@@ -21,9 +21,9 @@ control headers from the server as specified in :rfc:`7234`. It needs a
21
21
use Http\Client\Common\Plugin\CachePlugin;
22
22
23
23
/** @var \Psr\Cache\CacheItemPoolInterface $pool */
24
- $pool...
24
+ $pool = ...
25
25
/** @var \Http\Message\StreamFactory $streamFactory */
26
- $streamFactory...
26
+ $streamFactory = ...
27
27
28
28
$options = [];
29
29
$cachePlugin = new CachePlugin($pool, $streamFactory, $options);
@@ -33,22 +33,78 @@ control headers from the server as specified in :rfc:`7234`. It needs a
33
33
[$cachePlugin]
34
34
);
35
35
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::
38
60
39
61
$options = [
40
62
'default_ttl' => 42, // cache lifetime time in seconds
41
63
];
42
64
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::
46
67
47
68
$options = [
48
69
'default_ttl' => 3600, // cache for one hour
49
70
'respect_cache_headers' => false,
50
71
];
51
72
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
+
52
108
Cache Control Handling
53
109
----------------------
54
110
0 commit comments