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

## Índice

- Que Saída é Armazenada em Buffer?
- Aninhando Buffers de Saída
- Tamanho do Buffer
- Operações permitidas em buffers
- Manipuladores de Saída
- Trabalhando com Manipuladores de Saída
- Opções Passadas aos Manipuladores de Saída
- Valores de Retorno do Menipulador de Saída

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.

## 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.

Cuidado

Chamar ob_end_flush() ou ob_get_flush() irá desligar o buffer ativo.

Cuidado

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.

Cuidado

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

Cuidado

Chamar ob_end_clean() ou ob_get_clean() desligará o buffer ativo.

## Desligando Buffers

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

Aviso

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.

Cuidado

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.

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

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open