From c83367674dab16281a9331563573dc1a37d16a3f Mon Sep 17 00:00:00 2001 From: Jeremy Harris Date: Wed, 21 Jun 2017 20:08:56 -0500 Subject: [PATCH 1/2] Documenting cache fallback --- en/appendices/3-5-migration-guide.rst | 11 ++++++++++ en/core-libraries/caching.rst | 29 +++++++++++++++++++++++++++ 2 files changed, 40 insertions(+) diff --git a/en/appendices/3-5-migration-guide.rst b/en/appendices/3-5-migration-guide.rst index f50c3753e9..018466cdd8 100644 --- a/en/appendices/3-5-migration-guide.rst +++ b/en/appendices/3-5-migration-guide.rst @@ -119,10 +119,21 @@ behavior that may affect your application: defaults alone. * ``Cake\ORM\Table::addBehavior()`` and ``removeBehavior()`` now return ``$this`` to assist in defining table objects in a fluent fashion. +* Cache engines no longer throw an exception when they fail or are misconfigured, + but instead fall back to the noop ``NullEngine``. Fallbacks can also be + :ref:`configured ` on a per-engine basis. New Features ============ +Cache +----- + +* Cache engines can now be configured with a ``fallback`` key that defines a + cache configuration to fall back to if the engine is misconfigured (or + unavailable). See :ref:`cache-configuration-fallback` for more information on + configuring fallbacks. + Core ---- diff --git a/en/core-libraries/caching.rst b/en/core-libraries/caching.rst index 7f70b9a74a..e26602e5aa 100644 --- a/en/core-libraries/caching.rst +++ b/en/core-libraries/caching.rst @@ -131,6 +131,35 @@ refer to the class name using the following syntaxes: When using the FileEngine you might need to use the ``mask`` option to ensure cache files are made with the correct permissions. +.. _cache-configuration-fallback: + +Configuring Cache Fallbacks +--------------------------- + +In the event that an engine is not available, such as the ``FileEngine`` trying +to write to an unwritable folder or the ``RedisEngine`` failing to connect to +Redis, the engine will fall back to the noop ``NullEngine`` and trigger a loggable +error. This prevents the application from throwing an uncaught exception due to +cache failure. + +You can configure Cache configurations to fall back to a specified config using +the ``fallback`` configuration key:: + + Cache::config('redis', [ + 'className' => 'Redis', + 'duration' => '+1 hours', + 'prefix' => 'cake_redis_', + 'host' => '127.0.0.1', + 'port' => 6379, + 'fallback' => 'default', + ]); + +If the Redis server unexpectedly failed, writing to the ``redis`` cache +configuration would fall back to writing to the ``default`` cache configuration. +If writing to the ``default`` cache configuration *also* failed in this scenario, the +engine would fall back once again to the ``NullEngine`` and prevent the application +from throwing an uncaught exception. + Removing Configured Cache Engines --------------------------------- From ee4d840b8298cbc6a4d81428013f662a2cf0d5af Mon Sep 17 00:00:00 2001 From: Jeremy Harris Date: Wed, 21 Jun 2017 20:55:19 -0500 Subject: [PATCH 2/2] Added version note for cache fallbacks --- en/core-libraries/caching.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/en/core-libraries/caching.rst b/en/core-libraries/caching.rst index e26602e5aa..00d9e28499 100644 --- a/en/core-libraries/caching.rst +++ b/en/core-libraries/caching.rst @@ -160,6 +160,9 @@ If writing to the ``default`` cache configuration *also* failed in this scenario engine would fall back once again to the ``NullEngine`` and prevent the application from throwing an uncaught exception. +.. versionadded:: 3.5.0 + Cache engine fallbacks were added. + Removing Configured Cache Engines ---------------------------------