Contrary to my tentative conclusions of a month ago, I now understand at least one good reason to use output-buffering while writing WordPress code. Indeed, I now anticipate using the tool frequently.
While asking a question to developers at StackOverflow, I wrote the following:
My general impression is that, unless I have a very good reason for using it – probably involving the kind of script in which I’m not generally interested at this time – I should avoid it. Yet I’ll read suggestions that I could use buffering in one or another normal context (e.g., a shortcode that renders a large block of HTML), and I often see it being used in code by people whose work I admire and try to emulate. I’ve seen the familiar ob_start() etc. sequences applied for rendering even very minimal output that is not further adjusted: a menu or other short list, for example.
I have also seen people assert that there is simply no need for output buffering in well-written code, except in peculiar situations… Others will say it’s useful ONLY when some manipulation of the output is necessary – like a preg_replace of content – but you don’t need an output buffer to do that kind of thing (any ol’ variable will do).
The minimal response I received tended toward agreement: “I have no idea,” said one developer, “why some people would forcedly output something instead of returning it as a string, especially as for libraries.” My thinking was not completely wrong, but the exception I mentioned and which the developer mentions – concerning “manipulation of the output” or “forced output” – turns out to be more common in WordPress than I recognized.
The use has to do with establishing code extensibility. As WordPresser Pippin Williamson put it in a useful post from 2012, making a WordPress plugin extensible means writing it so that “other plugins and themes can manipulate or add onto the behavior of the plugin.” The “WordPress way” to achieve this end is to include “action hooks” and “filters” at critical points. It turns out that for the kind of script in which I am interested, the ob_start() to ob_get_clean() sequence is just what I need.
In my own StackOverflow answer to my own question, posted today, I wrote the following:
In order to provide a filter – using the common WordPress “apply_filters” function – you will frequently need to be able to capture the entirety of your HTML output at once. When creating a large, complex block with mixed HTML and secondary functions, using an ob_start()/ob_get_[] sequence will be a markedly more efficient way of achieving this end.
So: A plugin on which I’m currently working outputs a table whose elements are put together using a number of secondary functions. Now, I could conceivable do the entire thing adding content to a single variable, but it’s much easier and more economical to initiate output buffering at the beginning, and then write the code without the extra layer of abstraction of
$html .= [more and more HTML and PHP]In the end, the code assigns the entire output to a variable:
$html = ob_get_clean();It then returns the variable with the apply_filters function:
return apply_filters( 'filter-tag' , $html );Additionally, ob_start() and ob_get_clean() mark points in the code where it makes sense to provide do_action hooks.
In the Link-Posts Aggregator plug-in that I’ve been working on for the last month or two, at line 150 (as of this writing) of the main output function, the code finally turns to the main WordPress query that will produce the actual content of the table. In a sequence that I’m thinking may become a common sight in my plug-ins of this general type, lines 152-6 read as follows:
if ( $my_query->have_posts() ) {
ob_start();
do_action('cks_lpa_make_table');
After 86 lines, including action by 4 html-outputting secondary functions, the query loop has finished, and the total output can now be captured – and hook-and-filtered:
wp_reset_query(); //unless you're looking for trouble
do_action('cks_lpa_finish_table');
$html = ob_get_clean();
return apply_filters( 'cks_lpa_table' , $html );
Now I – or any developer – can add functions at the “do_action” points, or can perform more complex manipulation of the “$html” content.
How to use apply_filters is something that has taken me a long time to grasp: I wish I had come across Williamson’s post when first seeing the function in WordPress core code (years ago by now), and having no idea how to exploit it!
