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

<?php
declare(strict_types=1);

ob_start();
echo '<p>Заказ готов</p>';
$html = ob_get_clean();
echo 'Получено: ', $html, "\n";

Получено: <p>Заказ готов</p>

Никакого браузера для первого опыта не нужно. echo между вызовами попал в буфер, а первый видимый вывод сделан после его закрытия. Если код сразу умеет вернуть строку, дополнительный буфер может быть не нужен.

<?php
declare(strict_types=1);

function renderReceipt(string $product): string
{
    ob_start();
    try {
        require 'receipt.php';
    } catch (Throwable $error) {
        ob_end_clean();
        throw $error;
    }
    $html = ob_get_clean();
    if ($html === false) { throw new RuntimeException('Буфер потерян'); }
    return $html;
}
echo renderReceipt('Чай <мятный>'), "\n";

<p>Чай &lt;мятный&gt;</p>

Файл fixture известен разработчику, не приходит из запроса. htmlspecialchars защищает вставку в HTML; сам буфер ничего не экранирует. В примере договор шаблона запрещает ему открывать/закрывать чужие буферы. Обработка ошибки очищает принадлежащий этой функции буфер; общий случай нарушения уровней разобран отдельно.

<?php
declare(strict_types=1);

$sizes = [];
ob_start(static function (string $buffer, int $phase) use (&$sizes): string {
    $sizes[] = strlen($buffer);
    return '';
}, 3);
echo 'ab';
echo 'cdef';
echo 'g';
ob_end_flush();
echo implode(', ', $sizes), "\n";

6, 1

Первые два echo вместе накопили шесть байт, хотя порог равен трём. Последний один байт обработан при завершении. Возврат пустой строки сознательно не передаёт исходный текст наружу; callback только записывает длины в локальный массив.

<?php
declare(strict_types=1);

ob_start();
echo '<strong>Sale</strong>';
$html=ob_get_clean();
echo strlen($html)." bytes\n";

21 bytes

Компонент не отправлен непосредственно, его можно включить в письмо или проверить тестом.

<?php
declare(strict_types=1);

function legacyBadge(): void { echo 'stock:3'; }
ob_start();
legacyBadge();
$badge=ob_get_clean();
echo strtoupper($badge)."\n";

STOCK:3

Адаптер превращает печатающую функцию в значение. Сама legacy-функция не должна управлять внешними буферами.

<?php
declare(strict_types=1);

ob_start();
echo '<p>Чай</p>';
$html = ob_get_clean();
echo $html, ' | ', $html, "\n";

<p>Чай</p> | <p>Чай</p>

Один раз сформировали строку и дважды использовали её. Повторной работы генератора не было. Печатаем после закрытия, поэтому случайно не дописываем копию в исходный буфер.

<?php
declare(strict_types=1);

$phases = [];
ob_start(static function (string $buffer, int $phase) use (&$phases): string {
    $phases[] = $phase;
    return strtoupper($buffer);
});
echo 'tea';
$raw = ob_get_clean();
echo $raw, "\n";
var_dump(($phases[0] & PHP_OUTPUT_HANDLER_CLEAN) !== 0,
         ($phases[0] & PHP_OUTPUT_HANDLER_FINAL) !== 0);

tea
bool(true)
bool(true)

Callback действительно исполнился, но его TEA отброшено. Возвращается снимок исходного tea. Фраза «handler не работает с get_clean» неверна: он работает, но результат его преобразования не является результатом функции.

<?php
declare(strict_types=1);

$notices = 0;
set_error_handler(static function (int $level, string $message) use (&$notices): bool {
    if ($level === E_NOTICE) { ++$notices; return true; }
    return false;
});
$base = ob_get_level();
ob_start(static fn(string $buffer, int $phase): string => '', 0, 0);
echo 'kept';
$result = ob_get_clean();
$stillActive = ob_get_level() === $base + 1;
restore_error_handler();
fwrite(STDOUT, ($result === 'kept' && $stillActive && $notices > 0)
    ? "Строка получена, но буфер не закрыт\n" : "Иное поведение\n");

Строка получена, но буфер не закрыт

Узкий опыт PHP8.5.11: функция сначала получает текст, затем не может удалить non-removable буфер. fwrite(STDOUT) намеренно обходит его, чтобы показать результат; при shutdown handler возвращает пустую строку и ничего лишнего не печатает. Так защищённые буферы не создают в обычном render: это опыт границы контракта.

<?php
declare(strict_types=1);

ob_start();
$html=ob_get_clean();
echo $html === '' ? "valid empty component\n" : "unexpected\n";

valid empty component

Отсутствие разметки может быть правильным результатом условного блока.

<?php
declare(strict_types=1);

ob_start();
echo "sku,quantity\nbook,2\n";
$csv=ob_get_clean();
echo substr_count($csv,"\n")." rows\n";

2 rows

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

<?php
declare(strict_types=1);

ob_start();
echo 'Заказ';
$first = ob_get_contents();
echo ' готов';
$second = ob_get_contents();
ob_end_clean();
echo $first, ' | ', $second, "\n";

Заказ | Заказ готов

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

<?php
declare(strict_types=1);

$calls = 0;
ob_start(static function (string $buffer, int $phase) use (&$calls): string {
    ++$calls;
    return strtoupper($buffer);
});
echo 'tea';
$snapshot = ob_get_contents();
$callsBeforeClean = $calls;
ob_end_clean();
echo $snapshot, '/', $callsBeforeClean, '/', $calls, "\n";

tea/0/1

Чтение не вызвало callback; очистка при закрытии вызвала, но отбросила его результат. Поэтому снимок содержит tea, а не TEA. Для получения обработанного результата используйте внешний буфер и flush внутреннего, либо явную функцию преобразования строки.

<?php
declare(strict_types=1);

ob_start();
echo 'A';
$first=ob_get_contents();
echo 'B';
$all=ob_get_clean();
echo $first.'|'.$all."\n";

A|AB

Чтение снимка не остановило дальнейшее накопление.

<?php
declare(strict_types=1);

ob_start();
echo 'catalog';
$length=strlen(ob_get_contents());
ob_end_clean();
echo $length." bytes\n";

7 bytes

Буфер отброшен после измерения. Для большого потока лучше не получать полную копию ради подсчёта.

<?php
declare(strict_types=1);

$base = ob_get_level();
ob_start(); $outer = ob_get_level();
ob_start(); $inner = ob_get_level();
$statusLevel = ob_get_status()['level'];
ob_end_clean(); ob_end_clean();
echo $outer - $base, '/', $inner - $base, "\n";
var_dump($statusLevel === $inner - 1, ob_get_level() === $base);

1/2
bool(true)
bool(true)

ob_get_level считает первый уровень как 1, status[level] — как 0. Разность с base не зависит от того, был ли внешний буфер до вызова.

<?php
declare(strict_types=1);

ob_start();
echo 'Внешняя часть; ';
$base = ob_get_level();
ob_start();
try {
    echo 'Незавершённая карточка';
    throw new RuntimeException('Учебный отказ');
} catch (RuntimeException) {
    if (ob_get_level() !== $base + 1) { throw new LogicException('Шаблон нарушил договор буферов'); }
    ob_end_clean();
    echo 'Карточка недоступна';
}
$page = ob_get_clean();
echo $page, "\n";

Внешняя часть; Карточка недоступна

Мы точно знаем: шаблон не управляет буферами и наш уровень removable. Проверка обнаруживает нарушение числа уровней, но не доказывает identity буфера: чужой код мог закрыть один и создать другой. Не используйте это как sandbox для недоверенного PHP.

<?php
declare(strict_types=1);

$base=ob_get_level();
ob_start();
ob_start();
$depth=ob_get_level()-$base;
ob_end_clean();
ob_end_clean();
echo $depth." own levels\n";

2 own levels

Сравнение с исходным уровнем работает и внутри чужого рендерера.

<?php
declare(strict_types=1);

$base=ob_get_level();
try { ob_start(); echo 'partial'; throw new RuntimeException(); }
catch (RuntimeException) {}
finally { while (ob_get_level()>$base) ob_end_clean(); }
echo "clean response\n";

clean response

Частичный вывод не просочился в ответ. Контракт запрещает неудаляемые или чужие буферы внутри блока.

<?php
declare(strict_types=1);

ob_start();
echo 'Черновик';
$cleaned = ob_clean();
echo 'Готово';
$text = ob_get_clean();
var_dump($cleaned);
echo $text, "\n";

bool(true)
Готово

Буфер после ob_clean продолжает существовать. Мы забрали новую надпись отдельным ob_get_clean; старая не попала в результат.

<?php
declare(strict_types=1);

$notices = 0;
set_error_handler(static function (int $level, string $message) use (&$notices): bool {
    if ($level === E_NOTICE) { ++$notices; return true; }
    return false;
});
ob_start(null, 0, PHP_OUTPUT_HANDLER_REMOVABLE);
echo 'Содержимое';
$cleaned = ob_clean();
$saved = ob_get_contents();
$ended = ob_end_clean();
restore_error_handler();
var_dump($cleaned, $ended);
echo $saved, '/', $notices > 0 ? 'Был notice' : 'Без notice', "\n";

bool(false)
bool(true)
Содержимое/Был notice

CLEANABLE отсутствует, поэтому ob_clean отказал и не стёр данные. REMOVABLE присутствует: ob_end_clean затем закрывает и очищает буфер. Это два разных разрешения, а не общий флаг «можно удалить текст».

<?php
declare(strict_types=1);

ob_start();
echo 'draft';
ob_clean();
echo 'final';
$result=ob_get_clean();
echo $result."\n";

final

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

<?php
declare(strict_types=1);

ob_start();
echo 'debug noise';
ob_clean();
$stillActive=ob_get_level()>0;
ob_end_clean();
echo $stillActive ? "buffer remained active\n" : "closed\n";

buffer remained active

Показано отличие очистки от завершения. Лучше удалить отладочный echo из самой функции.

<?php
declare(strict_types=1);

ob_start();
echo '<p>Незавершённая карточка';
$discarded = ob_end_clean();
var_dump($discarded);
echo "Показать запасной блок\n";

bool(true)
Показать запасной блок

Внешнему потребителю не достался незакрытый тег. Это локальная подготовка текста; уже выполненные действия генератора буфер не отменяет.

<?php
declare(strict_types=1);

ob_start();
echo 'Шапка | ';
ob_start();
echo 'Ошибочная карточка';
ob_end_clean();
echo 'Запасная карточка';
$page = ob_get_clean();
echo $page, "\n";

Шапка | Запасная карточка

Закрыт только последний буфер. Внешняя шапка не была стёрта; последующий echo попал во внешний уровень. Поэтому while (ob_get_level()) без знания владельцев — неверный универсальный cleanup библиотеки.

<?php
declare(strict_types=1);

ob_start();
echo '<p>unfinished';
ob_end_clean();
echo "fallback\n";

fallback

Клиент получает только альтернативный ответ.

<?php
declare(strict_types=1);

ob_start(); echo 'page:';
ob_start(); echo 'private debug';
ob_end_clean();
echo 'ok';
$html=ob_get_clean();
echo $html."\n";

page:ok

Внешний буфер сохранён, внутренний отброшен.

<?php
declare(strict_types=1);

ob_start();
ob_start();
echo 'Часть1; ';
$flushed = ob_flush();
$remaining = ob_get_length();
echo 'Часть2';
ob_end_flush();
$whole = ob_get_clean();
var_dump($flushed, $remaining);
echo $whole, "\n";

bool(true)
int(0)
Часть1; Часть2

После первого flush данные уже во внешнем буфере, а внутренний пуст. Следующий echo остаётся в том же внутреннем уровне. Внешний буфер позволил увидеть весь результат без HTTP.

<?php
declare(strict_types=1);

ob_start();
ob_start(static fn(string $buffer, int $phase): string => strtoupper($buffer));
echo 'tea'; ob_flush();
echo 'mint'; ob_end_flush();
echo ob_get_clean(), "\n";

TEAMINT

Во внешний буфер поступили TEA и MINT, а не исходные строки. Это показывает отличие flush от get_clean. Многословное преобразование может сломаться на границе порции: например, str_replace полного слова не найдёт слово, разрезанное между двумя echo.

<?php
declare(strict_types=1);

ob_start();
ob_start(); echo 'A'; ob_flush(); echo 'B'; ob_end_flush();
$result=ob_get_clean();
echo $result."\n";

AB

Обе части попали в внешний уровень, который ещё можно получить строкой.

<?php
declare(strict_types=1);

$base=ob_get_level();
ob_start(); ob_flush();
$active=ob_get_level()===$base+1;
ob_end_clean();
echo $active ? "still active\n" : "closed\n";

still active

Пустой flush показывает жизненный цикл без сетевых эффектов.

<?php
declare(strict_types=1);

ob_start();
echo 'Шапка; ';
ob_start();
echo 'Карточка; ';
$ended = ob_end_flush();
echo 'Подвал';
$page = ob_get_clean();
var_dump($ended);
echo $page, "\n";

bool(true)
Шапка; Карточка; Подвал

Карточка добавлена к внешнему буферу, внутренний закрыт. Подвал уже печатается прямо во внешний уровень. Очистить внутреннюю карточку после этого можно только изменив внешнюю строку, не ob_clean старого уровня.

<?php
declare(strict_types=1);

ob_start();
ob_start(null, 0, PHP_OUTPUT_HANDLER_REMOVABLE);
echo 'Готово';
$ended = ob_end_flush();
$text = ob_get_clean();
var_dump($ended);
echo $text, "\n";

bool(true)
Готово

REMOVABLE разрешает завершающую операцию. FLUSHABLE управляет отдельным ob_flush, поэтому его отсутствие не запрещает ob_end_flush. Не путайте эти разрешения в проверке прав буфера.

<?php
declare(strict_types=1);

ob_start(); echo 'page:';
ob_start(); echo 'badge'; ob_end_flush();
$html=ob_get_clean();
echo $html."\n";

page:badge

Внутренний компонент передан внешнему без отдельной переменной.

<?php
declare(strict_types=1);

$base=ob_get_level();
ob_start();
$ok=ob_end_flush();
echo $ok && ob_get_level()===$base ? "closed\n" : "failed\n";

closed

Пустой пример проверяет bool и восстановление глубины.

<?php
declare(strict_types=1);

ob_start();
echo 'Отчёт';
$before = ob_get_length();
$returned = flush();
$after = ob_get_length();
$text = ob_get_clean();
var_dump($returned, $before === $after);
echo $text, "\n";

NULL
bool(true)
Отчёт

Возврат void не сообщает об успешной доставке. Текст остался в пользовательском буфере; системному слою здесь ещё нечего отправлять из него. Не заменяйте ob_flush вызовом flush.

<?php
declare(strict_types=1);

foreach (['Файл проверен', 'Отчёт подготовлен'] as $stage) {
    echo $stage, "\n";
    flush();
}

Файл проверен
Отчёт подготовлен

Вместо настоящей обработки здесь только два сообщения, без sleep и сети. Проверен итоговый CLI-вывод. Момент отображения в терминале/браузере или прохождения прокси этим опытом не измеряется.

<?php
declare(strict_types=1);

header('Content-Type: text/event-stream');
header('Cache-Control: no-cache');
echo "event: progress\ndata: {\"done\":1}\n\n";
flush();

HTTP-фрагмент требует настройки буферизации всей цепочки и закрытой сессии. Не обещает мгновенную доставку.

<?php
declare(strict_types=1);

echo "batch 1 complete\n";
flush();

batch 1 complete

В CLI нет браузерного рендера; вывод в терминал или pipe имеет собственные условия буферизации.