Documenting cache fallback

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 <cache-configuration-fallback>` 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
 ----
 

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
 ---------------------------------