README

Simple HTTP WordPress Cache for WordPress

Requirements

PHP 7.0+ WordPress 4.9.8+

Installation

Basic Installation

This is a WordPress plugin, and can be installed following these instructions.

via Composer

Composer is a PHP dependency manager.

You will need to install composer first, before using it.

To install this plugin as a dependency run the following in your WordPress install root folder with a composer.json file present:

composer require edwincromleydev/simple-wp-http-cache:dev-master

Make sure your composer.json file uses installer paths to move the dependency into your plugins folder. Here is a the config needed for a default WordPress install:

"extra": {
	"installer-paths": {
		"wp-content/plugins/{$name}": ["type:wordpress-plugin"]
	}
}

This will install the plugin inside of wp-content/plugins with the matching plugin name.

This plugin is not available on WPPackagist.

Usage

Fundamentals

Simple WP HTTP Cache builds on top of WordPress's internal WP_HTTP API.

Any request using WordPress's WP HTTP, can be passed an additional argument to control the functionality of the Simple HTTP caching and logging. Below is an example of how to cache a network request:

$response = wp_safe_remote_get(
	'https://edwincromley.com/wp-json/wp/v2/posts?per_page=1',
	[
		'simple_wp_http_cache' => [
			'active' => true,
		],
	]
);

This will store the response value by default for 5 minutes, preventing any repeating calls in that time frame from reaching out over the network.

There are a number of arguments that can be added to simple_wp_http_cache.

`'active'`

Sets the cache to active, meaning it will cache any uncached or bypassed requests. This will only cache successful requests, that reach the network. Internal WP failures will not be cached by default. The active parameter is only in charge of whether a fresh cache is set, not whether it is fetched. If active is set to any value other than true, or not set at all, and there is a previously cached result for the same request, the cached value will still be returned.

[
	'simple_wp_http_cache' => [
		'active' => true,
	],
]

`'expiration'`

The expiration of the cache set in seconds. Defaults to 300; 5 minutes.

To store the value indefinitely pass a value of 0 like so:

[
	'simple_wp_http_cache' => [
		'active' => true,
		'expiration' => 0,
	],
]

Expiration can be changed from the 'simple_wp_http_cache_expiration' filter.

apply_filters( 'simple_wp_http_cache_expiration', $request['simple_wp_http_cache']['expiration'] ?? 300, $response, $request, $url );

`'bypass'`

By setting bypass to true you can avoid the cache hits. In the example below, a new cache value will be set every time. The cache lookup is bypassed, and the request goes through and the new response value is cached due to the active flag. The following is really only useful for debugging and not recommended for any other reason:

[
	'simple_wp_http_cache' => [
		'active' => true,
		'bypass' => true,
	],
]

`'log_errors'`

log_errors is used to ensure that any internal WP Failures, or network request failures are passed to the Logger. By default, if you have both WP_DEBUG and WP_DEBUG_LOG enabled, the message will be output to WordPress's error log.

Alternative logging solutions can be implemented based on request, or response.

[
	'simple_wp_http_cache' => [
		'log_errors' => true,
	],
]

Whether the response is something that should be logged as an error can be handled via the simple_wp_http_cache_is_error filter. Which expects a boolean.

apply_filters( 'simple_wp_http_cache_is_error', $is_error, $response, $request, $url );

`'log_request_times'`

log_request_times is used to log any request that reaches the network, and displays the response time in milliseconds. Requests that are cached, will not log by default on a cache hit, only on a cache miss.

[
	'simple_wp_http_cache' => [
		'log_request_times' => true,
	],
]

Caching

Simple WP HTTP Cache makes use of WordPress' internal caching APIs. If WP_CACHE is set to true, the Object Cache that is configured for WordPress will be used. If WP_CACHE is not enabled, then the Transients API will be used as a fallback.

Requests are cached by the request parameters being sent as well as the URL. Any change in the request parameters or URL will result in a cache miss. The cache key is generated using sha1, to create a hash, and the likelihood of any collisions is extremely low.

You can pass the caching arguments directly to any HTTP function call like wp_safe_remote_get, or you can leverage WordPress' internal hooks to set the parameters for Simple WP HTTP Cache.

The following example will cache every request WordPress makes for 10 minutes:

add_filter( 'http_request_args', function( $request ) {
	$request['simple_wp_http_cache'] = [
		'active'     => true,
		'expiration' => 600,
	];

	return $request;
}, 1, 1 );

The above is not advised, but you can get a sense for the flexibility of this plugin.

Logging

Simple WP HTTP Cache also features a pluggable Logger class. You can override the base Logger with a matching class of your own. The current Logger is based around the PSR-3 interface, and will likely be changed to match that in the future.

If you have a custom Logger class, make sure it has the method log with the following signature:

public function log( $level, $message, array $context = array() ) {
	// Log my stuff here.
}

A basic custom logging class might look something like this:

/**
 * My custom logger.
 */
class MyLogger {
	/**
	 * Constructs log object.
	 *
	 * @return void
	 */
	public function __construct() {
		return;
	}

	/**
	 * Logs with an arbitrary level.
	 *
	 * @param mixed  $level
	 * @param string $message
	 * @param array  $context
	 * @return void
	 */
	public function log( $level, $message, array $context = array() ) {
		// Log your message to wherever it should go.
	}
}

Then you can use your custom class like so:

add_filter( 'simple_wp_http_cache_log_class', function( $class ) {
	$class = '\MyLogger';

	return $class;
} );

Now whenever any responses are sent to be logged, they will go through your custom class. You can take advantage of the 'simple_wp_http_cache_log_class' hook to implement your logging strategy. Rather than writing complex log methods for one class, it is recommended that you create multiple classes with a log method that fits that particular use case.

Wrap Up

Simple WP HTTP Cache is a basic enhancement to WordPress's existing HTTP API, enabling the ability to quickly cache particular requests, or log out errors and response times. The abilities are actually quite flexible and pluggable, as they leverage various hooks in WordPress.

edwincromleydev / simple-wp-http-cache

Maintainers

Details