MemBlaze Full Page Cache for WordPress

Introduction

This system provides a robust full-page caching mechanism for WordPress sites using Memcached, significantly improving performance and reducing server load. It consists of two main components:

1. memblaze-full-page-cache.php: A WordPress plugin that provides an admin interface to configure the caching behavior, Memcached server(s), cache expiration rules, and generates necessary configuration files.
2. index-cached.php: A PHP front-controller script that sits in your WordPress root directory. It intercepts requests, attempts to serve pages from Memcached, or, if a page isn't cached or the cache is bypassed, it loads WordPress to generate the page and then stores it in Memcached for subsequent requests.

Features

• Memcached Integration: Leverages the speed and efficiency of Memcached for storing full HTML pages.
• Configurable Cache Times: Set a default cache expiration time and define specific cache durations for different URL paths (e.g., /blog/, /category/).
• Multiple Server Support: Configure one or more Memcached servers (TCP/IP or Unix sockets).
• Automatic Cache Purging:
  • Purges cache for individual posts/pages and the homepage when content is saved, updated, or deleted.
  • Bulk Actions: Purge cache for multiple posts directly from the WordPress post list.
  • Purge Method: Choose between precise purging of specific pages or flushing the entire cache on updates.
• Cache Pre-loading (Warmup):
  • On Save: Automatically visits the post and homepage after purging to regenerate the cache.
  • Scheduled: Automatically pre-cache a specified number of recent posts hourly.
  • WP-CLI: Command to manually warm up the cache.
• Asset Minification: Automatically minifies HTML, inline CSS, and inline JS to reduce page size and improve Core Web Vitals.
• Lazy Load (Experimental): Automatically adds loading="lazy" attributes to images and iframes to improve Core Web Vitals.
• Cookie-Based Cache Bypass: Define a list of cookie name prefixes. If a visitor has any of these cookies, the cache will be bypassed for them, ensuring dynamic content for logged-in users or users with specific session cookies (e.g., e-commerce carts).
• Admin Interface & Stats:
  • Dashboard Stats: View cache hit/miss ratios and server statistics.
  • Admin Bar: See cache status of the current page and purge it instantly.
• Debug Mode: Optional debug comments in the HTML output showing cache status and generation time.
• Nginx Configuration Generation: The plugin generates a sample Nginx configuration snippet to help direct requests to index-cached.php.
• Server Status Check: Test connectivity to your Memcached servers directly from the plugin settings page.
• Enterprise Ready:
  • Environment Configuration: Support for defining settings via wp-config.php constants for immutable deployments.
  • WP-CLI Support: Manage cache and check status via command line.
  • Site Health Integration: Built-in checks for Memcached connectivity.
  • Emergency Bypass: Instantly disable caching via a file trigger.

How it Works

1. Nginx Request Handling: The web server (Nginx) is configured to first check for static files. If a static file is not found and the request is for a PHP page, Nginx is configured to pass the request to index-cached.php instead of the standard index.php.
2. index-cached.php Interception:
   • Reads its configuration from wp-content/uploads/memblaze-full-page-cache/memcached-fp-config.php (generated by the plugin).
   • Checks if the current visitor has any cookies that match the "bypass cookies" list. If so, it proceeds to generate a fresh page without checking or storing to cache.
   • Determines the appropriate cache key based on the host and request URI.
   • Determines the cache expiration time based on configured rules or the default.
   • Attempts to fetch the page from Memcached using the cache key.
3. Cache Hit: If the page is found in Memcached and is not expired, index-cached.php serves the cached HTML directly to the visitor and exits.
4. Cache Miss/Bypass: If the page is not in Memcached, is expired, or the cache is bypassed:
   • index-cached.php captures the output of WordPress generating the page.
   • If caching is enabled for this request and not bypassed by a cookie, the generated HTML is stored in Memcached with the determined cache key and expiration time.
   • The freshly generated HTML is served to the visitor.

Setup and Installation

Prerequisites

• A WordPress installation.
• Memcached server(s) installed and running.
• The Memcached PECL extension for PHP installed and enabled.
• Nginx web server (recommended, as the system is primarily designed for it).

Step 1: Install Files

1. Plugin (memblaze-full-page-cache-config.php):

   • Place the entire memblaze-full-page-cache directory into your WordPress wp-content/plugins/ directory (or create a directory named memblaze-full-page-cache-config and place all plugin files there).
   • Activate the "Memcached Full Page Cache" plugin from the WordPress admin area.

2. Front Controller (index-cached.php):

   • Place the index-cached.php file into the root directory of your WordPress installation (the same directory where wp-config.php and the main index.php are located).

Step 2: Configure Nginx

You need to modify your Nginx configuration to direct appropriate requests to index-cached.php.

1. Generate Nginx Config:

   • Go to "MemBlaze Cache" in your WordPress admin menu.
   • Configure your Memcached server(s) under the "Memcached Servers" section.
   • Save the settings.
   • The plugin will generate two files in your wp-content/ directory:
     • memcached_upstream.conf: Contains the upstream memcached_servers { ... } block.
     • memcached_nginx.conf: Contains the location rules and logic for serving from Memcached.

2. Apply Nginx Configuration:

   • Include the Upstream Config: Copy wp-content/memcached_upstream.conf to /etc/nginx/conf.d/ or include it in your main nginx.conf within the http { ... } block.

   • Modify your site's server block: Include the generated memcached_nginx.conf in your server block:

     server {
         listen 80;
         server_name example.com;
         root /var/www/html; # Your WordPress root
     
         # Include the MemBlaze location rules
         include /var/www/path/to/wordpress/wp-content/memcached_nginx.conf;
     
         # ... other rules (static assets, security)
     }

3. Test Nginx Configuration: sudo nginx -t

4. Reload Nginx: sudo systemctl reload nginx

Step 3: Configure the Plugin

1. Navigate to "MemBlaze Cache" -> "Config" in your WordPress admin dashboard.
2. General Settings:
   • Enable Debug: Check this to add HTML comments at the end of your pages showing cache status (hit/miss, bypass reason) and generation time. Useful for testing.
   • Default Cache Time: Set the default expiration time in seconds for cached pages (e.g., 3600 for 1 hour).
   • Purge Cache on Actions: Enable to automatically clear relevant caches when posts/pages are saved, updated, or deleted.
   • Pre-load Cache: Automatically visit the post and homepage after purging to regenerate the cache.
   • Pre-cache Recent Posts: Number of recent posts/pages to automatically pre-cache (warm up) hourly.
   • Minify Assets: Automatically minifies HTML, inline CSS, and inline JS to reduce page size and improve Core Web Vitals.
   • Lazy Load: Enable experimental lazy loading for images and iframes.
   • Purge Method: Select "Purge Specific Pages" (default) or "Flush Entire Cache".
   • Bypass Cache for Cookies: Add cookie name prefixes (one per line) that should cause the cache to be bypassed. Defaults include common WordPress, WooCommerce, and other plugin cookies.
3. Memcached Servers:
   • Add your Memcached server(s) by specifying the Host (IP address, hostname, or path to Unix socket) and Port (e.g., 11211, or 0 for Unix sockets).
   • The "Status" column will attempt to connect and show if the server is reachable.
4. Cache Time Rules:
   • Define specific cache times for different URL paths.
   • Path: The URI path prefix (e.g., /blog/, /products/category/).
   • Time in Seconds: Cache duration for matching paths. 0 means do not cache.
   • Rules are matched in the order they appear. The first matching rule applies.
5. Content Type Rules:
   • Define specific Content-Types for URI paths. Useful for API endpoints or feeds. These rules override the default text/html.
   • URI Path Contains: URI to match
   • Content Type: The assigned content type for this URI path.
   • Actions: Option to delete an entry
6. Save Settings: Click "Save Settings". This updates the configuration files in wp-content/.

Step 4: Enterprise Configuration (Optional)

For enterprise environments, you can configure the plugin using constants in wp-config.php. This overrides database settings.

define( 'WP_MFPC_DEBUG', true );
define( 'WP_MFPC_DEFAULT_CACHE_TIME', 3600 );
define( 'WP_MFPC_SERVERS', [
    [ 'host' => '127.0.0.1', 'port' => '11211' ],
] );
define( 'WP_MFPC_RULES', [
    [ 'path' => '/', 'time' => 600 ],
] );
define( 'WP_MFPC_BYPASS_COOKIES', [
    'wordpress_logged_in_',
    'woocommerce_items_in_cart',
] );

Step 5: WP-CLI Usage

The plugin supports WP-CLI commands:

• wp mfpc flush <all|posts|pages> [<ids>]: Flush cache items (comma-separated IDs for posts/pages).
• wp mfpc status: Check connection status of servers.
• wp mfpc warmup [<count>]: Pre-cache recent posts/pages.
• wp mfpc warmup <all|posts|pages> [<ids>]: Pre-cache specific items (comma-separated IDs for posts/pages).
• wp mfpc generate-nginx: Regenerate configuration files.
• wp mfpc help: Display available commands.

Step 6: Emergency Bypass

To instantly disable the cache (e.g., during an incident), create a file named .mfpc-bypass in your WordPress root directory.

touch .mfpc-bypass

Step 7: Test

1. Open your website in a browser where you are not logged in (e.g., incognito mode).
2. View the page source. If debug is enabled, you should see a comment like: ``
3. Refresh the page. You should now see: ``
4. Log in to WordPress. Visit a page. You should see a bypass message if your login cookies are in the bypass list: ``
5. Test cache purging by editing and saving a post. The cache for that post and the homepage should be cleared.

Troubleshooting

• Permissions: Ensure your web server has write permissions to the wp-content/uploads/ directory to create the memblaze-full-page-cache/ folder and its contents.
• Memcached PECL Extension: Verify the Memcached PHP extension is installed and enabled (php -m | grep memcached).
• Memcached Server Running: Ensure your Memcached service is running and accessible from your web server.
• Nginx Configuration: Double-check your Nginx configuration. Incorrect try_files or fastcgi_index directives are common issues.
• Plugin Conflicts: Other caching plugins or security plugins might interfere. Test with a minimal set of plugins if you encounter issues.
• Debug Output: Use the plugin's debug mode and check your PHP error logs and Nginx error logs for clues.

Professional Services

Need help with installation, configuration, or customization? Contact me for professional services at emailme@erwinlomibao.com