Os buffers de saída no nível do usuário podem ser iniciados, manipulados e finalizados a partir do código PHP. Cada um desses buffers inclui um buffer de saída e uma função de manipulador de saída associada.
O buffer de saída pode ser ativado usando a função ob_start() ou definindo as configurações output_buffering e output_handler do php.ini. Embora ambas possam criar buffers de saída, ob_start() é mais flexível, pois aceita funções definidas pelo usuário como manipuladores de saída e as operações permitidas no buffer (liberar, limpar, remover) também podem ser definidas. Buffers iniciados com ob_start() estarão ativos a partir da linha em que a função foi chamada, enquanto aqueles iniciados com output_buffering irão armazenar a saída em buffer a partir da primeira linha do script.
O PHP também é fornecido com um manipulador de saída "URL-Rewriter"
integrado que inicia seu próprio buffer de saída e permite
até no máximo duas instâncias dele em execução a qualquer momento
(uma para reescrita de URL no nível de usuário
e uma para suporte transparente ao ID de sessão).
Esses buffers podem ser iniciados chamando
a função output_add_rewrite_var()
e/ou ativando a configuração
session.use_trans_sid
do php.ini.
A extensão zlib
incluída tem seu próprio
buffer de saída que pode ser ativado usando a configuração
zlib.output_compression
do php.ini.
Nota: Embora
"URL-Rewriter"
seja especial porque permite apenas até duas instâncias dele em execução ao mesmo tempo, todos os buffers de saída em nível de usuário usam os mesmos buffers subjacentes usados por ob_start() com sua funcionalidade implementada por uma função de manipulador de saída personalizada. Como tal, todas as suas funcionalidades podem ser emuladas pelo código do usuário.
A descarga envia e descarta o conteúdo do buffer ativo. Os buffers de saída são descarregados quando o tamanho da saída excede o tamanho do buffer; quando o script termina; ou quando ob_flush(), ob_end_flush() ou ob_get_flush() são chamados.
Chamar ob_end_flush() ou ob_get_flush() irá desligar o buffer ativo.
A descarga de buffers liberará o valor de retorno do manipulador de saída, que pode ser diferente do conteúdo do buffer. Por exemplo, usar ob_gzhandler() compactará a saída e liberará a saída compactada.
O conteúdo do buffer ativo pode ser recuperado chamando ob_get_contents(), ob_get_clean() ou ob_get_flush().
Se apenas o comprimento do conteúdo do buffer for necessário, ob_get_length() ou ob_get_status() retornação o comprimento do conteúdo em bytes.
Chamar ob_get_clean() ou ob_get_flush() irá desligar o buffer ativo depois de retornar seu conteúdo.
O conteúdo do buffer ativo pode ser limpo chamando ob_clean(), ob_end_clean() ou ob_get_clean().
Chamar ob_end_clean() ou ob_get_clean() desligará o buffer ativo.
Buffers de saída podem ser desligados chamando ob_end_clean(), ob_end_flush(), ob_get_flush() ou ob_get_clean().
Buffers de saída iniciados sem a opção
PHP_OUTPUT_HANDLER_REMOVABLE
não podem ser desligados e podem gerar um E_NOTICE
.
Todo buffer de saída que não tiver sido fechado até o final do script, ou quando a função exit() for chamada, será descarregado e desligado pelo processo de desligamento do PHP. Os buffers serão descarregados e desligados na ordem inversa de sua inicialização. O último buffer iniciado será o primeiro, o primeiro buffer iniciado será o último a ser descarregado e desligado.
Se a descarga do conteúdo do buffer não for desejada, um manipulador de saída personalizado deverá ser usado para evitar a descarga durante o desligamento.
Se uma exceção não capturada é lançada em um manipulador de saída,
o programa termina e o manipulador é invocado
pelo processo de desligamento depois do qual
a mensagem de erro "Uncaught Exception"
(exceção não capturada) é descarregada.
Se a exceção não capturada é lançada em um manipulador invocado por ob_flush(), ob_end_flush() ou ob_get_flush(), o conteúdo do buffer é descarregado antes da mensagem de erro.
Se uma exceção não capturada é lançada em um manipulador de saída durante o desligamento, o manipulador é terminado e nem o conteúdo do buffer nem a mensagem de erro são descarregados.
Nota: Se um manipulador lança uma exceção, sua constante de estado
PHP_OUTPUT_HANDLER_DISABLED
é definida.
Se um erro não fatal for gerado em um manipulador de saída, o programa continuará a execução.
Se o erro não fatal for gerado em um manipulador invocado por
ob_flush(), ob_end_flush()
ou ob_get_flush(),
o buffer descarrega determinados dados dependendo do valor de retorno do manipulador.
Se o manipulador retornar false
, o buffer e a mensagem de erro são descarregados.
Se retornar qualquer outra coisa, o valor de retorno do manipulador será descarregado,
mas a mensagem de erro não.
Nota: Se um manipulador retornar
false
, sua constante de estadoPHP_OUTPUT_HANDLER_DISABLED
será definida.
Se um erro fatal for gerado em um manipulador de saída, o programa será encerrado e o manipulador será invocado pelo processo de desligamento, após o qual a mensagem de erro será descarregada.
Se o erro fatal for gerado em um manipulador invocado por ob_flush(), ob_end_flush() ou ob_get_flush(), o conteúdo dos buffers será descarregado antes da mensagem de erro.
Se um erro fatal for gerado em um manipulador de saída durante o desligamento, o programa será encerrado sem descarregar o buffer ou a mensagem de erro.
Em circunstâncias específicas, a saída produzida no manipulador é descarregada junto com o conteúdo do buffer. Esta saída não é anexada ao buffer e não faz parte da string retornada por ob_get_flush().
Durante operações de descarga (ao chamar ob_flush(),
ob_end_flush(), ob_get_flush()
e durante o desligamento),
se o valor de retorno de um manipulador for false
,
o conteúdo do buffer é descarregado seguido pela saída.
Se o manipulador não for invocado durante o desligamento,
o fato do manipulador lançar uma exceção ou chamar a função exit()
resultará no mesmo comportamento.
Nota: Se um manipulador retornar
false
, sua constante de estadoPHP_OUTPUT_HANDLER_DISABLED
é definida.
As
constantes de estado de manipulador
da máscara de bits flags
do buffer
são definidas toda vez que o manipulador de saída é invocado
e são parte das flags
retornadas por
ob_get_status().
Se o manipulador executa com sucesso e não retorna false
,
PHP_OUTPUT_HANDLER_STARTED
e
PHP_OUTPUT_HANDLER_PROCESSED
são definidas.
Se o manipulador retonar false
ou lança uma exceção durante a execução,
PHP_OUTPUT_HANDLER_STARTED
e
PHP_OUTPUT_HANDLER_DISABLED
são definidas.
Nota: Se a constante
PHP_OUTPUT_HANDLER_DISABLED
de um manipulador for definida, o manipulador não será invocado chamando-se ob_end_clean(), ob_end_flush(), ob_get_clean(), ob_get_flush(), ob_clean(), ob_flush() ou durante o processo de desligamento do PHP. Antes do PHP 8.4.0, esta constante não tinha efeito ao chamar ob_clean() ou ob_flush().