WP-CLI - Prime the Page Cache

[amiga-500]

This adds the much desired cache preload feature to W3 Total Cache's WP-CLI space. It's the ability to prime the page cache from the command line. It was a feature request by WP forum users to ease the burden of script-managed re-caching of multiple sites remotely. It was also added to help flesh out W3 Total Cache's completeness when using WP-CLI.

Because the priming can potentially take very long to process it has been designed to run asynchronously in the background after initiating the request, thus, freeing up the command line prompt immediately. There is also a command to stop the running prime process, if needed.

This also fixes a few minor bugs in Cli.php: The Exception object was being incorrectly passed to the WP_CLI::Error() function in some areas, ironically, causing an exception error of its own. It seems the sprintf() wrapper was missing in a few spots and the object's getMessage() call was also missing. To save on an extra function call i just opted to concatenate the exception message string into their proper positions.

Important Coding Note

Since user's batch sizes can potentially be large enough that the time to process each batch can lead to another scheduled batch running while the previous one is not finished, this prime process keeps track of the active process IDs (each batch has its own process ID) so that if the user decides to stop the priming it can do so by terminating all active batch processes (e.g. via the "stop" CLI command or if they deactivate the plugin). To accomplish this it keeps track by writing a list of these active process IDs to disk or using an interprocess messaging system, depending on what is made available in the environment (posix or sysvmsg or exec).

It was determined that WP's database functions (and therefore, W3TC's new State class) was not suitable because since each batch process would need to write out their ID, the available db functions actually cached the response for that specific process ID and so when a different process ID updated the db entry, the original process ID would not be made aware of it -- it would just get served an old, outdated cached version. And so using direct file read/write or interprocess messaging was more efficient in this case to make sure all active processes were communicating correctly with the latest data when priming.

As a result, special w3tc_lock_read() w3tc_lock_write() functions were created to handle the proper reading/writing of files, accessed by mutli-processes, to disk (if using posix or exec). Note the use of clearstatcache() to prevent serving back cached versions of the file which is critical when multi-processes are being managed.

How the WP-CLI Prime Cache Works

Format:

wp w3-total-cache prime [stop] [--batch=<size>] [--interval=<seconds>] [--sitemap=<url>]

Because all the arguments are optional, if the arg is not present it will default to its corresponding user-set configuration value as seen in Page Cache's Cache Preload section.

Usage Examples:

• Begin priming the page cache using the already defined interval, batch size, and sitemap url values as shown under W3TC's Performance > Page Cache > Cache Preload section:

  wp w3-total-cache prime

• If the page cache is currently being primed this will end that process:

  wp w3-total-cache prime stop

• Begin priming the page cache at the rate of 2 pages every 30 seconds using the sitemap url held within W3TC's Performance > Page Cache > Cache Preload > Sitemap URL box:

  wp w3-total-cache prime --batch=2 --interval=30

• Using the provided sitemap url, its pages are primed in batch sizes (as defined by W3TC's Performance > Page Cache > Cache Preload > Pages per Interval box) every 30 seconds until all pages within the given sitemap is complete:

  wp w3-total-cache prime --interval=30 --sitemap=http://domain.com/sitemap.xml