Introduction

Today I want to answer a question which has vexed mankind for centuries, "How do I get my suit dry-cleaned without that disgusting chemical smell? And can I get it done overnight?" Unfortunately, I don't have the slightest idea how to answer that question, so I'm forced instead to discuss output buffering in PHP. That's how life is some times.

Output buffering is a powerful tool in PHP which allows you to buffer a script's output. You can then edit this buffer before returning it to the client.

This tutorial will procede first by enumerating the functions used in output buffering with a brief explanation of each. Then we will examine how these functions are utililized. We will conclude with three brief examples of scenerios where one might use output buffering. Without further ado then, we will procede to...

Output Buffering Functions

Our toolbox of functions dealing with output buffering is fairly small. The following are the most common functions. The full list can be obtained from the PHP website.

ob_start([callback function]) - Starts an output buffering session.
ob_flush() - Send the contents of the buffer to the client and clear the buffer.
ob_get_contents() - Returns the contents of the buffer. The buffer is not cleared.
ob_end_clean() - Ends the current buffering session and purges the buffer.
ob_end_flush() - Ends the current buffering session and displays the buffer.
ob_get_length() - (Version >= 4.0.2) Return the size of the current buffer.
ob_get_clean() - (Version >= 4.3) Composite of ob_get_contents() and ob_end_clean(). The buffer is returned and the session ends.

How It's Done

We begin with a simple Hello World script.

// Start buffering ob_start(); print "Hello World"; // Grab the buffer $buffer = ob_get_contents(); // Stop buffering ob_end_clean(); // Display the buffer print "'$buffer'";

The output isn't all that exciting, simply Hello World in single quotes. The function ob_start() initiates the output buffering. "Hello World" is then printed, but it does not get sent to the client. Instead it is buffered until we do something with it. That we do by storing the buffer in $buffer by calling ob_get_contents(). ob_end_clean() ends the output buffering, which means that the last print command displays to the client.

You might be asking what happens if you call ob_start() twice without closing the buffer. PHP's real smart, so it handles it very nicely by nesting the buffers. The following script shows how this is done.

// Open buffer #1 ob_start(); print "Line 1\n"; // Open buffer #2 ob_start(); print "Line 2\n"; // Grab the contents of buffer #2 $buf2 = ob_get_contents(); // Close buffer #2 ob_end_clean(); print "Line 3\n"; // Grab the contents of buffer #1 $buf1 = ob_get_contents(); // Close buffer #1 ob_end_clean(); // Output the buffer contents print $buf1; print $buf2;

Without knowledge of output buffering, one would expect the lines to be printed in numerical order. This is not the case though. After printing line 1, a second buffer is opened which prints line 2 and captures the buffer. Line 3 is then printed in the first buffer. The first buffer captures lines 1 and 3 while the second captures line 2.

What all this means is that you can build functions and scripts with output buffering without worrying about fouling up an algorithm nested below or above in the logic. As long as you always remember to close every buffer you open, you won't have any problems.

Arguably the most powerful element of output buffering is the capability of defining callback functions. You can define a function to be called when the buffer is flushed to the screen. This callback function receives the buffer as a parameter. The returned value is then printed.

// Start buffering with a callback function ob_start("callback"); print "Line 1\n"; print "Line 2\n"; // Flush the contents ob_flush(); print "Line 3\n"; // Define the callback function function callback($buffer) {     return "Here's the buffer: $buffer"; }

The script displays lines 1 through 3. After printing line 2, the buffer is flushed. This passes the data to the callback function, which prepends to trite little message. Since the buffer isn't closed before the end of the script, PHP automatically flushes the buffer, which calls the callback function once again. One of the examples below deals with callback functions more in depth.

There are a couple of things to remember when using callback functions. You have to return what you want to displayed, not print it. The print command doesn't work in the callback function. Also, you cannot use output buffering inside of a callback function. It's because of some United Nations resolution or something. It just can't be done, so don't try it.

Examples

Now that we are all experts with output buffering, let's examine a few examples of what output buffering can do for us. We will first examine a simple method of caching pages that require a large amount of processor time to execute, so you only have to update the information when absolutely necessary. We will then see how to catch the output from functions like fileread(). The last example is how to add footer functions.

Recently I wrote a script which took a long time to run. There was a very large list of race results for a 5K. The script loaded the results from a CSV spreadsheet file and output them in a visually pleasing format. With the size of the spreadsheet, the parsing took an extremely long time. This definitely wouldn't do, but then my good friend output buffering came and joined my side.

The following code shows how output buffering can be employed to cache whole pages or sections of pages. A call is made to parse_spreadsheet() which is not a real function. This simply exists to represent a function which parses the spreadsheet. In testing this snippet, replace this line with a function you have prepared. The name of the cache file and spreadsheet are stored in the constants CACHE_FILE and SPREADSHEET_FILE respectively.

// Define file locations     define(CACHE_FILE, "./spreadsheet_cache");     define(SPREADSHEET_FILE, "./spreadsheet.csv");     // Check which has been updated most recently, the spreadsheet or cache     if (@filemtime(SPREADSHEET_FILE) > @filemtime(CACHE_FILE)) {                  // Initiate output buffering         ob_start();                  // Parse the spreadsheet         parse_spreadsheet();         // Write the buffer to the cache file         $fh = fopen(CACHE_FILE, "w");         fwrite($fh, ob_get_contents());         fclose($fh);         // End the output buffer and display the contents         ob_end_flush();          // If the cache is newer than the spreadsheet, simply display     // the cache file rather than parsing again     } else {         readfile(CACHE_FILE);     }

One should not think that this technique is limited to spreadsheets only. Another useful example is when data must be retrieved from a database. This works well in any situation where a lot of data needs to be parsed on a regular basis which is possibly very time consuming. Simply replace parse_spreadsheet() with the appropriate display function and the if statement with an appropriate method of detecting whether the data should be updated or if the cache can be used.

There aren't too many things that annoy me. My entire list could be enumerated as follows: cats, people who buy 300 individual cans of soup yet count it as one item in the express lane, and functions like fileread(). I can't offer any solutions for the first two (no legal solutions at least), but the third I can.

By functions like fileread() I am implying functions which simply dump their output to the output buffer rather than returning their output as a string. A brief list (by no means comprehensive) of such functions is: passthru(), fpassthru(), system(), etc. These functions are extremely annoying when you are simply trying to obtain and parse the output. Thankfully, our good friend output buffering comes to the rescue.

The following snippet shows how to read an entire file into a variable very easily.

// Start output buffering     ob_start();       // Load file contents     readfile("data.txt");     // Transfer the contents into a variable     $data = ob_get_contents();     // Close the output buffering     ob_end_clean();

The entire contents of data.txt are now stored in $data. It is obvious how one could easily replace readfile() with any of the previously mentioned functions to capture any sort of function output into a variable. For example, to run a shell script and suppress the results can be accomplished in the same way but without placing the output buffer contents in a variable.

In most PHP applications header files are included at the beginning of each script to handle such things as initiating database connections, loading libraries, instantiating classes, etc. There are often things which should be done at the end of each script as well, such as parsing templates, closing connections, etc. In the past, I have been forced to explicitly call these functions in each seperate script. I didn't know of anyway to globally set such footer functions, until now.

Output buffering with the use of a callback function allows the use of footer functions without having to edit the php.ini file. We will first examine a very simple example. Including the following snippet at the top of a script will cause a copyright message to be appended to the bottom of the page.

// Start output buffering with a callback function     ob_start("footer_copyright");     // Function called when the output buffer is flushed     function footer_copyright($buffer) {         // Generate the copyright message         $copyright = "<p align=center><small>Copyright © "                    . implode(",", range(2002, date('Y')))                    . "</small></p>";                  // Return the composite buffer         return $buffer.$copyright;     }

The footer function need not only deal with adding text to the page. You can perform any operation within this footer function as you would anywhere else. Therefore, you could increment counters, close file handles, finalize object instances, etc. The only thing you cannot do inside a output buffering handler is output buffering. This should not be too large of a restriction though.

Output buffering is one of those parts of PHP which often gets overlooked. This is unfortunate since wise use of output buffering can simplify many projects. Once you learn to use it proficiently, you will find numerous scenarios where it can be used that you'd never thought of before.