summaryrefslogtreecommitdiff
path: root/vendor/guzzle/guzzle/docs/plugins/cache-plugin.rst
diff options
context:
space:
mode:
Diffstat (limited to 'vendor/guzzle/guzzle/docs/plugins/cache-plugin.rst')
-rw-r--r--vendor/guzzle/guzzle/docs/plugins/cache-plugin.rst169
1 files changed, 169 insertions, 0 deletions
diff --git a/vendor/guzzle/guzzle/docs/plugins/cache-plugin.rst b/vendor/guzzle/guzzle/docs/plugins/cache-plugin.rst
new file mode 100644
index 0000000..d2fd5df
--- /dev/null
+++ b/vendor/guzzle/guzzle/docs/plugins/cache-plugin.rst
@@ -0,0 +1,169 @@
+=================
+HTTP Cache plugin
+=================
+
+Guzzle can leverage HTTP's caching specifications using the ``Guzzle\Plugin\Cache\CachePlugin``. The CachePlugin
+provides a private transparent proxy cache that caches HTTP responses. The caching logic, based on
+`RFC 2616 <http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html>`_, uses HTTP headers to control caching behavior,
+cache lifetime, and supports Vary, ETag, and Last-Modified based revalidation:
+
+.. code-block:: php
+
+ use Guzzle\Http\Client;
+ use Doctrine\Common\Cache\FilesystemCache;
+ use Guzzle\Cache\DoctrineCacheAdapter;
+ use Guzzle\Plugin\Cache\CachePlugin;
+ use Guzzle\Plugin\Cache\DefaultCacheStorage;
+
+ $client = new Client('http://www.test.com/');
+
+ $cachePlugin = new CachePlugin(array(
+ 'storage' => new DefaultCacheStorage(
+ new DoctrineCacheAdapter(
+ new FilesystemCache('/path/to/cache/files')
+ )
+ )
+ ));
+
+ // Add the cache plugin to the client object
+ $client->addSubscriber($cachePlugin);
+ $client->get('http://www.wikipedia.org/')->send();
+
+ // The next request will revalidate against the origin server to see if it
+ // has been modified. If a 304 response is received the response will be
+ // served from cache
+ $client->get('http://www.wikipedia.org/')->send();
+
+The cache plugin intercepts GET and HEAD requests before they are actually transferred to the origin server. The cache
+plugin then generates a hash key based on the request method and URL, and checks to see if a response exists in the cache. If
+a response exists in the cache, the cache adapter then checks to make sure that the caching rules associated with the response
+satisfy the request, and ensures that response still fresh. If the response is acceptable for the request any required
+revalidation, then the cached response is served instead of contacting the origin server.
+
+Vary
+----
+
+Cache keys are derived from a request method and a request URL. Multiple responses can map to the same cache key and
+stored in Guzzle's underlying cache storage object. You should use the ``Vary`` HTTP header to tell the cache storage
+object that the cache response must have been cached for a request that matches the headers specified in the Vary header
+of the request. This allows you to have specific cache entries for the same request URL but variations in a request's
+headers determine which cache entry is served. Please see the http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.44
+for more information.
+
+Cache options
+-------------
+
+There are several options you can add to requests or clients to modify the behavior of the cache plugin.
+
+Override cache TTL
+~~~~~~~~~~~~~~~~~~
+
+You can override the number of seconds a cacheable response is stored in the cache by setting the
+``cache.override_ttl`` parameter on the params object of a request:
+
+.. code-block:: php
+
+ // If the response to the request is cacheable, then the response will be cached for 100 seconds
+ $request->getParams()->set('cache.override_ttl', 100);
+
+If a response doesn't specify any freshness policy, it will be kept in cache for 3600 seconds by default.
+
+Custom caching decision
+~~~~~~~~~~~~~~~~~~~~~~~
+
+If the service you are interacting with does not return caching headers or returns responses that are normally
+something that would not be cached, you can set a custom ``can_cache`` object on the constructor of the CachePlugin
+and provide a ``Guzzle\Plugin\Cache\CanCacheInterface`` object. You can use the
+``Guzzle\Plugin\Cache\CallbackCanCacheStrategy`` to easily make a caching decision based on an HTTP request and
+response.
+
+Revalidation options
+~~~~~~~~~~~~~~~~~~~~
+
+You can change the revalidation behavior of a request using the ``cache.revalidate`` parameter. Setting this
+parameter to ``never`` will ensure that a revalidation request is never sent, and the response is always served from
+the origin server. Setting this parameter to ``skip`` will never revalidate and uses the response stored in the cache.
+
+Normalizing requests for caching
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use the ``cache.key_filter`` parameter if you wish to strip certain query string parameters from your
+request before creating a unique hash for the request. This parameter can be useful if your requests have query
+string values that cause each request URL to be unique (thus preventing a cache hit). The ``cache.key_filter``
+format is simply a comma separated list of query string values to remove from the URL when creating a cache key.
+For example, here we are saying that the ``a`` and ``q`` query string variables should be ignored when generating a
+cache key for the request:
+
+.. code-block:: php
+
+ $request->getParams()->set('cache.key_filter', 'a, q');
+
+Other options
+~~~~~~~~~~~~~
+
+There are many other options available to the CachePlugin that can meet almost any caching requirement, including
+custom revalidation implementations, custom cache key generators, custom caching decision strategies, and custom
+cache storage objects. Take a look the constructor of ``Guzzle\Plugin\Cache\CachePlugin`` for more information.
+
+Setting Client-wide cache settings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can specify cache settings for every request created by a client by adding cache settings to the configuration
+options of a client.
+
+.. code-block:: php
+
+ $client = new Guzzle\Http\Client('http://www.test.com', array(
+ 'request.params' => array(
+ 'cache.override_ttl' => 3600,
+ 'params.cache.revalidate' => 'never'
+ )
+ ));
+
+ echo $client->get('/')->getParams()->get('cache.override_ttl');
+ // >>> 3600
+
+ echo $client->get('/')->getParams()->get('cache.revalidate');
+ // >>> never
+
+Cache revalidation
+------------------
+
+If the cache plugin determines that a response to a GET request needs revalidation, a conditional GET is transferred
+to the origin server. If the origin server returns a 304 response, then a response containing the merged headers of
+the cached response with the new response and the entity body of the cached response is returned. Custom revalidation
+strategies can be injected into a CachePlugin if needed.
+
+Cache adapters
+--------------
+
+Guzzle doesn't try to reinvent the wheel when it comes to caching or logging. Plenty of other frameworks have
+excellent solutions in place that you are probably already using in your applications. Guzzle uses adapters for
+caching and logging. The cache plugin requires a cache adapter so that is can store responses in a cache. Guzzle
+currently supports cache adapters for `Doctrine 2.0 <http://www.doctrine-project.org/>`_ and the
+`Zend Framework <http://framework.zend.com>`_.
+
+Doctrine cache adapter
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: php
+
+ use Doctrine\Common\Cache\ArrayCache;
+ use Guzzle\Cache\DoctrineCacheAdapter;
+ use Guzzle\Plugin\Cache\CachePlugin;
+
+ $backend = new ArrayCache();
+ $adapter = new DoctrineCacheAdapter($backend);
+ $cache = new CachePlugin($adapter);
+
+Zend Framework cache adapter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: php
+
+ use Guzzle\Cache\ZendCacheAdapter;
+ use Zend\Cache\Backend\TestBackend;
+
+ $backend = new TestBackend();
+ $adapter = new ZendCacheAdapter($backend);
+ $cache = new CachePlugin($adapter);