Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
188 lines (175 sloc) 8.07 KB
* On the Advanced Settings page enable "Enable dynamic caching" and clear
* the cache.
* Plugin authors: NEVER define the template tag for your users. Make them
* choose one so it will be unique to their site.
* There are two examples in this file. Both use template tags that must be
* kept secret.
* Dynamic content: the text or widget you want to show visitors to your site
* that changes every time it's viewed.
* Placeholder/template tag: the string of random characters placed in your
* theme file or printed in an action where the dynamic content will go.
* Output buffer (ob): any text that is printed by PHP to be sent to the browser
* but captured by PHP for further manipulation.
* OB Callback function: A function that is called when the output buffer is
* filled with a html page. The contents of the page are passed to the function
* for processing.
* You should probably add 'deny from all' to the .htaccess in the cache directory
* so visitors can't directly load any cached html files and discover the secret
* tag. Or you can move the cache directory out of the web path and set the
* cache location to that new directory on the advanced settings page.
* Replace a string in your theme with the dynamic content.
* dynamic_cache_test_init()
* This function is the first one to be called. This function hooks
* dynamic_cache_test_template() to the WordPress action, wp_footer.
* This script is loaded before WordPress is and the add_action()
* function isn't defined at this time.
* This init function hooks onto the cache action "add_cacheaction"
* that fires after WordPress (and add_action) is loaded.
* dynamic_cache_test_template_tag()
* This function hooks on to wp_footer and displays the secret template
* tag that will be replaced by our dynamic content on each page view.
* dynamic_cache_test_filter()
* This function hooks on to the filter through which all the cached data
* sent to visitors is sent.
* In this simple example the template tag is replaced by a html comment
* containing the text "Hello world at " and the current server time.
* If you want to use the output of a WordPress plugin or command you
* must enable "late init" on the settings page. Each time you reload
* the cached page this time will change. View the page source to examine
* this text.
* Chronology of a request:
* 1. dynamic_cache_test_init() hooks dynamic_cache_test_template_tag() on
* to the wp_footer action. dynamic_cache_test_filter() is hooked on to
* the wpsc_cachedata filter.
* 2. An output buffer is created by WP Super Cache.
* 3. Most of the page is generated by WordPress.
* 4. The wp_footer action fires and the TAG is printed to the page.
* 5. Processing continues and the page is created.
* 6. The output buffer finishes. A WP Super Cache callback function runs
* and saves the output buffer to a cache file. The wpsc_cachedata
* filter is called.
* 7. The function dynamic_cache_test_filter() runs and replaces the TAG in
* the buffer with the "Hello world" string.
* 8. The output buffer is pushed to the browser to be displayed.
define( 'DYNAMIC_CACHE_TEST_TAG', '' ); // Change this to a secret placeholder tag.
if ( '' !== DYNAMIC_CACHE_TEST_TAG ) {
function dynamic_cache_test_safety( $safety ) {
return 1;
add_cacheaction( 'wpsc_cachedata_safety', 'dynamic_cache_test_safety' );
function dynamic_cache_test_filter( $cachedata ) {
return str_replace( DYNAMIC_CACHE_TEST_TAG, '<!-- Hello world at ' . date( 'H:i:s' ) . ' -->', $cachedata );
add_cacheaction( 'wpsc_cachedata', 'dynamic_cache_test_filter' );
function dynamic_cache_test_template_tag() {
echo DYNAMIC_CACHE_TEST_TAG; // This is the template tag.
function dynamic_cache_test_init() {
add_action( 'wp_footer', 'dynamic_cache_test_template_tag' );
add_cacheaction( 'add_cacheaction', 'dynamic_cache_test_init' );
* This is going to be complicated. Hang on!
* When the cache file for a new page is generated the plugin uses an output
* buffer to capture the page. A callback function processes the buffer and
* writes to the cache file. The placeholder tag for any dynamic content has
* to be written to that cache file but also, it has to be replaced with
* dynamic content before the page is shown to the user.
* More on output buffers here:
* Unfortunately an extra output buffer is often required when capturing dynamic
* content such as sidebar widgets. Due to a quirk of the way PHP works it's
* not possible to have an output buffer run in an output buffer callback. That
* dynamic content has to be generated before the callback function is reached.
* The following error occurs when an output buffer is created in the
* callback function of another output buffer:
* "PHP Fatal error: ob_start(): Cannot use output buffering in output buffering display handlers in..."
* In this example the function add_action() isn't available when this file is
* loaded so dynamic_output_buffer_init() is hooked on to the "add_cacheaction"
* cacheaction. That function then hooks dynamic_output_buffer_test() on to the
* familiar wp_footer action.
* The first time dynamic_output_buffer_test() runs it generates the dynamic
* content and captures it with ob_start() in the DYNAMIC_OB_TEXT constant.
* When the main WP Super Cache output buffer is ready the callback is called.
* This fires the wpsc_cachedata_safety filter. If the DYNAMIC_OB_TEXT constant
* is set, which means dynamic content is ready, then it returns 1, a signal
* that everything is ok.
* Finally, the wpsc_cachedata filter is run. The function
* dynamic_output_buffer_test() is hooked on to it. Since DYNAMIC_OB_TEXT is
* set it replaces the placeholder text with that constant.
* The resulting html is then sent to the browser.
* Already cached pages call the safety filter, and then the wpsc_cachedata
* filter so any hooked function must be ready to generate dynamic content. The
* very last line of dynamic_output_buffer_test() replaces the placeholder tag
* with the dynamic content in the cache file.
* Use an output buffer to capture dynamic content while the page is generated
* and insert into the right place:
* Remember to add the DYNAMIC_OUTPUT_BUFFER_TAG text (as defined below) to
* your theme where the dynamic content should be.
* dynamic_output_buffer_test() is a function that uses the wpsc_cachedata
* filter to add a small message and the current server time to every web
* page. The time increments on every reload.
define( 'DYNAMIC_OUTPUT_BUFFER_TAG', '' ); // Change this to a secret placeholder tag.
function dynamic_output_buffer_test( $cachedata = 0 ) {
if ( defined( 'DYNAMIC_OB_TEXT' ) ) {
return str_replace( DYNAMIC_OUTPUT_BUFFER_TAG, DYNAMIC_OB_TEXT, $cachedata );
// call the sidebar function, do something dynamic
echo '<p>This is a test. The current time on the server is: ' . date( 'H:i:s' ) . '</p>';
$text = ob_get_contents();
if ( 0 === $cachedata ) { // called directly from the theme so store the output.
define( 'DYNAMIC_OB_TEXT', $text );
} else { // called via the wpsc_cachedata filter. We only get here in cached pages in wp-cache-phase1.php.
return str_replace( DYNAMIC_OUTPUT_BUFFER_TAG, $text, $cachedata );
add_cacheaction( 'wpsc_cachedata', 'dynamic_output_buffer_test' );
function dynamic_output_buffer_init() {
add_action( 'wp_footer', 'dynamic_output_buffer_test' );
add_cacheaction( 'add_cacheaction', 'dynamic_output_buffer_init' );
function dynamic_output_buffer_test_safety( $safety ) {
if ( defined( 'DYNAMIC_OB_TEXT' ) ) {// this is set when you call dynamic_output_buffer_test() from the theme.
return 1; // ready to replace tag with dynamic content.
} else {
return 0; // tag cannot be replaced.
add_cacheaction( 'wpsc_cachedata_safety', 'dynamic_output_buffer_test_safety' );
You can’t perform that action at this time.