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

Сначала полезный результат: превратить печать в строку

Старый шаблон уже умеет печатать квитанцию через echo. Теперь ту же квитанцию нужно передать в письмо или сохранить в кэше как строку. Переписывать каждую печать не обязательно: PHP может временно собирать вывод в буфере — области памяти — и затем отдать собранный текст переменной. Сначала получим этот результат всего тремя действиями.

<?php
declare(strict_types=1);

ob_start();
echo 'Квитанция: чай, 350 рублей';
$receipt = ob_get_clean();
echo 'Для письма: ', $receipt, "\n";

Для письма: Квитанция: чай, 350 рублей

Если вы сами пишете небольшую функцию, вернуть строку через return зачастую проще. Буфер особенно полезен на границе с уже печатающим шаблоном, диагностической функцией или старой библиотекой. Он не нужен вокруг каждого echo и не делает приложение автоматически быстрее. Перед дальнейшими опытами полезны вызов и результат функции и практика шаблонов и ответа.

Пользовательский буфер, SAPI и браузер — разные ступени

У запроса нет единственного волшебного буфера. PHP-код может открыть пользовательские буферы; ниже работает системный вывод выбранного SAPI — CLI, FastCGI, Apache и так далее. Ещё дальше свои решения принимают веб-сервер, прокси, транспорт и браузер. Операция на одном уровне не доказывает, что человек уже увидел текст.

Пользовательский буфер — не только строка: с ним связан обработчик, разрешённые операции и состояние. ob_start() без callback использует обработчик по умолчанию, который передаёт текст дальше без преобразования. Настройки php.ini могут открыть буфер ещё до первой инструкции файла; ob_start действует только с места своего вызова. Поэтому библиотека должна считать уже существующие уровни и не закрывать чужие.

Кроме захвата шаблона, буфер используют для повторного использования дорогого результата, выборочной обработки вывода готового компонента и подключения преобразований, которых нет на веб-сервере. Возможна ранняя отправка HTML head, чтобы браузер начал загружать ресурсы, пока строится body; такой маршрут допустим лишь когда дальнейшая работа уже не потребует изменить отправленный HTTP-статус или заголовки. Обычному приложению сначала полезнее собрать целый управляемый ответ.

При обычном окончании скрипта и при exit PHP закрывает оставшиеся уровни в обратном порядке, передавая их вывод наружу. Запрет REMOVABLE относится к операциям пользовательского кода и не предотвращает завершение буфера при shutdown. Если данные нельзя отправлять автоматически, приложение должно своевременно владеть их очисткой и завершением. Обработчик, возвращающий пустую строку, может подавлять обычный вывод при завершении, но ошибки обработчика имеют отдельные правила: это не граница конфиденциальности.

Установка, пять настроек и различия CLI / веб

Управление выводом входит в PHP Core: отдельный PECL-пакет для этих 16 функций не устанавливают. Конкретные преобразующие обработчики могут зависеть от расширений mbstring, iconv или zlib. Проверьте конфигурацию именно того SAPI, где работает сайт: CLI и веб могут читать разные ini-файлы. Области действия INI_PERDIR и INI_ALL нельзя заменить произвольным ini_set в любой точке приложения.

PHP также имеет специальный URL-Rewriter: максимум два внутренних экземпляра одновременно, отдельно для пользовательских пар и прозрачной передачи session ID. Расширение zlib может включить свой буфер через zlib.output_compression. Они используют тот же механизм пользовательских буферов, поэтому появляются в стеке рядом с вашим кодом. Значение On для zlib обычно соответствует порогу 16 KiB; это не общая настройка всех ob_start.

Кроме двух внутренних обработчиков default output handler и URL-Rewriter, документация перечисляет обработчики расширений: mb_output_handler, ob_gzhandler, ob_iconv_handler и ob_tidyhandler. Их наличие зависит от сборки/расширений, а имена не означают взаимозаменяемость. У URL-Rewriter порог равен 0 и через ob_start для него не выбирается: до обработки текст ограничен доступной PHP памятью.

<?php
declare(strict_types=1);

echo extension_loaded('Core') ? "Core доступен\n" : "Core недоступен\n";
echo function_exists('ob_start') ? "Захват вывода доступен\n" : "Нет функции\n";
$before = ob_get_level();
ob_start();
$opened = ob_get_level() === $before + 1;
ob_end_clean();
echo $opened ? "Свой уровень открыт и закрыт\n" : "Проверьте конфигурацию\n";

Core доступен
Захват вывода доступен
Свой уровень открыт и закрыт

Что попадает в буфер, а что проходит другим путём

Буфер перехватывает вывод, проходящий через обычный механизм вывода PHP: echo, print, printf, печать var_dump, HTML вне PHP-тегов и запись в php://output. Возвращаемое функцией значение само по себе не печать. HTTP-заголовки и cookies также не становятся частью текстового буфера. В CLI прямая запись в STDOUT или php://stdout обходит пользовательские ob-буферы.

<?php
declare(strict_types=1);

function makeLabel() { return 'Чай'; }
ob_start();
$name = makeLabel();
echo 'Товар: ', $name;
file_put_contents('php://output', ' / готов');
$text = ob_get_clean();
echo $text, "\n";

Товар: Чай / готов

<?php
declare(strict_types=1);

ob_start();
echo 'Собранный текст';
fwrite(STDOUT, "Прямое сообщение CLI\n");
$text = ob_get_clean();
echo 'Буфер: ', $text, "\n";

Прямое сообщение CLI
Буфер: Собранный текст

Диагностические сообщения PHP тоже могут попасть в обычный вывод, если это разрешено display_errors и error_reporting. Поэтому захват шаблона не гарантирует «чистый HTML»: предупреждение о неверном поле способно загрязнить письмо или JSON. Исправляйте ошибку и настраивайте отдельный журнал; не прячьте её через ob_clean как способ лечения. Разделение ошибок, показа и журналирования объясняет эту границу подробнее.

Вложенные шаблоны: кто владеет каким уровнем

Отчёт может открыть внешний буфер, а небольшой шаблон внутри него — свой. В каждый момент активен последний открытый уровень. Только когда внутренний уровень передал результат, внешний его получает. Это стек: последний вошёл — первый вышел. ob_get_level считает количество уровней начиная с одного; поле level в ob_get_status нумерует их начиная с нуля.

<?php
declare(strict_types=1);

ob_start();
echo 'Каталог: ';
ob_start();
echo 'чай';
$card = ob_get_clean();
echo '[', $card, ']';
$page = ob_get_clean();
echo $page, "\n";

Каталог: [чай]

Функции clean/end/get работают с активным уровнем, не ищут «буфер моей библиотеки» по имени. Не используйте while (ob_get_level()) ob_end_clean() внутри подключаемого шаблона: это уничтожает вывод владельца запроса. Проверка исходного уровня полезна, но не изолирует код, который сам закрывает чужой буфер и открывает новый на той же глубине. Договор о владении обязателен; полную песочницу счётчик не создаёт.

Порог обработки, байты, память и границы порций

chunk_size — порог запуска обработки по количеству байтов, а не вместимость строки. Значение 0 означает «не запускать автоматическую обработку из-за размера». При положительном значении PHP передаёт накопленное содержимое, когда оно достигло порога или превысило его. Один большой echo может дать обработчику порцию заметно больше порога; это не разбиение строго на одинаковые блоки.

<?php
declare(strict_types=1);

$sizes = [];
ob_start();
ob_start(function ($text, $phase) use (&$sizes) {
    $sizes[] = strlen($text);
    return strtoupper($text);
}, 4);
echo 'abcdef';
ob_end_flush();
$result = ob_get_clean();
echo $result, "\n", implode(',', $sizes), "\n";

ABCDEF
6,0

Единица здесь байт: UTF-8 буква может занимать несколько байтов. Буфер может закончиться посреди символа, HTML-тега или JSON-токена. Преобразование, рассчитанное на целый документ, нельзя автоматически применять независимо к каждой порции. Для такого преобразования нужны сохранение состояния между вызовами, корректная финализация и понимание формата; регулярная замена по любому чанку может пропустить границу.

Стандартный пользовательский буфер без положительного порога первоначально выделяет около 16 KiB. При явном пороге начальное выделение округляется вверх до кратного 4 KiB; затем при необходимости растёт. Это детали реализации PHP 8.5.11, а не бюджет памяти приложения. Снимок ob_get_contents, результат преобразования и внешний буфер могут одновременно удерживать дополнительные строки. Для огромного экспорта предпочтительнее поэлементная запись в файл/поток с подходящим API, чем сборка всего документа в RAM.

Clean, flush, end и get: таблица без путаницы

Сначала отделите три решения. Clean удаляет накопленное содержимое. Flush передаёт результат обработчика следующему уровню и опустошает активный буфер. End закрывает сам уровень. Get возвращает исходные накопленные байты в переменную, а не автоматически результат преобразующего callback. Названия комбинируют эти действия, но требования к разрешениям отличаются.

<?php
declare(strict_types=1);

ob_start();
ob_start(fn($text) => strtoupper($text));
echo 'tea';
$raw = ob_get_flush();
$processed = ob_get_clean();
echo $raw, '/', $processed, "\n";

tea/TEA

Callback: регистрация, вызов, два параметра и return

Callback — функция, которую позже вызывает PHP. Для обработчика вывода ей передают накопленный текст $buffer и битовую маску этапа $phase. Сам ob_start регистрирует обработчик; обычно он не вызывает его сразу. Обработчик возвращает новый текст, а не печатает его. Следующий пример преобразует маленький целый фрагмент, когда буфер закрывается.

<?php
declare(strict_types=1);

function markReceipt($buffer, $phase) {
    return '[' . $buffer . ']';
}
ob_start();
ob_start('markReceipt');
echo 'Квитанция';
ob_end_flush();
$text = ob_get_clean();
echo $text, "\n";

[Квитанция]

Далее допустимы замыкание, статический метод, callable-массив или вызываемый объект. Конкретный callback должен принимать строку и целочисленный этап; типизированный прикладной контракт удобно ограничить string|false, чтобы не зависеть от неявных преобразований. Если состояние нужно между порциями, используйте явно принадлежащее обработчику состояние. Не применяйте глобальный массив, случайно общий для нескольких экземпляров.

Если обработчик вызывается при shutdown, рабочая папка под некоторыми веб-серверами может отличаться от ожидаемой. Для файлов конфигурации/шаблонов заранее фиксируют абсолютный путь, например через __DIR__, и не выполняют в callback платёж или отправку заявки. Обработчик может запускаться несколько раз и на пустой строке: ни один его вызов не равен подтверждению бизнес-операции.

Этапы обработчика: START, WRITE, CLEAN, FLUSH, FINAL

Флаги этапа — независимые биты в числе. Оператор | объединяет флаги, & проверяет присутствие бита. START добавляется к первому фактическому вызову, FINAL — к последнему; между ними возможны WRITE, CLEAN и FLUSH. Поэтому сравнение phase === START теряет случай START | FINAL. WRITE равен нулю: проверять его через phase & WRITE бессмысленно.

<?php
declare(strict_types=1);

$events = [];
ob_start();
ob_start(function ($text, $phase) use (&$events) {
    $events[] = [$text, $phase];
    return strtoupper($text);
});
echo 'discard';
ob_clean();
echo 'send';
ob_flush();
echo 'last';
ob_end_flush();
$output = ob_get_clean();
foreach ($events as [$text, $phase]) {
    echo $text, ':', $phase, "\n";
}
echo 'Итог: ', $output, "\n";

discard:3
send:4
last:8
Итог: SENDLAST

Строка, false и неявные преобразования результата

Лучший прикладной обработчик явно возвращает строку. Но язык допускает и другие результаты, и у false особый смысл: исходный текст передаётся дальше, а сам обработчик помечается DISABLED. Это не команда «ничего не выводить». Пустая строка подавляет данную порцию, сохраняя обработчик активным.

<?php
declare(strict_types=1);

$calls = 0;
ob_start();
ob_start(function ($text) use (&$calls) {
    $calls++;
    return false;
});
echo 'first';
ob_flush();
echo 'second';
ob_end_flush();
$text = ob_get_clean();
echo $text, '/', $calls, "\n";

firstsecond/1

Если обработчик заменяет персональные данные или очищает HTML, ошибка не должна открывать путь к выдаче сырого содержимого. Удаляйте недопустимые данные до помещения в вывод и используйте подходящее экранирование в шаблоне. Буферизация меняет маршрут байтов, но не правила проверки входа и формирования безопасного ответа.

Разрешения, состояние и диагностика стека

У буфера есть ещё одна маска — flags из ob_get_status. В ней соединяются разрешения операций и состояние обработчика. Это другой набор значений, чем phase, который PHP передаёт callback. Разрешения задаются при ob_start; состояние меняет движок по мере работы.

С PHP 8.4 третий аргумент ob_start больше не задаёт статусные STARTED / DISABLED / PROCESSED: это не поддерживаемый способ пропустить инициализацию. Также с 8.4 DISABLED учитывается при ob_clean и ob_flush; до этого эти две операции могли снова вызывать отключённый обработчик. Не стройте новый код на старой лазейке. Поле flags может содержать и внутренние биты типа обработчика: проверяйте нужный бит, не сравнивайте всю маску с одним значением.

ob_get_status(false) описывает активный уровень: name, type, flags, level, chunk_size, buffer_size и buffer_used. true возвращает массив всех уровней от внешнего к внутреннему. buffer_used — байты текста; buffer_size — выделенная ёмкость. Имена closure в PHP 8.5.11 включают место определения и не обязаны быть одинаковыми между файлами. Для стабильного мониторинга нужны ваши собственные метки, а не парсинг отладочного имени.

Исключения, shutdown и пределы восстановления

Исключение в callback не откатывает уже переданное тело. Даже если вызывающий код поймал Throwable вокруг ob_flush, исходная порция может уже уйти во внешний буфер, а обработчик — стать DISABLED. Первое действие при ошибке — не обещать новый целый HTTP-ответ, а определить, что ещё принадлежит приложению и что действительно было отправлено.

<?php
declare(strict_types=1);

ob_start();
ob_start(function ($text) {
    throw new RuntimeException('Учебный сбой');
});
echo 'pending';
$caught = false;
try { ob_flush(); }
catch (RuntimeException $error) { $caught = true; }
$disabled = (ob_get_status()['flags'] & PHP_OUTPUT_HANDLER_DISABLED) !== 0;
echo 'after';
ob_end_flush();
$text = ob_get_clean();
echo $caught ? "Поймано\n" : "Не поймано\n";
echo $disabled ? "Обработчик отключён\n" : "Активен\n";
echo $text, "\n";

Поймано
Обработчик отключён
pendingafter

Точные форматы фатальных сообщений, путей и stderr различаются между средами. Учебные проверки отдельно фиксируют статус процесса, фазу и поток, не объявляя единый HTML ошибки переносимым. Журналируйте идентификатор операции и тип сбоя, не весь буфер с токенами, cookies или платёжными данными. В output handler не размещают транзакцию БД, списание денег или надёжную отправку уведомления: его жизненный цикл служит выводу.

Отправка заголовков и тела: где кончаются гарантии PHP

В CLI длительная команда может печатать этапы и вызывать flush. Для веба один такой вызов не доказывает немедленный показ: сначала нужно передать данные из всех принадлежащих вам пользовательских уровней, затем PHP/SAPI, затем инфраструктура. ob_implicit_flush автоматизирует только системную просьбу после печати. Пустая строка и один header не являются непустым блоком вывода; управляющий байт вроде перевода строки является.

Веб-SAPI обычно отправляет сначала заголовки, затем тело. Даже когда тело ещё удерживается внешним ob_start, явный flush может уже отправить заголовки: это отдельно подтверждено встроенным cli-server. С PHP 8.4 FastCGI поддерживает flush одних заголовков без тела. Слишком ранний сброс способен помешать сжимающему handler добавить нужные заголовки. Оставляйте Content-Type, статус и cookies на управляемом этапе до отправки; буферизация тела не возвращает заголовки назад после фактической отправки.

В изолированном тесте встроенного PHP-сервера можно проверить, что печать внутри активного буфера ещё позволяет задать заголовок, а после end_flush + flush заголовки уже отправлены. Это проверка конкретного cli-server, без reverse proxy, TLS или браузерного рендеринга. Для production streaming нужен отдельный тест реальной цепочки. Примеры карточек flush и ob_implicit_flush намеренно не имитируют скорость sleep или лишними пробелами.

Готовый обработчик на практике: ссылки и формы

Исторический URL-Rewriter полезен для понимания готового обработчика: приложение регистрирует пару name/value, печатает HTML, а handler меняет подходящие ссылки и формы при обработке. Это не парсер произвольного современного фронтенда и не механизм безопасности. При собственной генерации шаблона обычно яснее построить нужную ссылку явно и затем экранировать её в HTML-контексте.

Важен момент обработки: reset до flush уберёт пары и для ранее напечатанного, но ещё ожидающего HTML. После flush reset не меняет уже обработанную строку во внешнем буфере. Одноимённые пары добавляются, а не заменяют друг друга. Hidden input читатель может изменить; метка в URL попадает в историю и журналы. Примеры output_add_rewrite_var и output_reset_rewrite_vars используют вымышленные домены и несекретные метки, а не session ID.

Относительные ссылки переписываются по tag/attribute; абсолютные дополнительно ограничиваются host-настройкой. form= создаёт по скрытому input на пару. Типовой пример из официального раздела rewrite показывает именно такую обработку выхода; он не обещает, что любая строка, содержащая URL, будет изменена. В JS, CSS или текстовом письме такой механизм не заменяет явное построение данных.

Рабочая граница шаблона: результат, ошибка и владение

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

<?php
declare(strict_types=1);

function renderReceipt($product) {
    ob_start();
    try {
        require __DIR__ . '/receipt.php';
    } catch (Throwable $error) {
        ob_end_clean();
        throw $error;
    }
    return ob_get_clean();
}
$before = ob_get_level();
try { renderReceipt(''); }
catch (InvalidArgumentException $error) { echo "Квитанция не готова\n"; }
echo ob_get_level() === $before ? "Уровень восстановлен\n" : "Остался буфер\n";
echo renderReceipt('Чай & мёд'), "\n";

Квитанция не готова
Уровень восстановлен
<p>Чай &amp; мёд</p>

Кэширование такого текста — отдельное решение: ключ должен учитывать нужный контекст пользователя, языка и прав, а время жизни — изменения данных. Сам ob_get_clean не делает строку безопасной для общего кэша. Аналогично захваченная HTML-квитанция ещё не отправлена почтой и не превращена в PDF: это следующий явный шаг приложения.

• Для новой небольшой функции начните с return string, если перехватывать печать не требуется.
• Для готового печатающего шаблона захватывайте ровно его область и держите договор о владении уровнями.
• Для огромного экспорта не храните весь результат в памяти без обоснованного ограничения объёма.
• Для HTTP-прогресса тестируйте реальный серверный маршрут; не заменяйте договор протокола вызовом flush.

Все функции категории и следующий шаг

В категории 16 функций. Девять ранее разобранных карточек сохраняют свои адреса в главе «Буферизация вывода»; здесь приведён полный контракт и связанный маршрут. Выберите операцию по намерению, а затем проверьте её разрешения, побочные эффекты и обработку false.

Дальше: шаблоны и HTTP-ответ · системная обработка ошибок · callback и замыкания.