PHP: полный мануал с примерами, функциями и ООП

PHP 4.0.4+; примеры PHP 8.2+ · bz2 / libbzip2

bzcompress(string $data, int $block_size = 4, int $work_factor = 0): string|int

Уменьшить текст отчёта перед хранением или передачей. Результат — двоичная строка Bzip2, а не имя файла.

Вызов имя(...) передаёт значения функции; запятые разделяют аргументы. $name = ...; сохраняет результат, echo выводит его, а var_dump показывает также тип. "\n" — перевод строки. === false проверяет именно отказ, не пустой текст и не строку "0". Переменная; Вызов функции.

bzcompress(string $data, int $block_size = 4, int $work_factor = 0): string|int

Результат и ошибки. Сжатая строка либо целое число ошибки. Проверяйте is_string. С PHP 8.5 неверные диапазоны block_size/work_factor вызывают ValueError; в прежних версиях возможен числовой отказ библиотеки. Неподходящий тип аргумента даёт TypeError.

<?php
$packed = bzcompress('SKU-7;2');
var_dump(is_string($packed));
echo bzdecompress($packed), "\n";

bool(true)
SKU-7;2

Теперь вынесем упаковку повторяющегося отчёта в функцию: return возвращает строку вызывающему коду, а is_string отделяет её от кода ошибки. str_repeat повторяет учебную строку, strlen считает байты.

<?php
function packReport($text) {
    $packed = bzcompress($text, 9, 0);
    if (!is_string($packed)) {
        throw new RuntimeException('Ошибка сжатия: ' . $packed);
    }
    return $packed;
}
$csv = str_repeat("SKU-7;2\n", 100);
$packed = packReport($csv);
var_dump(strlen($packed) < strlen($csv));
var_dump(bzdecompress($packed) === $csv);
var_dump(bzcompress($csv, 4, 0) === bzcompress($csv, 4, 30));

bool(true)
bool(true)
bool(true)

<?php
foreach ([[0, 0], [4, 251]] as [$block, $work]) {
    try { bzcompress('report', $block, $work); }
    catch (ValueError $error) { echo "Неверная настройка\n"; }
}

Неверная настройка
Неверная настройка

Границы применения. Вход и выход одновременно занимают память; это не потоковая обработка большого файла. При больших выгрузках используйте bzopen/bzwrite. Не путайте Bzip2 с gzip, zlib и ZIP: принимающая сторона должна ожидать тот же формат.

Связанные действия: bzdecompress(), bzopen(), bzwrite().

• bzcompress
• Контроль поведения: PHP 8.5.11 ext/bz2

PHP 4.0.4+; примеры PHP 8.2+ · bz2 / libbzip2

bzdecompress(string $data, bool $use_less_memory = false): string|int|false

Вернуть исходные байты из небольшой сжатой строки, например из сохранённого отчёта.

Вызов имя(...) передаёт значения функции; запятые разделяют аргументы. $name = ...; сохраняет результат, echo выводит его, а var_dump показывает также тип. "\n" — перевод строки. === false проверяет именно отказ, не пустой текст и не строку "0". Переменная; Вызов функции.

bzdecompress(string $data, bool $use_less_memory = false): string|int|false

Результат и ошибки. Строка, false или целый код ошибки. Пустая строка и "0" допустимы, поэтому if (!$result) неверно. Успешный тип сам по себе не доказывает полноту произвольного внешнего входа: поведение обрезанного потока разобрано ниже.

<?php
$text = bzdecompress(bzcompress('0'));
var_dump(is_string($text));
echo $text, "\n";

bool(true)
0

<?php
$bad = bzdecompress('not a bzip2 stream');
echo is_string($bad) ? "Текст\n" : "Отказ\n";
$packed = bzcompress("id;total\n7;450\n");
var_dump(bzdecompress($packed, true) === bzdecompress($packed, false));

Отказ
bool(true)

Две независимые границы: PHP 8.5.11/libbzip2 1.0.8 возвращает только первый поток при склейке двух Bzip2-потоков; на данном обрезанном входе возвращает часть текста. Не переносите на этот вызов поведение утилиты bunzip2 для нескольких потоков.

<?php
$joined = bzcompress('ONE') . bzcompress('TWO');
echo bzdecompress($joined), "\n";
$original = str_repeat('A', 10000);
$truncated = substr(bzcompress($original), 0, -10);
$result = bzdecompress($truncated);
var_dump(is_string($result));
var_dump(is_string($result) && strlen($result) < strlen($original));

ONE
bool(true)
bool(true)

Границы применения. Весь распакованный результат создаётся в памяти. У малого входа может быть большой выход. Функция не даёт лимита результата или универсальной проверки, что потреблены все входные байты; для внешнего импорта нужны ограничения и отдельный договор целостности.

Связанные действия: bzcompress(), bzopen(), bzread(), bzerror().

• bzdecompress
• Контроль поведения: PHP 8.5.11 ext/bz2

PHP 4.0.4+; примеры PHP 8.2+ · bz2 / libbzip2

bzopen(string|resource $file, string $mode): resource|false

Открыть файл .bz2 так, чтобы последующие чтения и записи работали с обычным текстом.

Вызов имя(...) передаёт значения функции; запятые разделяют аргументы. $name = ...; сохраняет результат, echo выводит его, а var_dump показывает также тип. "\n" — перевод строки. === false проверяет именно отказ, не пустой текст и не строку "0". Переменная; Вызов функции.

bzopen возвращает ресурс — временный указатель на открытый поток, либо false при отказе. Это не содержимое файла. if (...) { ... } выбирает ветку; throw new RuntimeException(...) останавливает обычный путь с описанием ошибки. В try { ... } finally { bzclose($handle); } блок finally освобождает поток даже при исключении, но не подавляет ошибку. Потоки и позиция чтения; Обработка ошибки.

bzopen(string|resource $file, string $mode): resource|false

Результат и ошибки. Ресурс либо false, например при невозможности открыть путь; операция открытия может выдать warning. Ошибочный режим в PHP 8.5.11 вызывает ValueError. Неподходящий ресурс/режим исходного потока тоже проверяется. Не рассчитывайте, что все ошибки представляются только false.

<?php
$handle = bzopen('report.bz2', 'w');
if ($handle === false) { throw new RuntimeException('Не открыт файл'); }
bzwrite($handle, 'REPORT');
bzclose($handle);
$handle = bzopen('report.bz2', 'r');
if ($handle === false) { throw new RuntimeException('Не открыт файл'); }
try { echo bzread($handle), "\n"; }
finally { bzclose($handle); }

REPORT

<?php
file_put_contents('source.bz2', bzcompress('INVOICE'));
$raw = fopen('source.bz2', 'rb');
if ($raw === false) { throw new RuntimeException('Не открыт источник'); }
$compressed = bzopen($raw, 'r');
if ($compressed === false) { fclose($raw); throw new RuntimeException('Нет Bzip2-потока'); }
try { echo bzread($compressed), "\n"; }
finally { bzclose($compressed); }
var_dump(is_resource($raw));

INVOICE
bool(false)

Границы применения. Переданный файловый поток должен стоять в начале нужного сжатого потока; предварительное чтение заголовка сдвигает позицию. Режим чтения файла не подтверждает корректность Bzip2: неверный формат часто обнаруживается только при bzread. Для потоковых обёрток см. схемы и контексты.

Связанные действия: bzread(), bzwrite(), bzclose(), bzerror().

• bzopen
• Контроль поведения: PHP 8.5.11 ext/bz2

PHP 4.0.4+; примеры PHP 8.2+ · bz2 / libbzip2

bzread(resource $bz, int $length = 1024): string|false

Прочитать порцию распакованных байтов из файла, не собирая весь результат сразу.

Вызов имя(...) передаёт значения функции; запятые разделяют аргументы. $name = ...; сохраняет результат, echo выводит его, а var_dump показывает также тип. "\n" — перевод строки. === false проверяет именно отказ, не пустой текст и не строку "0". Переменная; Вызов функции.

bzopen возвращает ресурс — временный указатель на открытый поток, либо false при отказе. Это не содержимое файла. if (...) { ... } выбирает ветку; throw new RuntimeException(...) останавливает обычный путь с описанием ошибки. В try { ... } finally { bzclose($handle); } блок finally освобождает поток даже при исключении, но не подавляет ошибку. Потоки и позиция чтения; Обработка ошибки.

bzread(resource $bz, int $length = 1024): string|false

Результат и ошибки. Строка либо false при ошибке. Конец корректного потока даёт пустую строку; сверяйте bzerror, поскольку EOF бывает также на повреждённом входе. Длина измеряется в байтах, граница порции может пройти посередине UTF-8 символа или CSV-строки.

<?php
file_put_contents('letters.bz2', bzcompress('ABCDEF'));
$handle = bzopen('letters.bz2', 'r');
if ($handle === false) { throw new RuntimeException('Не открыт файл'); }
try {
    echo bzread($handle, 2), "\n";
    echo bzread($handle, 2), "\n";
} finally { bzclose($handle); }

AB
CD

while (true) повторяет действия, break останавливает цикл; += увеличивает счётчик. Проверяем ошибку до использования порции. Циклы и выход.

<?php
file_put_contents('batch.bz2', bzcompress(str_repeat('A', 10000)));
$handle = bzopen('batch.bz2', 'r');
if ($handle === false) { throw new RuntimeException('Не открыт файл'); }
$total = 0;
try {
    while (true) {
        $chunk = bzread($handle, 4096);
        $error = bzerror($handle);
        if ($chunk === false || $error['errno'] !== 0) {
            throw new RuntimeException('Ошибка Bzip2: ' . $error['errstr']);
        }
        if ($chunk === '') { break; }
        if (strlen($chunk) > 12000 - $total) {
            throw new RuntimeException('Лимит распаковки');
        }
        $total += strlen($chunk);
    }
} finally { bzclose($handle); }
echo $total, "\n";

10000

Границы применения. Короткая порция сама по себе не доказывает конец. Для данных вне доверенного источника ограничивают также размер входа, длительность задачи и область записи; завершённые бизнес-изменения делают после проверки всего документа. feof без проверки ошибки недостаточен.

Связанные действия: bzopen(), bzerror(), bzclose().

• bzread
• Контроль поведения: PHP 8.5.11 ext/bz2

PHP 4.0.4+; примеры PHP 8.2+ · bz2 / libbzip2

bzwrite(resource $bz, string $data, ?int $length = null): int|false

Передать обычные байты в открытый Bzip2-файл; сжатие выполняется внутри потока.

Вызов имя(...) передаёт значения функции; запятые разделяют аргументы. $name = ...; сохраняет результат, echo выводит его, а var_dump показывает также тип. "\n" — перевод строки. === false проверяет именно отказ, не пустой текст и не строку "0". Переменная; Вызов функции.

bzopen возвращает ресурс — временный указатель на открытый поток, либо false при отказе. Это не содержимое файла. if (...) { ... } выбирает ветку; throw new RuntimeException(...) останавливает обычный путь с описанием ошибки. В try { ... } finally { bzclose($handle); } блок finally освобождает поток даже при исключении, но не подавляет ошибку. Потоки и позиция чтения; Обработка ошибки.

bzwrite(resource $bz, string $data, ?int $length = null): int|false

Результат и ошибки. Количество принятых исходных байтов, либо false. Сравнивайте с длиной переданного фрагмента; 0 — не false и не означает успешную запись непустого фрагмента. Это алиас потоковой записи fwrite в реализации PHP.

<?php
$handle = bzopen('prefix.bz2', 'w');
if ($handle === false) { throw new RuntimeException('Не открыт файл'); }
try { echo bzwrite($handle, 'ABCDEF', 3), "\n"; }
finally { bzclose($handle); }
echo bzdecompress(file_get_contents('prefix.bz2')), "\n";

3
ABC

Следующий пример использует массив строк и foreach: каждая строка целиком передаётся одной операцией. При неполной записи выбран отказ, а не скрытое принятие повреждённого отчёта.

<?php
$lines = ["id;qty\n", "7;2\n", "9;1\n"];
$handle = bzopen('stock.bz2', 'w');
if ($handle === false) { throw new RuntimeException('Не открыт файл'); }
try {
    foreach ($lines as $line) {
        if (bzwrite($handle, $line) !== strlen($line)) {
            throw new RuntimeException('Неполная запись');
        }
    }
} finally { bzclose($handle); }
echo bzdecompress(file_get_contents('stock.bz2'));

id;qty
7;2
9;1

Границы применения. Закрытие завершает сжатый поток. Не открывайте заново тот же путь с w для каждой строки: старое содержимое будет обнулено. Не считайте bzflush способом сделать промежуточный файл завершённым.

Связанные действия: bzopen(), bzclose(), bzflush(), bzcompress().

• bzwrite
• Контроль поведения: PHP 8.5.11 ext/bz2

PHP 4.0.4+; примеры PHP 8.2+ · bz2 / libbzip2

bzclose(resource $bz): bool

Завершить работу с ресурсом; для пишущего потока закончить формирование .bz2.

Вызов имя(...) передаёт значения функции; запятые разделяют аргументы. $name = ...; сохраняет результат, echo выводит его, а var_dump показывает также тип. "\n" — перевод строки. === false проверяет именно отказ, не пустой текст и не строку "0". Переменная; Вызов функции.

bzopen возвращает ресурс — временный указатель на открытый поток, либо false при отказе. Это не содержимое файла. if (...) { ... } выбирает ветку; throw new RuntimeException(...) останавливает обычный путь с описанием ошибки. В try { ... } finally { bzclose($handle); } блок finally освобождает поток даже при исключении, но не подавляет ошибку. Потоки и позиция чтения; Обработка ошибки.

bzclose(resource $bz): bool

Результат и ошибки. true при успешном закрытии, false при отказе. Закрытый или неподходящий ресурс может вызвать TypeError. true не является доказательством физической сохранности диска или полноты исходного бизнес-документа.

<?php
$handle = bzopen('ready.bz2', 'w');
if ($handle === false) { throw new RuntimeException('Не открыт файл'); }
bzwrite($handle, 'READY');
var_dump(bzclose($handle));
var_dump(is_resource($handle));
echo bzdecompress(file_get_contents('ready.bz2')), "\n";

bool(true)
bool(false)
READY

<?php
file_put_contents('report.bz2', bzcompress('wrong-header'));
$handle = bzopen('report.bz2', 'r');
if ($handle === false) { throw new RuntimeException('Не открыт файл'); }
try {
    try {
        if (bzread($handle) !== 'id;qty') {
            throw new RuntimeException('Неверный заголовок');
        }
    } finally { bzclose($handle); }
} catch (RuntimeException $error) {
    echo $error->getMessage(), "\n";
}
var_dump(is_resource($handle));

Неверный заголовок
bool(false)

Границы применения. Состояние bzerror считывайте до закрытия. При передаче в bzopen существующего файлового ресурса закрытие обёртки закрывает также исходный ресурс в проверенной реализации. Закрывать дважды не нужно.

Связанные действия: bzopen(), bzerror(), bzflush().

• bzclose
• Контроль поведения: PHP 8.5.11 ext/bz2

PHP 4.0.4+; примеры PHP 8.2+ · bz2 / libbzip2

bzflush(resource $bz): bool

Распознать ограничение старого совместимого API: этот вызов не делает полезной принудительной выгрузки Bzip2-буфера.

Вызов имя(...) передаёт значения функции; запятые разделяют аргументы. $name = ...; сохраняет результат, echo выводит его, а var_dump показывает также тип. "\n" — перевод строки. === false проверяет именно отказ, не пустой текст и не строку "0". Переменная; Вызов функции.

bzopen возвращает ресурс — временный указатель на открытый поток, либо false при отказе. Это не содержимое файла. if (...) { ... } выбирает ветку; throw new RuntimeException(...) останавливает обычный путь с описанием ошибки. В try { ... } finally { bzclose($handle); } блок finally освобождает поток даже при исключении, но не подавляет ошибку. Потоки и позиция чтения; Обработка ошибки.

bzflush(resource $bz): bool

Результат и ошибки. Булев результат вызова. Официальная документация прямо отмечает: библиотечный BZ2_bzflush ничего не делает. true нельзя трактовать как готовность файла к чтению, завершение потока или гарантию сохранения на диск.

<?php
$handle = bzopen('flush.bz2', 'w');
if ($handle === false) { throw new RuntimeException('Не открыт файл'); }
bzwrite($handle, 'ABC');
var_dump(bzflush($handle));
bzclose($handle);
echo bzdecompress(file_get_contents('flush.bz2')), "\n";

bool(true)
ABC

<?php
$handle = bzopen('parts.bz2', 'w');
if ($handle === false) { throw new RuntimeException('Не открыт файл'); }
try {
    bzwrite($handle, "part-1\n");
    bzflush($handle);
    bzwrite($handle, "part-2\n");
} finally { bzclose($handle); }
echo bzdecompress(file_get_contents('parts.bz2'));

part-1
part-2

Границы применения. Не переносите обещания fflush обычного потока на эту обёртку. Если читатель должен видеть обновления в реальном времени, выберите иной протокол/несжатый журнал либо закрывайте отдельные сжатые части.

Связанные действия: bzclose(), bzwrite().

• bzflush
• Контроль поведения: PHP 8.5.11 ext/bz2

PHP 4.0.4+; примеры PHP 8.2+ · bz2 / libbzip2

bzerrno(resource $bz): int

Получить числовой код последней ошибки потока и выбрать ветку обработки.

Вызов имя(...) передаёт значения функции; запятые разделяют аргументы. $name = ...; сохраняет результат, echo выводит его, а var_dump показывает также тип. "\n" — перевод строки. === false проверяет именно отказ, не пустой текст и не строку "0". Переменная; Вызов функции.

bzopen возвращает ресурс — временный указатель на открытый поток, либо false при отказе. Это не содержимое файла. if (...) { ... } выбирает ветку; throw new RuntimeException(...) останавливает обычный путь с описанием ошибки. В try { ... } finally { bzclose($handle); } блок finally освобождает поток даже при исключении, но не подавляет ошибку. Потоки и позиция чтения; Обработка ошибки.

bzerrno(resource $bz): int

Результат и ошибки. Целое число: 0 означает отсутствие ошибки, отрицательное — отказ. Это не число прочитанных байтов и не HTTP-код. Если bzopen вернул false, диагностического ресурса ещё нет: эту функцию не вызывают.

<?php
file_put_contents('ok.bz2', bzcompress('OK'));
$handle = bzopen('ok.bz2', 'r');
if ($handle === false) { throw new RuntimeException('Не открыт файл'); }
try {
    bzread($handle);
    echo bzerrno($handle), "\n";
} finally { bzclose($handle); }

0

Теперь имя заканчивается .bz2, но содержимое обычное. bzopen смог открыть файл; ошибка формата появилась при bzread. Результат чтения не используют до проверки состояния.

<?php
file_put_contents('fake.bz2', 'ordinary report');
$handle = bzopen('fake.bz2', 'r');
if ($handle === false) { throw new RuntimeException('Не открыт файл'); }
try {
    bzread($handle);
    echo bzerrno($handle) === -5 ? "Неверный формат\n" : "Другая ошибка\n";
} finally { bzclose($handle); }

Неверный формат

Границы применения. Считайте состояние сразу после операции и до bzclose. В PHP эти имена библиотечных ошибок не экспортированы как BZ_* константы. Таблица кодов есть в разделе диагностики. Код 0 после конца чтения не доказывает отсутствие лишних байтов/второго сжатого потока после первого.

Связанные действия: bzerrstr(), bzerror(), bzread().

• bzerrno
• Контроль поведения: PHP 8.5.11 ext/bz2

PHP 4.0.4+; примеры PHP 8.2+ · bz2 / libbzip2

bzerrstr(resource $bz): string

Получить техническое описание ошибки для внутренней диагностики.

Вызов имя(...) передаёт значения функции; запятые разделяют аргументы. $name = ...; сохраняет результат, echo выводит его, а var_dump показывает также тип. "\n" — перевод строки. === false проверяет именно отказ, не пустой текст и не строку "0". Переменная; Вызов функции.

bzopen возвращает ресурс — временный указатель на открытый поток, либо false при отказе. Это не содержимое файла. if (...) { ... } выбирает ветку; throw new RuntimeException(...) останавливает обычный путь с описанием ошибки. В try { ... } finally { bzclose($handle); } блок finally освобождает поток даже при исключении, но не подавляет ошибку. Потоки и позиция чтения; Обработка ошибки.

bzerrstr(resource $bz): string

Результат и ошибки. Строка технического состояния, например OK или DATA_ERROR_MAGIC. Она не предназначена для прямого сообщения пользователю и не заменяет проверку кода. Если bzopen вернул false, диагностического ресурса ещё нет: эту функцию не вызывают.

<?php
file_put_contents('ok.bz2', bzcompress('OK'));
$handle = bzopen('ok.bz2', 'r');
if ($handle === false) { throw new RuntimeException('Не открыт файл'); }
try {
    bzread($handle);
    echo bzerrstr($handle), "\n";
} finally { bzclose($handle); }

OK

Теперь имя заканчивается .bz2, но содержимое обычное. bzopen смог открыть файл; ошибка формата появилась при bzread. Результат чтения не используют до проверки состояния.

<?php
file_put_contents('fake.bz2', 'ordinary report');
$handle = bzopen('fake.bz2', 'r');
if ($handle === false) { throw new RuntimeException('Не открыт файл'); }
try {
    bzread($handle);
    echo bzerrstr($handle), "\n";
} finally { bzclose($handle); }

DATA_ERROR_MAGIC

Границы применения. Считайте состояние сразу после операции и до bzclose. В PHP эти имена библиотечных ошибок не экспортированы как BZ_* константы. Таблица кодов есть в разделе диагностики. Код 0 после конца чтения не доказывает отсутствие лишних байтов/второго сжатого потока после первого.

Связанные действия: bzerrno(), bzerror(), bzread().

• bzerrstr
• Контроль поведения: PHP 8.5.11 ext/bz2

PHP 4.0.4+; примеры PHP 8.2+ · bz2 / libbzip2

bzerror(resource $bz): array

Получить код и описание одной ошибочной операции вместе.

Вызов имя(...) передаёт значения функции; запятые разделяют аргументы. $name = ...; сохраняет результат, echo выводит его, а var_dump показывает также тип. "\n" — перевод строки. === false проверяет именно отказ, не пустой текст и не строку "0". Переменная; Вызов функции.

bzopen возвращает ресурс — временный указатель на открытый поток, либо false при отказе. Это не содержимое файла. if (...) { ... } выбирает ветку; throw new RuntimeException(...) останавливает обычный путь с описанием ошибки. В try { ... } finally { bzclose($handle); } блок finally освобождает поток даже при исключении, но не подавляет ошибку. Потоки и позиция чтения; Обработка ошибки.

bzerror(resource $bz): array

Результат и ошибки. Ассоциативный массив с errno (int) и errstr (string). Ключи читают через квадратные скобки: $error['errno']. Массив сам по себе не булев признак ошибки. Если bzopen вернул false, диагностического ресурса ещё нет: эту функцию не вызывают.

<?php
file_put_contents('ok.bz2', bzcompress('OK'));
$handle = bzopen('ok.bz2', 'r');
if ($handle === false) { throw new RuntimeException('Не открыт файл'); }
try {
    bzread($handle);
    $error = bzerror($handle);
echo $error['errno'], ":", $error['errstr'], "\n";
} finally { bzclose($handle); }

0:OK

Теперь имя заканчивается .bz2, но содержимое обычное. bzopen смог открыть файл; ошибка формата появилась при bzread. Результат чтения не используют до проверки состояния.

<?php
file_put_contents('fake.bz2', 'ordinary report');
$handle = bzopen('fake.bz2', 'r');
if ($handle === false) { throw new RuntimeException('Не открыт файл'); }
try {
    bzread($handle);
    $error = bzerror($handle);
echo $error['errno'], ":", $error['errstr'], "\n";
} finally { bzclose($handle); }

-5:DATA_ERROR_MAGIC

Границы применения. Считайте состояние сразу после операции и до bzclose. В PHP эти имена библиотечных ошибок не экспортированы как BZ_* константы. Таблица кодов есть в разделе диагностики. Код 0 после конца чтения не доказывает отсутствие лишних байтов/второго сжатого потока после первого.

Связанные действия: bzerrno(), bzerrstr(), bzread().

• bzerror
• Контроль поведения: PHP 8.5.11 ext/bz2