diff --git a/cache.rst b/cache.rst
index cbfc178da54..4d82e5b176f 100644
--- a/cache.rst
+++ b/cache.rst
@@ -52,50 +52,6 @@ of:
Redis and Memcached are example of such adapters. If a DSN is used as the
provider then a service is automatically created.
-There are two pools that are always enabled by default. They are ``cache.app`` and
-``cache.system``. The system cache is used for things like annotations, serializer,
-and validation. The ``cache.app`` can be used in your code. You can configure which
-adapter (template) they use by using the ``app`` and ``system`` key like:
-
-.. configuration-block::
-
- .. code-block:: yaml
-
- # config/packages/cache.yaml
- framework:
- cache:
- app: cache.adapter.filesystem
- system: cache.adapter.system
-
- .. code-block:: xml
-
-
-
-
-
-
-
-
-
-
- .. code-block:: php
-
- // config/packages/cache.php
- $container->loadFromExtension('framework', [
- 'cache' => [
- 'app' => 'cache.adapter.filesystem',
- 'system' => 'cache.adapter.system',
- ],
- ]);
-
The Cache component comes with a series of adapters pre-configured:
* :doc:`cache.adapter.apcu `
@@ -182,6 +138,81 @@ will create pools with service IDs that follow the pattern ``cache.[type]``.
],
]);
+System Cache and Application Cache
+----------------------------------
+
+There are two pools that are always enabled by default. They are
+``cache.system`` and ``cache.app``.
+
+The system cache ``cache.system`` is mainly used by Symfony components for
+things like annotations, serializer, and validation. For advanced use-cases it
+is also available for application code under the following constraints:
+
+- Entries are derived from source code and can be generated during cache warmup
+ by a CacheWarmer
+- Cached content only needs to change if the source code also changes (i.e.
+ only on deployment on non-development machines); it should be regarded as
+ read-only after deployment
+
+By default the system cache uses the special ``cache.adapter.system`` adapter
+which writes to the file system and chains the APCu adapter if APCu is
+available. In most cases the default adapter should be the right choice for
+your application.
+
+The application cache ``cache.app`` can be used as a multi-purpose data cache
+in your application and bundle code. In general, data in this pool does not
+need to be flushed on deployment. It defaults to ``cache.adapter.filesystem``
+but it is recommended to configure another adapter like Redis if available, so
+that data both "survives" deployments and is available on multiple instances in
+a multi-server setup.
+Custom pools (see section below) will default to ``cache.app`` as adapter if
+not specified explicitly.
+When using autowiring in your service definitions, ``cache.app`` will by
+default be injected if a service argument declares ``CacheItemPoolInterface``,
+``AdapterInterface``, or ``CacheInterface`` as its type.
+
+You can configure which adapter (template) these predefined pools use by using
+the ``app`` and ``system`` key like:
+
+.. configuration-block::
+
+ .. code-block:: yaml
+
+ # config/packages/cache.yaml
+ framework:
+ cache:
+ app: cache.adapter.filesystem
+ system: cache.adapter.system
+
+ .. code-block:: xml
+
+
+
+
+
+
+
+
+
+
+ .. code-block:: php
+
+ // config/packages/cache.php
+ $container->loadFromExtension('framework', [
+ 'cache' => [
+ 'app' => 'cache.adapter.filesystem',
+ 'system' => 'cache.adapter.system',
+ ],
+ ]);
+
Creating Custom (Namespaced) Pools
----------------------------------