From 03d3e359ba983755ac4b20de15c06aecbb323778 Mon Sep 17 00:00:00 2001 From: Geoffrey Brier Date: Mon, 12 Dec 2016 00:18:33 +0100 Subject: [PATCH 1/3] [Cache] Document "framework.cache" node --- reference/configuration/framework.rst | 146 ++++++++++++++++++++++++++ 1 file changed, 146 insertions(+) diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index 7f5f6249681..f4820763c40 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -102,6 +102,20 @@ Configuration * :ref:`cache ` * :ref:`enable_annotations ` * :ref:`name_converter ` +* :ref:`cache ` + * :ref:`app ` + * `system`_ + * `directory`_ + * `default_doctrine_provider`_ + * `default_psr6_provider`_ + * `default_redis_provider`_ + * `pools`_ + * :ref:`name ` + * `adapter`_ + * `public`_ + * `default_lifetime`_ + * `provider`_ + * `clearer`_ secret ~~~~~~ @@ -674,6 +688,8 @@ installation. You can see an example of the usage of this in :doc:`/doctrine/pdo_session_storage`. +.. _name: + name .... @@ -1446,6 +1462,119 @@ value. For more information, see :ref:`component-serializer-converting-property-names-when-serializing-and-deserializing`. +.. _reference-cache: + +cache +~~~~~ + +.. _reference-cache-app: + +app +... + +**type**: ``string`` **default**: ``cache.adapter.filesystem`` + +The cache adapter behind the ``cache.app`` service. + +.. note:: + + The framework bundle ships with multiple adapters : apcu, doctrine, system, filesystem, psr6, redis. + +system +...... + +**type**: ``string`` **default**: ``cache.adapter.system`` + +The cache adapter behind the ``cache.system`` service. + +directory +......... + +**type**: ``string`` **default**: ``%kernel.cache_dir%/pools`` + +The path to the cache directory used by services inheriting from the ``cache.adapter.filesystem`` adapter +(including ``cache.app``). + +default_doctrine_provider +......................... + +**type**: ``string`` + +The service name to use as your default doctrine provider. + +default_psr6_provider +..................... + +**type**: ``string`` **default**: ``%kernel.cache_dir%/pools`` + +The service name to use as your default psr6 provider. + +default_redis_provider +...................... + +**type**: ``string`` **default**: ``redis://localhost`` + +The dsn to use by the redis provider. + +pools +..... + +**type**: ``array`` + +A list of cache pools to be created by the framework extension. + +.. _reference-cache-pools-name: + +name +"""" + +**type**: ``prototype`` + +Name of the pool you want to create. + +.. note:: + + Your pool name must differ from ``cache.app`` or ``cache.system``. + +adapter +####### + +**type**: ``string`` **default**: ``cache.app`` + +A cache adapter. + +public +###### + +**type**: ``boolean`` **default**: ``false`` + +Whether your service should be public or not. + +default_lifetime +################ + +**type**: ``integer`` + +Default lifetime of your cache items. + +provider +######## + +**type**: ``string`` + +The service name to use as provider when the specified adapter needs one. + +clearer +####### + +**type**: ``string`` + +The cache clearer used to clear your PSR-6 cache. + +.. seealso:: + + For more information, see :class:`Symfony\\Component\\HttpKernel\\CacheClearer\\Psr6CacheClearer` + Full Default Configuration -------------------------- @@ -1580,6 +1709,23 @@ Full Default Configuration file_cache_dir: '%kernel.cache_dir%/annotations' debug: '%kernel.debug%' + # cache configuration + cache: + app: cache.app + system: cache.system + directory: '%kernel.cache_dir%/pools' + default_doctrine_provider: ~ + default_psr6_provider: ~ + default_redis_provider: 'redis://localhost' + pools: + # Prototype + name: + adapter: cache.app + public: false + default_lifetime: ~ + provider: ~ + clearer: ~ + .. _`HTTP Host header attacks`: http://www.skeletonscribe.net/2013/05/practical-http-host-header-attacks.html .. _`Security Advisory Blog post`: https://symfony.com/blog/security-releases-symfony-2-0-24-2-1-12-2-2-5-and-2-3-3-released#cve-2013-4752-request-gethost-poisoning .. _`Doctrine Cache`: http://docs.doctrine-project.org/projects/doctrine-common/en/latest/reference/caching.html From bf565594c9ebeafaed5fba7f019eda71d9f2e3a3 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 23 Dec 2016 10:23:50 +0100 Subject: [PATCH 2/3] Minor fixes --- reference/configuration/framework.rst | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index f4820763c40..6fbd4688062 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -1474,47 +1474,48 @@ app **type**: ``string`` **default**: ``cache.adapter.filesystem`` -The cache adapter behind the ``cache.app`` service. +The cache adapter used by the ``cache.app`` service. .. note:: - The framework bundle ships with multiple adapters : apcu, doctrine, system, filesystem, psr6, redis. + The framework bundle ships with multiple adapters: apcu, doctrine, system, + filesystem, psr6, and redis. system ...... **type**: ``string`` **default**: ``cache.adapter.system`` -The cache adapter behind the ``cache.system`` service. +The cache adapter used by the ``cache.system`` service. directory ......... **type**: ``string`` **default**: ``%kernel.cache_dir%/pools`` -The path to the cache directory used by services inheriting from the ``cache.adapter.filesystem`` adapter -(including ``cache.app``). +The path to the cache directory used by services inheriting from the +``cache.adapter.filesystem`` adapter (including ``cache.app``). default_doctrine_provider ......................... **type**: ``string`` -The service name to use as your default doctrine provider. +The service name to use as your default Doctrine provider. default_psr6_provider ..................... **type**: ``string`` **default**: ``%kernel.cache_dir%/pools`` -The service name to use as your default psr6 provider. +The service name to use as your default PSR-6 provider. default_redis_provider ...................... **type**: ``string`` **default**: ``redis://localhost`` -The dsn to use by the redis provider. +The dsn to use by the Redis provider. pools ..... @@ -1555,7 +1556,7 @@ default_lifetime **type**: ``integer`` -Default lifetime of your cache items. +Default lifetime of your cache items in seconds. provider ######## From 9cb31b2f3838341c6a892a48adc5ef2623eb6707 Mon Sep 17 00:00:00 2001 From: Geoffrey Brier Date: Wed, 28 Dec 2016 18:12:55 +0100 Subject: [PATCH 3/3] Improve doc --- components/cache/cache_pools.rst | 2 ++ reference/configuration/framework.rst | 18 ++++++++++++++++-- 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/components/cache/cache_pools.rst b/components/cache/cache_pools.rst index ed1311ce416..ce2c12971b7 100644 --- a/components/cache/cache_pools.rst +++ b/components/cache/cache_pools.rst @@ -4,6 +4,8 @@ single: Doctrine Cache single: Redis Cache +.. _component-cache-cache-pools: + Cache Pools =========== diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index 6fbd4688062..b70eeb4216e 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -1476,6 +1476,12 @@ app The cache adapter used by the ``cache.app`` service. +.. tip:: + + It might be tough to understand at the beginning, so to avoid confusion remember that all pools perform the + same actions but on different medium given the adapter they are based on. Internally, a pool wraps the definition + of an adapter. + .. note:: The framework bundle ships with multiple adapters: apcu, doctrine, system, @@ -1524,6 +1530,10 @@ pools A list of cache pools to be created by the framework extension. +.. seealso:: + + For more information about how pools works, see :ref:`cache pools `. + .. _reference-cache-pools-name: name @@ -1542,7 +1552,11 @@ adapter **type**: ``string`` **default**: ``cache.app`` -A cache adapter. +The name of the adapter to use. You could also use your own implementation. + +.. note:: + + Your service MUST implement the :class:`Psr\\Cache\\CacheItemPoolInterface` interface. public ###### @@ -1574,7 +1588,7 @@ The cache clearer used to clear your PSR-6 cache. .. seealso:: - For more information, see :class:`Symfony\\Component\\HttpKernel\\CacheClearer\\Psr6CacheClearer` + For more information, see :class:`Symfony\\Component\\HttpKernel\\CacheClearer\\Psr6CacheClearer`. Full Default Configuration --------------------------