(PHP 4, PHP 5, PHP 7)
ob_start — Ativa o buffer de saída
$output_callback = NULL
[, int $chunk_size = 0
[, int $flags = PHP_OUTPUT_HANDLER_STDFLAGS
]]] )Esta função irá ativar o buffer de saída. Enquanto o buffer de saída estiver ativo, não é enviada a saída do script (outros que não sejam cabeçalhos), ao invés a saída é guardada em um buffer interno.
O conteúdo deste buffer interno pode ser copiado em uma variável usando ob_get_contents(). Para enviar o que esta no buffer interno, use ob_end_flush(). Alternativamente, ob_end_clean() irá silenciosamente descartar o conteúdo do buffer.
Alguns servidores web (Apache, por exemplo) modificam o diretório de trabalho de um script no momento da chamada da função de callback. Você pode modificar para o diretório anterior fazendo um chdir(dirname($_SERVER['SCRIPT_FILENAME'])) no corpo da função callback.
Buffers de saída são empilháveis, ou seja, você pode utilizar ob_start() enquanto outro ob_start() estiver ativo. Apenas tenha certeza que você utiliza ob_end_flush() o número apropriado de vezes. Se multiplas funções de callback de saída estiverem ativas, a saída será filtrada sequencialmente atráves de cada uma delas na ordem de aninhamento.
output_callback
Uma função de callback opcional output_callback também
pode ser especificada. Esta função tem um parâmetro string e deve retornar
uma string. Esta função será chamada quando
o buffer é descarregado (flush), limpo (com
ob_flush(), ob_clean() ou função
similar) ou quando o buffer de saída
for descarregado ao final da requisição. Quando
output_callback for chamada ela irá receber
o conteúdo do buffer como seu parâmetro e é esperado
que ela retorne um novo buffer de saída como resultado, o qual será enviado
para o navegador. Se output_callback não é uma função
que possa ser chamada, esta função irá retornar FALSE.
O callback deve ter a seguinte assinatura:
$buffer
[, int $phase
] )bufferphasePHP_OUTPUT_HANDLER_*.
Se output_callback retornar FALSE então o
buffer original é enviado ao navegador.
O parâmetro output_callback pode ser ignorado
informando um NULL como seu valor.
ob_end_clean(), ob_end_flush(), ob_clean(), ob_flush() e ob_start() não podem ser chamados de dentro da função callback. Se chamá-las dentro da função callback, o comportamenteo é indefinido. Se você quiser limpar o conteúdo do buffer, retorne "" (a null string) de dentro da função callback. Você não pode chamar outras funções que utilizam o buffer de saída como print_r($expression, true) ou highlight_file($filename, true) de dentro da função callback.
Nota:
No PHP 4.0.4 ob_gzhandler() foi introduzido para facilitar o envio de dados comprimidos no formato gz à navegadores que suportam páginas web compactadas. ob_gzhandler() determina que tipo de codificação de conteúdos os navegadores podem aceitar e retorna o resultado com base nessas informações.
chunk_size
Se o parâmetro opcional chunk_size é informado, o
buffer será descarregado em qualquer ponto de output que cause o buffer ter dados
de tamanho igual ou maior que chunk_size. O valor padrão
é 0, que significa que o função de output só será
chamada quando o buffer de saída é fechado.
Anteriormente ao PHP 5.4.0 o valor 1 era um caso especial que configurava chunk size para 4096 bytes.
flags
O parâmetro flags é um bitmask que controla
as operações que podem ser realizadas no buffer de saída. O padrão
é permitir que o buffer de saída possa ser limpo, descarregado ou removido, o que
pode ser configurado explicitamente como
PHP_OUTPUT_HANDLER_CLEANABLE |
PHP_OUTPUT_HANDLER_FLUSHABLE |
PHP_OUTPUT_HANDLER_REMOVABLE, ou pelo atalho
PHP_OUTPUT_HANDLER_STDFLAGS.
Cada flasg controla o acesso das funções, como descrito a seguir::
| Constante | Funções |
|---|---|
PHP_OUTPUT_HANDLER_CLEANABLE |
ob_clean(), ob_end_clean() e ob_get_clean(). |
PHP_OUTPUT_HANDLER_FLUSHABLE |
ob_end_flush(), ob_flush() e ob_get_flush(). |
PHP_OUTPUT_HANDLER_REMOVABLE |
ob_end_clean(), ob_end_flush() e ob_get_flush(). |
Retorna TRUE em caso de sucesso ou FALSE em caso de falha.
| Versão | Descrição |
|---|---|
| 7.0.0 |
Se ob_start() é utilizado dentro de uma função de
callback, esta função não lança mais um E_ERROR
mas agora E_RECOVERABLE_ERROR, permitindo assim
que manipuladores de erros capturem essa situação.
|
| 5.4.0 |
O terceiro parâmetro de ob_start() mudou de um
boolean chamado erase
(que, configurado para FALSE, evitava o buffer de saída de ser
apagado até o final da execução) para um parâmetro
integer chamado flags.
Infelizmente isso é uma quebra de compatibilidade reversa para códigos
escritos antes do PHP 5.4.0 que utilizem o terceiro parâmetro. Veja
o exemplo de flags
para ver como lidar com código que precisa ser compatível com ambas
as formas.
|
| 5.4.0 | Um chunk size de 1 agora configura a descarga de blocos de 1 byte enviados ao navegador. |
| 4.3.2 |
Esta função foi modificada para retornar FALSE no caso de
output_callback não for executável.
|
Exemplo #1 Exemplo de uma função de callback
<?php
function callback($buffer)
{
// substitui apples por oranges
return (str_replace("apples", "oranges", $buffer));
}
ob_start("callback");
?>
<html>
<body>
<p>It's like comparing apples to oranges.</p>
</body>
</html>
<?php
ob_end_flush();
?>
O exemplo acima irá imprimir:
<html> <body> <p>It's like comparing oranges to oranges.</p> </body> </html>
Exemplo #2 Criando um buffer de saída não apagável compatível com PHP 5.3 e 5.4
<?php
if (version_compare(PHP_VERSION, '5.4.0', '>=')) {
ob_start(null, 0, PHP_OUTPUT_HANDLER_STDFLAGS ^
PHP_OUTPUT_HANDLER_REMOVABLE);
} else {
ob_start(null, 0, false);
}
?>