diff --git a/README.md b/README.md index bfcf70c..af4f1b5 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,14 @@ # WordPress Output Buffering -A simple [mu-plugin](https://codex.wordpress.org/Must_Use_Plugins) that buffers the entire WP process, capturing the final output for manipulation. +A simple [mu-plugin](https://codex.wordpress.org/Must_Use_Plugins) that buffers the entire WP process, capturing the final output for DOM manipulation. [Original code](http://stackoverflow.com/a/22818089/3799374) by [kfriend](https://stackoverflow.com/users/419673/kfriend) on Stack Overflow. Licensed as GPL because it is a WordPress derivative. -### Example Usage +### Usage + +##### Simple Example + +This code will replace any instance of "foo" on the web page with "bar": ``` add_filter( 'final_output', function($output) { @@ -12,10 +16,41 @@ add_filter( 'final_output', function($output) { }); ``` +### Configuration + +By default, output buffering is only **enabled** on the *frontend* of the site and is **disabled** for *WP Admin* and during *AJAX* requests. + +You can modify this behavior and specify on which request/screen types that you want to enable it by adding the following constants to `wp-config.php`: + +##### PHP (any version) + +``` +define( 'OB_ENABLE_ADMIN', true ); // Enables output buffering in WP Admin +define( 'OB_ENABLE_AJAX', true ); // Enables output buffering during AJAX calls +``` + +##### PHP 7.0 and Higher + +``` +define( 'OB_REQUEST_TYPES', array( 'site', 'admin', 'ajax' ) ); // Case-sensitive +``` + +In the example above, output buffering is enable on the frontend ("site"), in WP Admin ("admin") and during AJAX requests ("ajax"). Add or remove from the array as desired. For example, to **only** load output buffering in WP Admin and **not** on the frontend or during AJAX calls: + +``` +define( 'OB_ENABLE_SCREENS', array( 'admin' ) ); // Case-sensitive +``` + +##### Caution + +Take care when changing this behavior! You may experience issues when enabling in WP Admin or during AJAX calls if your manipulation logic interferes with normal WordPress function. + +Always test first before using in a production setting! + ## Changelog -**1.0.2 (master)** -* Disabled in WP Admin and when DOING_AJAX +**1.0.3 (master)** +* Added wp-config.php constants to control where output buffering is enabled. **1.0.0** * Initial commit diff --git a/output-buffering.php b/output-buffering.php index 7bb28b4..fd22619 100644 --- a/output-buffering.php +++ b/output-buffering.php @@ -4,7 +4,7 @@ * Plugin Name: Output Buffering * Plugin URI: https://github.com/dmhendricks/wordpress-output-buffering * Description: Buffers the entire WP process, capturing the final output for manipulation. - * Version: 1.0.2 + * Version: 1.0.3 * Author: Daniel M. Hendricks * Original Author: kfriend (https://stackoverflow.com/users/419673/kfriend) * Author URI: https://www.danhendricks.com @@ -12,23 +12,94 @@ * License URI: https://opensource.org/licenses/GPL-2.0 * GitHub Plugin URI: dmhendricks/wordpress-output-buffering */ +namespace TwoLab\MustUse; -ob_start(); +class OutputBuffering { -if( !is_admin() && !( defined('DOING_AJAX') && DOING_AJAX ) ) { - add_action('shutdown', function() { - $final = ''; + public function __construct() { - // We'll need to get the number of OB levels we're in, so that we can iterate over each, collecting - // that buffer's output into the final output. - $levels = ob_get_level(); - for ($i = 0; $i < $levels; $i++) - { - $final .= ob_get_clean(); + if($this->can_load()) $this->output_buffering(); + + } + + /** + * Returns string of addition CSS classes based on post type + * + * Returns CSS classes such as page-{slug}, parent-{slug}, post-type-{type} and + * category-{slug} for easier selector targeting + * + * @param array $classes An array of *current* body_class classes + * @return array Modified array of body classes including new ones + */ + public function output_buffering() { + + ob_start(); + + add_action('shutdown', function() { + $final = ''; + + // Iterate over each OB level + $levels = ob_get_level(); + for ($i = 0; $i < $levels; $i++) + { + $final .= ob_get_clean(); + } + + // Apply any filters to the final output + echo apply_filters('final_output', $final); + }, 0); + + } + + /** + * Get a list of screens/requests types to enable output buffering for. + * 'site' for frontend (default), 'admin' for WP Admin, 'ajax' for AJAX requests. + * + * @return array + */ + private function get_load_screens() { + + if( defined('OB_ENABLE_SCREENS')) { + return is_array(OB_ENABLE_SCREENS) ? OB_ENABLE_SCREENS : array( OB_ENABLE_SCREENS ); } - // Apply any filters to the final output - echo apply_filters('final_output', $final); - }, 0); + $screens = array( 'site' ); + if( defined('OB_ENABLE_ADMIN') || defined('OB_ENABLE_AJAX') ) { + if( defined('OB_ENABLE_ADMIN') && OB_ENABLE_ADMIN ) $screens[] = 'admin'; + if( defined('OB_ENABLE_AJAX') && OB_ENABLE_AJAX ) $screens[] = 'ajax'; + } + + return $screens; + + } + + /** + * Determine if output buffering should be enabled on frontend (default), WP Admin, + * and/or while doing AJAX requests. + * + * @return bool Whether or not output buffering should be performed. + */ + private function can_load() { + + $load_screens = $this->get_load_screens(); + $load_admin = is_admin() && in_array( 'admin', $load_screens ); + $load_ajax = $this->is_ajax() && in_array( 'ajax', $load_screens ); + $load_site = (!is_admin() && !$this->is_ajax()) && in_array( 'site', $load_screens ); + + return $load_admin || $load_ajax || $load_site; + + } + + /** + * Determine if current request is AJAX + * + * @return bool + */ + private function is_ajax() { + return defined('DOING_AJAX') && DOING_AJAX; + } + } + +new OutputBuffering(); ?>