Important alert: (current site time 10/30/2014 11:34:37 PM EDT)
 

article

Output Buffering in PHP

Email
Submitted on: 7/21/2003 12:59:26 PM
By: Michael Bailey  
Level: Intermediate
User Rating: By 4 Users
Compatibility: PHP 3.0, PHP 4.0
Views: 21987
author picture
(About the author)
 
     Unlock the mysteries of output buffering with PHP.

 
 
Terms of Agreement:   
By using this article, you agree to the following terms...   
  1. You may use this article in your own programs (and may compile it into a program and distribute it in compiled format for languages that allow it) freely and with no charge.
  2. You MAY NOT redistribute this article (for example to a web site) without written permission from the original author. Failure to do so is a violation of copyright laws.   
  3. You may link to this article from another website, but ONLY if it is not wrapped in a frame. 
  4. You will abide by any additional copyright restrictions which the author may have placed in the article or article's description.
				Originally posted by author at www.jinxidoru.com

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

The Basics

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.

Nested Output Buffering

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.

Callback Functions

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.

Caching with PHP

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($fhob_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.

Catching Text from Functions

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.

Footers

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 &copy; "
                   
implode(","range(2002date('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.

Conclusion

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.



Other 3 submission(s) by this author

 


Report Bad Submission
Use this form to tell us if this entry should be deleted (i.e contains no code, is a virus, etc.).
This submission should be removed because:

Your Vote

What do you think of this article (in the Intermediate category)?
(The article with your highest vote will win this month's coding contest!)
Excellent  Good  Average  Below Average  Poor (See voting log ...)
 

Other User Comments

7/23/2003 1:54:33 PMICode

Thanks Michael, I learned something new. Very comprehensive!
(If this comment was disrespectful, please report it.)

 
7/8/2004 8:54:28 AMZorrer

Brillient, Yes i am reading it in 2004, but there is always time to start using new and improved things ;)
(If this comment was disrespectful, please report it.)

 

Add Your Feedback
Your feedback will be posted below and an email sent to the author. Please remember that the author was kind enough to share this with you, so any criticisms must be stated politely, or they will be deleted. (For feedback not related to this particular article, please click here instead.)
 

To post feedback, first please login.