From 8e32cddc830ffe3c950d45d01b37b2468b4f8207 Mon Sep 17 00:00:00 2001 From: David Buchmann Date: Wed, 17 Feb 2016 12:10:36 +0100 Subject: [PATCH] document cache plugin --- plugins/cache.rst | 48 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 47 insertions(+), 1 deletion(-) diff --git a/plugins/cache.rst b/plugins/cache.rst index 319ce78..edfd2f3 100644 --- a/plugins/cache.rst +++ b/plugins/cache.rst @@ -1,4 +1,50 @@ Cache Plugin ============ -TODO +The ``CachePlugin`` allows you to cache responses from the server. It can use +any PSR-6 compatible caching engine. By default, the plugin respects the cache +control headers from the server as specified in :rfc:`7234`. It needs a +:ref:`stream ` and a `PSR-6`_ implementation:: + + use Http\Discovery\HttpClientDiscovery; + use Http\Client\Plugin\PluginClient; + use Http\Client\Plugin\CachePlugin; + + /** @var \Psr\Cache\CacheItemPoolInterface $pool */ + $pool... + /** @var \Http\Message\StreamFactory $streamFactory */ + $streamFactory... + + $options = []; + $cachePlugin = new CachePlugin($pool, $streamFactory, $options); + + $pluginClient = new PluginClient( + HttpClientDiscovery::find(), + [$cachePlugin] + ); + +By default, responses with no cache control headers are not cached. If you want +a default cache lifetime if the server specifies no ``max-age``, use:: + + $options = [ + 'default_ttl' => 42, // cache lifetime time in seconds + ]; + +You can also tell the plugin to completely ignore the cache control headers +from the server and force caching for the default time to life. Note that in +this case, ``default_ttl`` is required:: + + $options = [ + 'default_ttl' => 3600, // cache for one hour + 'respect_cache_headers' => false, + ]; + +Cache Control Handling +---------------------- + +This plugin does not cache responses with ``no-store`` or ``private`` instructions. + +It does store responses with cookies or a ``Set-Cookie`` header. Be careful with +the order of your plugins. + +.. _PSR-6: http://www.php-fig.org/psr/psr-6/