Skip to content

brightfish-be/caching-guzzle

Repository files navigation

HTTP caching middleware for Guzzle

Tests Latest Version on Packagist Downloads

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.