Customize WordPress Without Hacking the Core Code

 

Customize WordPress Without Hacking the Core Code

Making WordPress do exactly what you want can sometimes be frustrating. For example, let’s say you’re writing your own custom plugin. You want to use the WordPress Settings API, but you don’t like the way it outputs <h3></h3> tags before each settings section. How can you customize WordPress without modifying the core functions (a hack)? PHP output buffering can be a convenient solution. This is a brief tutorial on how to use the PHP output buffering functions to filter WordPress output.

How to buffer output

Buffering is done by calling the ob_start() function in PHP. This tells the server to capture all output in an internal buffer instead of returning it. You then have a couple of choices. You can modify the buffer in place via a callback function and then flush the buffer with the ob_end_flush() or retrieve the buffer contents via ob_getcontents(), change as necessary, output the result yourself, and then call ob_end_clean() to discard the buffer contents.

Logical steps

  1. Call ob_start() to start output buffering.
  2. Modify the buffer contents in place via a custom callback function, OR
  3. Retrieve the buffer contents by calling ob_get_contents()
  4. Call ob_end_flush() after modifying the buffer contents in place via a custom callback function, OR
  5. Call ob_end_clean() if you just want to silently discard the buffer contents

PHP Output Buffer Usage

ob_start() takes several parameters, all of which are optional. The primary parameter you need to worry about is the output_callback parameter, which is the first optional parameter: ob_start( $output_callback = 'my_callback_function_name' ). The callback function name is passed as a string.

There are only 2 rules for the callback function:

  1. it must accept a single parameter… a single string containing the buffer contents, AND
  2. it must return a string… which will replace the contents of the buffer.

In the code snippet below, a callback function is used to modify the buffer contents in place. The callback function is buffer_filter, which is defined within an abstract PHP class called wp_plugin_utilities.

try {
	// output beginning html for options page
	$this->output_html( SETTINGS_PAGE_BEGIN_HTML );
	settings_fields( $option_group = 'my_plugin_option_group' );
	ob_start( 'wp_plugin_utilities::buffer_filter' );
	do_settings_sections( $page = 'my_page_handle' );
	ob_end_flush();
	?>
	<script type="text/javascript">
		jQuery(document).ready(function() { 
			my_plugin_check_fields() 
			});
	</script>
	<?php 
	// create the buttons
	$this->setting_buttons( 'my_plugin_option_group' );
	// output ending html for options page
	$this->outputHtml( SETTINGS_PAGE_END_HTML );
} catch ( wp_plugin_exception $e ) {
	echo $e->getError();
}

Callback Function Definition

In this example, the callback function simply replaces the <h3> tag with a <p> tag. You can get as sophisticated as you want, using regular expressions and other tools to modify the buffer.

public function buffer_filter( $buffer ) {
	return str_replace( 'h3', 'p', $buffer );
}

And that’s it! Now you can customize WordPress output without hacking the core code (which is never a good idea).

A NOTE OF CAUTION – be careful to use these functions sparingly and on relatively small buffers, otherwise this technique can cause performance issues and page load delays.