From 2ceccfc67623bcb5f49ba8957d059dc80662f0dd Mon Sep 17 00:00:00 2001 From: Tobias Nyholm Date: Sat, 13 Aug 2016 18:48:26 +0200 Subject: [PATCH 1/7] Added more options examples This will hopefully clear out some confusions about how long the cache item and responses are stored. --- plugins/cache.rst | 70 ++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 63 insertions(+), 7 deletions(-) diff --git a/plugins/cache.rst b/plugins/cache.rst index 3fd459c..90aff52 100644 --- a/plugins/cache.rst +++ b/plugins/cache.rst @@ -21,9 +21,9 @@ control headers from the server as specified in :rfc:`7234`. It needs a use Http\Client\Common\Plugin\CachePlugin; /** @var \Psr\Cache\CacheItemPoolInterface $pool */ - $pool... + $pool = ... /** @var \Http\Message\StreamFactory $streamFactory */ - $streamFactory... + $streamFactory = ... $options = []; $cachePlugin = new CachePlugin($pool, $streamFactory, $options); @@ -33,22 +33,78 @@ control headers from the server as specified in :rfc:`7234`. It needs a [$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 +------- + +The third parameter to the ``CachePlugin`` constructor takes an array of options. The plugin has 3 options you can +configure. Their default values and meaning is described by the table below. + ++---------------------------+---------------+------------------------------------------------------+ +| Name | Default value | Description | ++===========================+===============+======================================================+ +| ``default_ttl`` | ``null`` | The default max age of a Response | ++---------------------------+---------------+------------------------------------------------------+ +| ``respect_cache_headers`` | ``true`` | Whatever or not we should care about cache headers | ++---------------------------+---------------+------------------------------------------------------+ +| ``cache_lifetime`` | 30 days | The minimum time we should store a cache item | ++---------------------------+---------------+------------------------------------------------------+ + +.. note:: + + A HTTP response may have expired but it is still in cache. If so, headers like ``If-Modified-Since`` and + ``If-None-Match`` are added to the HTTP request to allow the server answer with 304 status code. When + a 304 response is recieved we update the CacheItem and save it again for at least ``cache_lifetime``. + +Using these options together you may control the how your cached responses behave. 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:: +If you tell the plugin to completely ignore the cache control headers from the server and force caching the response +for the default time to life. The options below will cache all responses for one hour:: $options = [ 'default_ttl' => 3600, // cache for one hour 'respect_cache_headers' => false, ]; +Be ware of null values +`````````````````````` + +Setting null to the options ``cache_lifetime`` or ``default_ttl`` means "Store this as long as you can (forever)". +This could be a great thing when you requesting a pay-per-request API (eg. GoogleTranslate). + +Store a response as long the cache implementation allows:: + + $options = [ + 'default_ttl' => null, + 'respect_cache_headers' => false, + 'cache_lifetime' => null, + ]; + + +Ask the server if the response is valid at most ever hour. Store the cache item forever:: + + $options = [ + 'default_ttl' => 3600, + 'respect_cache_headers' => false, + 'cache_lifetime' => null, + ]; + + +Ask the server if the response is valid at most ever hour. If the response has not been used within 30 days it will be +removed from the cache:: + + $options = [ + 'default_ttl' => 3600, + 'respect_cache_headers' => false, + 'cache_lifetime' => 86400*30, // 30 days + ]; + + + Cache Control Handling ---------------------- From ddf65911e39ba8ef17565e89651da0c37fcdc416 Mon Sep 17 00:00:00 2001 From: Tobias Nyholm Date: Sun, 14 Aug 2016 00:40:49 +0200 Subject: [PATCH 2/7] Changed according to feedback --- plugins/cache.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/plugins/cache.rst b/plugins/cache.rst index 90aff52..4125c43 100644 --- a/plugins/cache.rst +++ b/plugins/cache.rst @@ -62,16 +62,16 @@ cache control headers are not cached. If you want a default cache lifetime if th 'default_ttl' => 42, // cache lifetime time in seconds ]; -If you tell the plugin to completely ignore the cache control headers from the server and force caching the response -for the default time to life. The options below will cache all responses for one hour:: +You can tell the plugin to completely ignore the cache control headers from the server and force caching the response +for the default time to live. The options below will cache all responses for one hour:: $options = [ 'default_ttl' => 3600, // cache for one hour 'respect_cache_headers' => false, ]; -Be ware of null values -`````````````````````` +Semantics of null values +```````````````````````` Setting null to the options ``cache_lifetime`` or ``default_ttl`` means "Store this as long as you can (forever)". This could be a great thing when you requesting a pay-per-request API (eg. GoogleTranslate). @@ -94,13 +94,13 @@ Ask the server if the response is valid at most ever hour. Store the cache item ]; -Ask the server if the response is valid at most ever hour. If the response has not been used within 30 days it will be +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 removed from the cache:: $options = [ 'default_ttl' => 3600, 'respect_cache_headers' => false, - 'cache_lifetime' => 86400*30, // 30 days + 'cache_lifetime' => 86400*365, // one year ]; From 94340009cf2def972fbfa9e4a30286b9ebfeb4a1 Mon Sep 17 00:00:00 2001 From: Tobias Nyholm Date: Sun, 14 Aug 2016 00:48:40 +0200 Subject: [PATCH 3/7] fixed spelling --- plugins/cache.rst | 2 +- spelling_word_list.txt | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/plugins/cache.rst b/plugins/cache.rst index 4125c43..9432c9b 100644 --- a/plugins/cache.rst +++ b/plugins/cache.rst @@ -53,7 +53,7 @@ configure. Their default values and meaning is described by the table below. A HTTP response may have expired but it is still in cache. If so, headers like ``If-Modified-Since`` and ``If-None-Match`` are added to the HTTP request to allow the server answer with 304 status code. When - a 304 response is recieved we update the CacheItem and save it again for at least ``cache_lifetime``. + a 304 response is received we update the CacheItem and save it again for at least ``cache_lifetime``. Using these options together you may control the how your cached responses behave. 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:: diff --git a/spelling_word_list.txt b/spelling_word_list.txt index 617f3a2..fdde20d 100644 --- a/spelling_word_list.txt +++ b/spelling_word_list.txt @@ -6,6 +6,7 @@ callables cURL Diactoros Elasticsearch +eg fallback GitHub hotfix From 7f0f1bf1ec707ea51df9948b9512248bed13fda7 Mon Sep 17 00:00:00 2001 From: Tobias Nyholm Date: Mon, 15 Aug 2016 08:46:08 +0200 Subject: [PATCH 4/7] Update cache.rst --- plugins/cache.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/cache.rst b/plugins/cache.rst index 9432c9b..a3f1c05 100644 --- a/plugins/cache.rst +++ b/plugins/cache.rst @@ -42,7 +42,7 @@ configure. Their default values and meaning is described by the table below. +---------------------------+---------------+------------------------------------------------------+ | Name | Default value | Description | +===========================+===============+======================================================+ -| ``default_ttl`` | ``null`` | The default max age of a Response | +| ``default_ttl`` | ``0`` | The default max age of a Response | +---------------------------+---------------+------------------------------------------------------+ | ``respect_cache_headers`` | ``true`` | Whatever or not we should care about cache headers | +---------------------------+---------------+------------------------------------------------------+ @@ -74,7 +74,7 @@ Semantics of null values ```````````````````````` Setting null to the options ``cache_lifetime`` or ``default_ttl`` means "Store this as long as you can (forever)". -This could be a great thing when you requesting a pay-per-request API (eg. GoogleTranslate). +This could be a great thing when you requesting a pay-per-request API (e.g. GoogleTranslate). Store a response as long the cache implementation allows:: From d8d0fef113d5c418c3f14abd21adbf2f62916b36 Mon Sep 17 00:00:00 2001 From: Tobias Nyholm Date: Mon, 15 Aug 2016 08:46:33 +0200 Subject: [PATCH 5/7] Update spelling_word_list.txt --- spelling_word_list.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/spelling_word_list.txt b/spelling_word_list.txt index fdde20d..617f3a2 100644 --- a/spelling_word_list.txt +++ b/spelling_word_list.txt @@ -6,7 +6,6 @@ callables cURL Diactoros Elasticsearch -eg fallback GitHub hotfix From 540c8262e6f12c104934f1c49325c4b812de75e1 Mon Sep 17 00:00:00 2001 From: Tobias Nyholm Date: Mon, 15 Aug 2016 09:15:14 +0200 Subject: [PATCH 6/7] syntax --- plugins/cache.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/cache.rst b/plugins/cache.rst index a3f1c05..35c3263 100644 --- a/plugins/cache.rst +++ b/plugins/cache.rst @@ -42,7 +42,7 @@ configure. Their default values and meaning is described by the table below. +---------------------------+---------------+------------------------------------------------------+ | Name | Default value | Description | +===========================+===============+======================================================+ -| ``default_ttl`` | ``0`` | The default max age of a Response | +| ``default_ttl`` | ``0`` | The default max age of a Response | +---------------------------+---------------+------------------------------------------------------+ | ``respect_cache_headers`` | ``true`` | Whatever or not we should care about cache headers | +---------------------------+---------------+------------------------------------------------------+ From 58a727cde189eb000e9e41b4131efe62d0ce15f6 Mon Sep 17 00:00:00 2001 From: Tobias Nyholm Date: Mon, 15 Aug 2016 09:24:15 +0200 Subject: [PATCH 7/7] typo --- plugins/cache.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/cache.rst b/plugins/cache.rst index 35c3263..febf6e5 100644 --- a/plugins/cache.rst +++ b/plugins/cache.rst @@ -55,7 +55,7 @@ configure. Their default values and meaning is described by the table below. ``If-None-Match`` are added to the HTTP request to allow the server answer with 304 status code. When a 304 response is received we update the CacheItem and save it again for at least ``cache_lifetime``. -Using these options together you may control the how your cached responses behave. By default, responses with no +Using these options together you can control how your responses should be cached. 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 = [