From 7e73e8278be9e00f8989c80799898b8e309fc056 Mon Sep 17 00:00:00 2001
From: Stefan Kruppa <stefan.kruppa@reservix.de>
Date: Fri, 17 Sep 2021 16:52:33 +0200
Subject: [PATCH] Improve explanation of cache.app and cache.system

---
 cache.rst | 119 ++++++++++++++++++++++++++++++++++--------------------
 1 file changed, 75 insertions(+), 44 deletions(-)

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
-
-        <!-- config/packages/cache.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xmlns:framework="http://symfony.com/schema/dic/symfony"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                https://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony
-                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
-
-            <framework:config>
-                <framework:cache app="cache.adapter.filesystem"
-                    system="cache.adapter.system"
-                />
-            </framework:config>
-        </container>
-
-    .. 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 </components/cache/adapters/apcu_adapter>`
@@ -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
+
+        <!-- config/packages/cache.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+            <framework:config>
+                <framework:cache app="cache.adapter.filesystem"
+                    system="cache.adapter.system"
+                />
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/cache.php
+        $container->loadFromExtension('framework', [
+            'cache' => [
+                'app' => 'cache.adapter.filesystem',
+                'system' => 'cache.adapter.system',
+            ],
+        ]);
+
 Creating Custom (Namespaced) Pools
 ----------------------------------
 

<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'>
<html xmlns='http://www.w3.org/1999/xhtml'>
<head>
<title>pFad - Phonifier reborn</title>
<meta http-equiv='Content-Type' content='text/html; charset=utf-8' />
</head>
<body>
<h1>Pfad - The Proxy pFad of &#169; 2024 Garber Painting. All rights reserved.</h1>


<!-- Disclaimer -->
<p>Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.</p>
<br>
<p>Alternative Proxies:</p><p><a href="http://rainy.clevelandohioweatherforecast.com/php-proxy/index.php?q=https://patch-diff.githubusercontent.com/raw/symfony/symfony-docs/pull/15827.patch" target="_blank">Alternative Proxy</a></p><p><a href="http://rainy.clevelandohioweatherforecast.com/pFad/index.php?u=https://patch-diff.githubusercontent.com/raw/symfony/symfony-docs/pull/15827.patch" target="_blank">pFad Proxy</a></p><p><a href="http://rainy.clevelandohioweatherforecast.com/pFad/v3index.php?u=https://patch-diff.githubusercontent.com/raw/symfony/symfony-docs/pull/15827.patch" target="_blank">pFad v3 Proxy</a></p><p><a href="http://rainy.clevelandohioweatherforecast.com/pFad/v4index.php?u=https://patch-diff.githubusercontent.com/raw/symfony/symfony-docs/pull/15827.patch" target="_blank">pFad v4 Proxy</a></p></body>
</html>