README

Simple and transparent HTTP response caching middleware for Guzzle, works well with Laravel or with any caching library implementing the PSR-16 caching interface.

Installation

You can install the library with Composer: composer require brightfish/caching-guzzle

How to use

The registration of the middleware follows Guzzle's documentation:

/** @var \Psr\SimpleCache\CacheInterface $cache */
$cache = app('cache')->store('database'); // Laravel example, but any PSR-16 cache will do

$middleware = new \Brightfish\CachingGuzzle\Middleware($cache);

$stack = \GuzzleHttp\HandlerStack::create();

$stack->push($middleware);

$client = new \GuzzleHttp\Client([
    'handler' => $stack,
    'base_uri' => 'https://example.org/api/'
]);

Instantiation parameters

Next to a PSR-16 compliant cache, the middleware takes two optional parameters:

$ttl, the default cache duration, which can be overridden by each request
$log, instructs the package to log cache hits Laravel's log or PHP's default error_log (see source).

$middleware = new \Brightfish\CachingGuzzle\Middleware($store, $ttl = 60, $log = true);

Making requests

Available options:

Option	Type	Default	Description
`cache`	bool	`true`	Completely disable the cache for this request
`cache_anew`	bool	`false`	Bypass the cache and replace it with the new response
`cache_ttl`	int	`60`	Cache duration in seconds, use `-1` to cache forever
`cache_key`	string	`true`	Cache key to override the default one based on the request URI (see Cache retrieval)

Example: cache the response for 90s (default: 60)

$response_1 = $guzzleClient->get('resource', [
    'cache_ttl' => 90
]);

Example: request anew and update the cache

$response_3 = $guzzleClient->post('resource/84', [
    'cache_anew' => true
]);

Example: disable caching

$response_2 = $guzzleClient->post('resource/84', [
    'cache' => false
]);

Example: cache forever with a custom key

$response_4 = $guzzleClient->post('resource/84', [
    'cache_key' => 'my-key',
    'cache_ttl' => -1
]);

If cache_ttl is set to 0 the response will not be cached, but, contrary to 'cache' => false, it may be retrieved from it.

Example: cache retrieval

# Get response_1 from cache.
$cached_response_1 = $cache->get('//example.org/api/resource');

# Get response_4 from cache.
$cached_response_4 = $cache->get('my-key');

Using the wrapper

Instead of manually configuring Guzzle's client and the caching middleware, it is also possible to instantiate the Client class provided by this package. This way, the binding of the middleware is done for you.

use Brightfish\CachingGuzzle\Client;

/** @var \Psr\SimpleCache\CacheInterface $store */
$psrCompatibleCache = new Cache();

$client = new Client($psrCompatibleCache, [
    'cache_ttl' => 60,	   // default cache duration
    'cache_log' => false,  // log the cache hits
    // Guzzle options:
    'base_uri' => 'https://example.org/api/'
    // ...
]);

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

GNU General Public License (GPL). Please see the license file for more information.

brightfish / caching-guzzle

Maintainers

Details