Буфери виводу користувача

Користувальницькі буфери виводу дозволено запускати, маніпулювати ними та завершувати з PHP-коду. Кожен із цих буферів складається з буфера виведення та пов'язаної з ним функції обробника виведення.

Увімкнення буферизації виводу

Буферизацію виводу включають виклик функції ob_start()или установкой в файле php.ini параметров директивамoutput_buffering і output_handler. Хоча обидва способи вміють створювати буфери виводу, функція ob_start() гнучкіше, оскільки приймає як обробників виведення користувацькі функції і вміє задавати операції, дозволені для буфера (скидання, очищення, видалення). Буфери, запущені функцією ob_start(), будуть активні з того рядка, з якого була викликана функція, тоді як ті, що були запущені директивою output_buffering, буферизуватиме висновок починаючи з першого рядка скрипта.

PHP також поставляється з вбудованим обробником виводу «URL-Rewriter», який запускає свій буфер виводу і дозволяє запускати одночасно до двох його екземплярів (одна для перезапису URL-адрес на рівні користувача та ще одна для підтримки прозорого ідентифікатора сесії). Ці буфери запускають виклик функції output_add_rewrite_var() та (або) включенням директиви session.use_trans_sidв файле php.ini.

У модуль, що входить в комплект zlib інтегрований свій буфер виводу, який включають директиву zlib.output_compressionв файле php.ini.

Зауваження: Хотя обработчик«URL-Rewriter» і виділяється тим, що дозволяє запускати одночасно лише до двох своїх екземплярів, користувальницькі буфери виведення працюють з тими ж базовими буферами, які використовує функція ob_start(), А їх функціональність реалізована користувальницькою функцією обробника виведення. Тому їх функціональність в змозі зімітувати код користувача.

Скидання, доступ та очищення вмісту буфера

Скидання надсилає та видаляє вміст активного буфера. Буфери виводу скидаються, коли розмір виводу перевищує розмір буфера, скрипт завершує роботу або викликаються функції ob_flush() ob_end_flush() або ob_get_flush()

Застереження

Виклик функцій ob_end_flush() або ob_get_flush() відключить активний буфер.

Застереження

Скидання буферів також скине повертається обробником виводу значення, яке обробник виводу вміє змінювати, і якщо так, значення відрізнятиметься від вмісту буфера. Наприклад, передача в обробник виведення функції ob_gzhandler() призведе до стиснення даних виведення та скидання стисненого виводу.

Вміст активного буфера одержують викликом функцій ob_get_contents() ob_get_clean() або ob_get_flush()

Якщо потрібно лише розмір вмісту буфера, функції ob_get_length() або ob_get_status() повернуть розмір вмісту у байтах.

Застереження

Виклик функцій ob_get_clean() або ob_get_flush() відключить активний буфер після повернення вмісту.

Вміст активного буфера очищають викликом функцій ob_clean() ob_end_clean() або ob_get_clean()

Застереження

Виклик функцій ob_end_clean() або ob_get_clean() вимкне активний буфер виведення.

Відключення буферів

Буфери виводу вимикають викликом функцій ob_end_clean() ob_end_flush() ob_get_flush() або ob_get_clean()

Увага

Буфери виведення, запущені без прапора PHP_OUTPUT_HANDLER_REMOVABLE, не можна вимкнути, а спроба видалити такі буфери видасть помилку рівня E_NOTICE

Кожен буфер виводу, який не був закритий до кінця скрипта або виклику конструкції exit(), буде скинуто та вимкнено процесом завершення роботи PHP. Буфери будуть скинуті та відключені у порядку, зворотному їх запуску. Останній запущений буфер буде першим, а перший запущений буфер буде скинутий та відключений в останню чергу.

Застереження

Якщо скидання вмісту буферів не потрібне, активують обробний користувач виводу, щоб запобігти скидання при завершенні роботи.

Винятки в обробниках висновку

Якщо в обробнику виводу викидається неперехоплений виняток, програма завершується, а процес завершення роботи викликає обробник, потім виводиться повідомлення про помилку Uncaught Exception

Якщо в обробнику виводу, що викликається функціями ob_flush() ob_end_flush() або ob_get_flush(), викидається неперехоплений виняток, вміст буфера скидається перед повідомленням про помилку.

Якщо в обробнику виводу неперехоплений виняток викидається під час вимкнення, обробник завершується, не скидаються ні вміст буфера, ні повідомлення про помилку.

Зауваження: Якщо обробник виводу викидає виняток, PHP встановлює для нього прапор стану PHP_OUTPUT_HANDLER_DISABLED

Помилки в обробниках виводу

Якщо в обробнику виводу видана помилка, програма продовжує виконуватися.

Якщо в обробнику, що викликається функціями ob_flush() ob_end_flush() або ob_get_flush(), Виникає непереборна помилка, буфер скидає дані, які повернув обробник. Якщо обробник повертає значення **false**скидається буфер і повідомлення про помилку. Якщо повертає інше значення, значення, що повертається обробником, скидається, але не повідомлення про помилку.

Зауваження: Якщо обробник повертає значення false PHP встановлює для нього прапор стану PHP_OUTPUT_HANDLER_DISABLED

Якщо в обробнику виводу виникає фатальна помилка, програма завершується, а процес завершення роботи викликає обробник, а потім скидається повідомлення про помилку.

Якщо в обробнику виводу, що викликається функціями ob_flush() ob_end_flush() або ob_get_flush(), виникає фатальна помилка, виникає, вміст буферів скидається перед повідомленням про помилку.

Якщо фатальна помилка виникає при вимкненні в обробнику виводу, програма завершується без скидання буфера або повідомлення про помилку.

Виведення обробників висновку

За конкретних обставин вихідні дані, створені в обробнику, скидаються разом із вмістом буфера. Цей висновок не додається до буфера і не стає рядком, що повертається функцією ob_get_flush()

Якщо під час операцій скидання (при виклику функцій ob_flush() ob_end_flush() ob_get_flush() і при завершенні роботи) значення обробника, що повертається, дорівнює false, вміст буфера скидається, а потім йде висновок. Якщо обробник не викликається при завершенні роботи, обробник викидає виняток; виклик конструкції exit() поводиться так само.

Зауваження: Якщо обробник повертає значення false, PHP встановлює для нього прапор стану PHP_OUTPUT_HANDLER_DISABLED

Прапори стану обробника виводу

PHP устанавливаетпрапори стану оброблювача бітової маски прапорів (flags) буфера щоразу під час виклику оброблювача виведення і робить їх частиною прапорів (flags), що повертаються функцією ob_get_status(). Якщо обробник успішно виконується та не повертає значення false, PHP встановлює прапори стану PHP_OUTPUT_HANDLER_STARTED і PHP_OUTPUT_HANDLER_PROCESSED. Якщо обробник повертає значення false або викидає виняток під час роботи, PHP встановлює прапори стану PHP_OUTPUT_HANDLER_STARTED і PHP_OUTPUT_HANDLER_DISABLED

Зауваження: Если для обработчика установлено значение**PHP_OUTPUT_HANDLER_DISABLED**, обробник не запускатиметься під час виклику функцій ob_end_clean() ob_end_flush() ob_get_clean() ob_get_flush() або при завершенні процесу роботи PHP. Цей прапор не дає ефекту під час виклику функцій ob_clean() або ob_flush()