Buffers de Saída em Nível de Usuário

Ativando o buffer de saída

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.

Descarregando, Acessando e Limpando o Conteúdo do Buffer

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.

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.

O conteúdo do buffer ativo pode ser limpo chamando ob_clean(), ob_end_clean() ou ob_get_clean().

Desligando Buffers

Buffers de saída podem ser desligados chamando ob_end_clean(), ob_end_flush(), ob_get_flush() ou ob_get_clean().

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.

Exceções Lançadas em Manipuladores de Saída

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.

Erros Emitidos em Manipuladores de Saída

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 estado PHP_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.

Saída nos Manipuladores de Saída

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 estado PHP_OUTPUT_HANDLER_DISABLED é definida.

Constantes de Estado do Manipulador de Saída

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().