Handling Output (Programming PHP)

13.3.1. Output Buffering

By default, PHP sends the results of echo and similar commands to the browser after each command is executed. Alternately, you can use PHP's output buffering functions to gather the information that would normally be sent to the browser into a buffer and send it later (or kill it entirely). This allows you to specify the content length of your output after it is generated, capture the output of a function, or discard the output of a built-in function.

You turn on output buffering with the ob_start( ) function:

ob_start([callback]);

The optional callback parameter is the name of a function that post-processes the output. If specified, this function is passed the collected output when the buffer is flushed, and it should return a string of output to send to the browser. You can use this, for instance, to turn all occurrences of http://www.yoursite.com/ to http://www.mysite.com/.

While output buffering is enabled, all output is stored in an internal buffer. To get the current length and contents of the buffer, use ob_get_length( ) and ob_get_contents( ):

$len = ob_get_length( );
$contents = ob_get_contents( );

If buffering isn't enabled, these functions return false.

There are two ways to throw away the data in the buffer. The ob_clean( ) function erases the output buffer but does not turn off buffering for subsequent output. The ob_end_clean( ) function erases the output buffer and ends output buffering.

There are three ways to send the collected output to the browser (this action is known as flushing the buffer). The ob_flush( ) function sends the output data to the web server and clears the buffer, but doesn't terminate output buffering. The flush( ) function not only flushes and clears the output buffer, but also tries to make the web server send the data to the browser immediately. The ob_end_flush( ) function sends the output data to the web server and ends output buffering. In all cases, if you specified a callback with ob_start( ), that function is called to decide exactly what gets sent to the server.

If your script ends with output buffering still enabled (that is, if you haven't called ob_end_flush( ) or ob_end_clean( )), PHP calls ob_end_flush( ) for you.

The following code collects the output of the phpinfo( ) function and uses it to determine whether you have the PDF module installed:

ob_start( );
phpinfo( );
$phpinfo = ob_get_contents( );
ob_end_clean( );
  
if (strpos($phpinfo, "module_pdf") === FALSE) {
  echo "You do not have PDF support in your PHP, sorry.";
} else {
  echo "Congratulations, you have PDF support!";
}

Of course, a quicker and simpler approach to check if a certain extension is available is to pick a function that you know the extension provides and check if it exists. For the PDF extension, you might do:

if (function_exists('pdf_begin_page'))

To change all references in a document from http://www.yoursite.com/ to http://www.mysite.com/, simply wrap the page like this:

<?php // at the very start of the file
  ob_start( );
?>
  
Visit <A HREF="http://www.yoursite.com/foo/bar">our site</A> now!
  
<?php
  $contents = ob_get_contents( );
  ob_end_clean( );
  echo str_replace('http://www.yoursite.com/', 'http://www.mysite.com/',
                   $contents);
?>
Visit <A HREF="http://www.mysite.com/foo/bar">our site</A> now!

Another way to do this is with a callback. Here, the rewrite( ) callback changes the text of the page:

<?php // at the very start of the file
 function rewrite ($text) {
   return str_replace('http://www.yoursite.com/', 'http://www.mysite.com/',
                       $contents);
 }
 ob_start('rewrite');
?>
Visit <A HREF="http://www.yoursite.com/foo/bar">our site</A> now!
Visit <A HREF="http://www.mysite.com/foo/bar">our site</A> now!

13.3.2. Compressing Output

Recent browsers support compressing the text of web pages; the server sends compressed text and the browser decompresses it. To automatically compress your web page, wrap it like this:

<?php
 ob_start('ob_gzhandler');
?>

The built-in ob_gzhandler( ) function is designed to be used as a callback with ob_start( ). It compresses the buffered page according to the Accept-Encoding header sent by the browser. Possible compression techniques are gzip, deflate, or none.

It rarely makes sense to compress short pages, as the time for compression and decompression exceeds the time it would take to simply send the uncompressed text. It does make sense to compress large (greater than 5 KB) web pages, though.

Instead of adding the ob_start( ) call to the top of every page, you can set the output_handler option in your php.ini file to a callback to be made on every page. For compression, this is ob_gzhandler.


13.2. Templating Systems		13.4. Error Handling

13.3. Handling Output

13.3.1. Output Buffering

13.3.2. Compressing Output