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..00d9e28499 100644 --- a/en/core-libraries/caching.rst +++ b/en/core-libraries/caching.rst @@ -131,6 +131,38 @@ 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. + +.. versionadded:: 3.5.0 + Cache engine fallbacks were added. + Removing Configured Cache Engines ---------------------------------