Skip to content

Commit 203a6b5

Browse files
Nyholmdbu
authored andcommitted
Added more options examples (#144)
cache plugin options documentation
1 parent a38beef commit 203a6b5

File tree

1 file changed

+63
-7
lines changed

1 file changed

+63
-7
lines changed

plugins/cache.rst

Lines changed: 63 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,9 @@ control headers from the server as specified in :rfc:`7234`. It needs a
2121
use Http\Client\Common\Plugin\CachePlugin;
2222

2323
/** @var \Psr\Cache\CacheItemPoolInterface $pool */
24-
$pool...
24+
$pool = ...
2525
/** @var \Http\Message\StreamFactory $streamFactory */
26-
$streamFactory...
26+
$streamFactory = ...
2727

2828
$options = [];
2929
$cachePlugin = new CachePlugin($pool, $streamFactory, $options);
@@ -33,22 +33,78 @@ control headers from the server as specified in :rfc:`7234`. It needs a
3333
[$cachePlugin]
3434
);
3535

36-
By default, responses with no cache control headers are not cached. If you want
37-
a default cache lifetime if the server specifies no ``max-age``, use::
36+
Options
37+
-------
38+
39+
The third parameter to the ``CachePlugin`` constructor takes an array of options. The plugin has 3 options you can
40+
configure. Their default values and meaning is described by the table below.
41+
42+
+---------------------------+---------------+------------------------------------------------------+
43+
| Name | Default value | Description |
44+
+===========================+===============+======================================================+
45+
| ``default_ttl`` | ``0`` | The default max age of a Response |
46+
+---------------------------+---------------+------------------------------------------------------+
47+
| ``respect_cache_headers`` | ``true`` | Whatever or not we should care about cache headers |
48+
+---------------------------+---------------+------------------------------------------------------+
49+
| ``cache_lifetime`` | 30 days | The minimum time we should store a cache item |
50+
+---------------------------+---------------+------------------------------------------------------+
51+
52+
.. note::
53+
54+
A HTTP response may have expired but it is still in cache. If so, headers like ``If-Modified-Since`` and
55+
``If-None-Match`` are added to the HTTP request to allow the server answer with 304 status code. When
56+
a 304 response is received we update the CacheItem and save it again for at least ``cache_lifetime``.
57+
58+
Using these options together you can control how your responses should be cached. By default, responses with no
59+
cache control headers are not cached. If you want a default cache lifetime if the server specifies no ``max-age``, use::
3860

3961
$options = [
4062
'default_ttl' => 42, // cache lifetime time in seconds
4163
];
4264

43-
You can also tell the plugin to completely ignore the cache control headers
44-
from the server and force caching for the default time to life. Note that in
45-
this case, ``default_ttl`` is required::
65+
You can tell the plugin to completely ignore the cache control headers from the server and force caching the response
66+
for the default time to live. The options below will cache all responses for one hour::
4667

4768
$options = [
4869
'default_ttl' => 3600, // cache for one hour
4970
'respect_cache_headers' => false,
5071
];
5172

73+
Semantics of null values
74+
````````````````````````
75+
76+
Setting null to the options ``cache_lifetime`` or ``default_ttl`` means "Store this as long as you can (forever)".
77+
This could be a great thing when you requesting a pay-per-request API (e.g. GoogleTranslate).
78+
79+
Store a response as long the cache implementation allows::
80+
81+
$options = [
82+
'default_ttl' => null,
83+
'respect_cache_headers' => false,
84+
'cache_lifetime' => null,
85+
];
86+
87+
88+
Ask the server if the response is valid at most ever hour. Store the cache item forever::
89+
90+
$options = [
91+
'default_ttl' => 3600,
92+
'respect_cache_headers' => false,
93+
'cache_lifetime' => null,
94+
];
95+
96+
97+
Ask the server if the response is valid at most ever hour. If the response has not been used within one year it will be
98+
removed from the cache::
99+
100+
$options = [
101+
'default_ttl' => 3600,
102+
'respect_cache_headers' => false,
103+
'cache_lifetime' => 86400*365, // one year
104+
];
105+
106+
107+
52108
Cache Control Handling
53109
----------------------
54110

0 commit comments

Comments
 (0)