Lara L. Schenck

tl;dr: Output buffering is a way to tell PHP to hold some data before it is sent to the browser. Then you can retrieve the data and put it in a variable, manipulate it, and send it to the browser once you’re finished.

Umm…isn’t this a little random?

Yes…but no! As someone who works with WordPress on the regular, output buffering is one of those concepts that I’ve encountered in the past and, until now, never needed to understand. It’s a good example of learning on a “need to know” basis which, I think most web folk will agree, is a core part of being in our industry. Particularly when using plugins and frameworks, we constantly come across code where we pause and think, “Uh, I have no idea what that does…” then we move along with our lives. Sometimes, however, we need to understand what that code-written-by-a-smarter-person-than-me is, for whatever reason.

This rabbit hole of research began with a question I received in my inbox regarding Timber, a plugin I love to use when developing custom WordPress websites: “What do header.php and footer.php do in a Timber theme?”

The quick answer to this question is they do nothing; they are required for certain WordPress plugins. But I didn’t know that! I’d never had to touch those files in my development practice, oddly enough, so I began to investigate. The main pieces of code in these files were PHP output buffering functions (ob_start, ob_get_contents, etc).

Let’s leave the Timber details for another time, and dive into this PHP thing called “output buffering”.

What is output buffering?

What is output buffering? Let’s pretend you, the developer had a conversation with PHP:

You: “Hey, PHP! Don’t send any output to the browser immediately, like you usually do. I want to do some programming stuff to it first, then I’ll tell you when to send it.”

PHP: “Ok, I’ll store it in a thing called a buffer until you tell me when to send it to the browser.”

You: “Thanks, PHP! Don’t worry, you are still relevant.”*

In other words, PHP sends data to the browser from the server as soon as a function is finished. For example, if your PHP code is echo "Hi there"; the string “Hi there” is sent to the browser immediately after the echo function runs. If you run that echo function when output buffering is in effect, however, “Hi there” will be stored in this invisible holding cell called a buffer, and won’t display on the page until you’ve retrieved its contents and sent them to the browser.

* In the age of JavaScript this, this, and that, it seems almost futile to write a detailed post about little PHP nuance. But it’s not! For one, PHP is the OG of programming for the web and WordPress, built in PHP, powers 25% of the web at large. JavaScript may be here to stay, but PHP isn’t going anywhere!

The Functions

A few common output buffering functions:

ob_start() turns on output buffering. In other words, it creates the buffer (invisible holding cell) that will store all output after it is called.

ob_get_contents() grabs all of the data gathered since we called ob_start, i.e. everything in the buffer. Usually, you’ll assign this to a variable.

ob_clean() removes everything from the output buffer. Note that it does not output anything.

ob_flush() outputs content from the buffer. Note that it does not erase the buffer.

ob_end_clean() basically runs ob_get_contents(), discards the result, and turns off output buffering.

ob_end_flush() outputs content from the buffer and ends output buffering. It does not erase the buffer.

See a full list here.

An Example

The most important part of using the output buffering functions is where you put them. You need to initiate the buffer with ob_start in the right spot, and you need to output the buffer either onto the page or into a variable before you empty it.

<?php
  // Turn on output buffering
  // There will be no output until you "flush" or echo the buffer's contents
  ob_start();
  
  // Set some variables unrelated to buffering
  $name = "Lara";
  $food = "cashews";
?> 
<!-- Remember, none of this HTML will be sent to the browser, yet! -->

<h1>Hi, my name is <?php echo $name; ?>.</h1>
<p>I like <?php echo $food; ?>.</p> 
<?php
  // Put all of the above ouptut into a variable
  // This has to be before you "clean" the buffer
  $content = ob_get_contents();
  
  // Erase the buffer in case we want to use it for something else later
  ob_end_clean();

  // All of the data that was in the buffer is now in $content
  echo $content;
?>

But why?

Great question; it’s quite possible you’ll never actually use output buffering unless you are a WordPress plugin developer or write custom PHP applications. For those of us who do neither of those things, here are a few instances where output buffering know-how could come in handy, if not only to provide context for a larger issue:

HTTP Headers

Ever seen this error?

Warning: Cannot modify header information - headers already sent by (output started at /some/file.php:12) in /some/file.php on line 23

For anyone unfamiliar with the definition of an HTTP header, HTTP headers are information sent from a server upon an HTTP request that tells the browser what kind of data is coming before it gets there. HTTP headers contain information like the type of content on its way, the date it was last modified, the type of server sending the request, and much more. The catch is, headers need to be sent before any output or other data is sent from the server.

A quick example: Let’s say your application saves a user’s login information in a cookie. Cookies are a type of HTTP header, so they must be sent to the browser before any other site data. Depending on how your program is structured, the cookie code might not be at the very top of your file. Output buffering, in simplest terms, allows you say, “Hey PHP, I’ll tell you when to send the regular site output after I’ve handled the cookie and stuff,” otherwise, you may run into an error similar to the above.

Note that running into this error in the above scenario could indicate some bad practice in terms of how your application is structured, conflicts with other plugins, or something else that is otherwise no bueno. There is a fantastic explantion of this error on StackOverflow here.

In Conclusion

You, front-end developer, might never use output buffering.

But someday, you may need to understand it! And I hope this write-up will help someone somewhere in their debugging adventures.

Resources

• Understanding PHP Output Buffering, and Why It’s Great for Shortcodes
• CSS-Tricks Output Buffering Snippet
• Buffering WordPress Content with PHP