ob_start

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_start — Ativa o buffer de saída

Descrição

ob_start(?callable $callback = null, int $chunk_size = 0, int $flags = PHP_OUTPUT_HANDLER_STDFLAGS): bool

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 disto a saída é guardada em um buffer interno. Consulte Que Saída é Armazenada em Buffer? sobre exatamente que saída é afetada.

Buffers de saída são empilháveis, ou seja, ob_start() pode ser chamada enquanto outro buffer estiver ativo. Se múltiplos buffers de saída estiverem ativos, a saída será filtrada sequencialmente atráves de cada uma delas na ordem de aninhamento. Consulte Aninhando Buffers de Saída para mais detalhes.

Consulte Buffers de Saída em Nível de Usuário para uma descrição detalhada de buffers de saída.

Parâmetros

callback

Uma função callback do tipo callable pode ser especificada. Ela também pode ser ignorada passando-se null.

callback é chamada quando o buffer de saída é descarregado (enviado), limpo, ou quando o buffer de saída é descarregado no final da execução do script.

A assinatura da função callback deve ser da seguinte forma:

handler(string $buffer, int $phase = ?): string

buffer: O conteúdo original do buffer.
phase: Máscara de bits das constantes PHP_OUTPUT_HANDLER_* . Consulte Opções Passadas aos Manipuladores de Saída para mais detalhes.

Se callback retornar false, o conteúdo do buffer é retornado. Consulte Valores de Retorno do Menipulador de Saída para mais detalhes.

Aviso

Chamar qualquer das funções a seguir de dentro de um manipulador de saída resultará em erro fatal: ob_clean(), ob_end_clean(), ob_end_flush(), ob_flush(), ob_get_clean(), ob_get_flush() e ob_start().

Consulte Manipuladores de Saída e Trabalhando com Manipuladores de Saída para mais detalhes sobre as funções callback (manipuladores de saída).

chunk_size

Se o parâmetro opcional chunk_size for informado, o buffer será descarregado depois que algum bloco de código que produza saída faça com que o tamanho do buffer fique igual ou maior que chunk_size. O valor padrão é 0, que significa que toda a saída fica em buffer até que ele seja desligado. Consulte Tamanho do Buffer para mais detalhes.

flags

O parâmetro flags é uma máscara de bits 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 através das opções de controle de buffer . Consulte Operações permitidas em buffers para mais detalhes.

Cada opção controla o acesso das funções, como descrito a seguir:

Constante	Funções
`PHP_OUTPUT_HANDLER_CLEANABLE`	ob_clean()
`PHP_OUTPUT_HANDLER_FLUSHABLE`	ob_flush()
`PHP_OUTPUT_HANDLER_REMOVABLE`	ob_end_clean(), ob_end_flush(), ob_get_clean() e ob_get_flush()

Nota: Antes do PHP 8.4.0, o parâmetro flags poderia definir também as opções de status do manipulador de saída.

Valor Retornado

Retorna true em caso de sucesso ou false em caso de falha.

Exemplos

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 produzirá:

<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

<?php

ob_start(null, 0, PHP_OUTPUT_HANDLER_STDFLAGS ^ PHP_OUTPUT_HANDLER_REMOVABLE);

?>

Veja Também

ob_get_contents() - Retorna o conteúdo do buffer de saída
ob_end_clean() - Limpa (apaga) o conteúdo do buffer de saída ativo e desliga-o
ob_end_flush() - Descarrega (envia) o valor de retorno do manipulador de saída ativo e desliga o buffer de saída ativo
ob_implicit_flush() - Liga ou desliga o descarregamento implícito
ob_gzhandler() - Função de chamada de retorno de ob_start para comprimir o buffer de saída com gzip
ob_iconv_handler() - Converte codificação de caracteres como manipulador de buffer de saída
mb_output_handler() - Callback converte a codificação de caracteres no buffer de saída
ob_tidyhandler() - ob_start callback function to repair the buffer

Melhore Esta Página

Aprenda Como Melhorar Esta Página • Envie uma Solicitação de Modificação • Reporte um Problema

＋adicione uma nota

Notas Enviadas por Usuários (em inglês) 6 notes

down

Ray Paseur (Paseur ... ImagineDB.com) ¶

19 years ago

You can use PHP to generate a static HTML page.  Useful if you have a complex script that, for performance reasons, you do not want site visitors to run repeatedly on demand.  A "cron" job can execute the PHP script to create the HTML page.  For example:

<?php // CREATE index.html
   ob_start();
/* PERFORM COMLEX QUERY, ECHO RESULTS, ETC. */
   $page = ob_get_contents();
   ob_end_clean();
   $cwd = getcwd();
   $file = "$cwd" .'/'. "index.html";
   @chmod($file,0755);
   $fw = fopen($file, "w");
   fputs($fw,$page, strlen($page));
   fclose($fw);
   die();
?>

down

net_navard at yahoo dot com ¶

18 years ago

Hello firends

ob_start() opens a buffer in which all output is stored. So every time you do an echo, the output of that is added to the buffer. When the script finishes running, or you call ob_flush(), that stored output is sent to the browser (and gzipped first if you use ob_gzhandler, which means it downloads faster). 

The most common reason to use ob_start is as a way to collect data that would otherwise be sent to the browser.

These are two usages of ob_start():

1-Well, you have more control over the output. Trivial example: say you want to show the user an error message, but the script has already sent some HTML to the browser. It'll look ugly, with a half-rendered page and then an error message. Using the output buffering functions, you can simply delete the buffer and sebuffer and send only the error message, which means it looks all nice and neat buffer and send 
2-The reason output buffering was invented was to create a seamless transfer, from: php engine -> apache -> operating system -> web user

If you make sure each of those use the same buffer size, the system will use less writes, use less system resources and be able to handle more traffic. 

With Regards, Hossein

down

ed.oohay (a) suamhcs_rodnan ¶

21 years ago

Output Buffering even works in nested scopes or might be applied in recursive structures... thought this might save someone a little time guessing and testing :)

<pre><?php
    
    ob_start();              // start output buffer 1
    echo "a";                // fill ob1
        
        ob_start();              // start output buffer 2
        echo "b";                // fill ob2
        $s1 = ob_get_contents(); // read ob2 ("b")
        ob_end_flush();          // flush ob2 to ob1
        
    echo "c";                // continue filling ob1
    $s2 = ob_get_contents(); // read ob1 ("a" . "b" . "c")
    ob_end_flush();          // flush ob1 to browser
    
    // echoes "b" followed by "abc", as supposed to:
    echo "<HR>$s1<HR>$s2<HR>";
    
?></pre>

... at least works on Apache 1.3.28

Nandor =)

down

Asher Haig (ahaig at ridiculouspower dot com) ¶

17 years ago

When a script ends, all buffered output is flushed (this is not a bug: http://bugs.php.net/bug.php?id=42334&thanks=4). What happens when the script throws an error (and thus ends) in the middle of an output buffer? The script spits out everything in the buffer before printing the error!

Here is the simplest solution I have been able to find. Put it at the beginning of the error handling function to clear all buffered data and print only the error:

$handlers = ob_list_handlers();
while ( ! empty($handlers) )    {
    ob_end_clean();
    $handlers = ob_list_handlers();
}

down

Chris ¶

14 years ago

Careful with while using functions that change headers of a page; that change will not be undone when ending output buffering.

If you for instance have a class that generates an image and sets the appropriate headers, they will still be in place after the end of ob.

For instance:
<?php
  ob_start();
  myClass::renderPng(); //header("Content-Type: image/png"); in here
  $pngString = ob_get_contents();
  ob_end_clean();
?>

will put the image bytes into $pngString, and set the content type to image/png. Though the image will not be sent to the client, the png header is still in place; if you do html output here, the browser will most likely display "image error, cannot be viewed", at least firefox does.

You need to set the correct image type (text/html) manually in this case.

down

ernest at vogelsinger dot at ¶

19 years ago

When you rely on URL rewriting to pass the PHP session ID you should be careful with ob_get_contents(), as this might disable URL rewriting completely.

Example:
ob_start();
session_start();
echo '<a href=".">self link</a>';
$data = ob_get_contents();
ob_end_clean();
echo $data;

In the example above, URL rewriting will never occur. In fact, rewriting would occur if you ended the buffering envelope using ob_end_flush(). It seems to me that rewriting occurs in the very same buffering envelope where the session gets started, not at the final output stage.

If you need a scenario like the one above, using an "inner envelope" will help:

ob_start();
ob_start();   // add the inner buffering envelope
session_start();
echo '<a href=".">self link</a>';
ob_end_flush(); // closing the inner envelope will activate URL rewriting
$data = ob_get_contents();
ob_end_clean();
echo $data;

In case you're interested or believe like me that this is rather a design flaw instead of a feature, please visit bug #35933 (http://bugs.php.net/bug.php?id=35933) and comment on it.

＋adicione uma nota