Skip to content

Improve explanation of cache.app and cache.system #15827

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: 4.4
Choose a base branch
from
Open

Improve explanation of cache.app and cache.system #15827

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
119 changes: 75 additions & 44 deletions cache.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>`
Expand Down Expand Up @@ -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
----------------------------------

Expand Down