Starting on documentation for cache

cache.rst

@@ -0,0 +1,195 @@
+Cache
+=====
+
+Using cache is a great way of making you application run quicker. The Symfony cache
+component is shipped with many adapters to different storages. Every adapter is
+developed for high performance.
+
+Basic uses of the cache looks like this::
+
+    use Symfony\Contracts\Cache\ItemInterface;
+
+    // The callable will only be executed on a cache miss.
+    $value = $pool->get('my_cache_key', function (ItemInterface $item) {
+        $item->expiresAfter(3600);
+
+        // Do some HTTP request or heavy computations
+        $computedValue = 'foobar';
+
+        return $computedValue;
+    });
+
+    echo $value; // 'foobar'
+
+    $pool->delete('some_key');
+
+
+Symfony also supports PSR-6 and PSR-16 cache interfaces. You can read more about
+these at the :doc:`component documentation </components/cache>`.
+
+
+Configuring Cache with FrameworkBundle
+--------------------------------------
+
+When configuring the the cache component there are a few concepts you should know
+of:
+
+**Pool**
+    This is a service that you will interact with. Each pool will always have
+    its own namespace and cache items. There is never a conflict between pools.
+**Adapter**
+    An adapter is a *template* that you use to create Pools.
+**Provider**
+    A provider is the DSN connection to the actual storage.
+
+There are two pools that are always enabled by default. They are ``cache.app`` and
+``cache.system``. The system cache is use 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:
+
+.. code-block:: yaml
+
+    # config/packages/cache.yaml
+    framework:
+        cache:
+            app: cache.adapter.filesystem
+            system: cache.adapter.system
+
+The Cache component comes with a series of adapters already created:
+
+* :doc:`cache.adapter.apcu </components/cache/adapters/apcu-adapter>`
+* :doc:`cache.adapter.array </components/cache/adapters/array-cache-adapter>`
+* :doc:`cache.adapter.doctrine </components/cache/adapters/doctrine-adapter>`
+* :doc:`cache.adapter.filesystem </components/cache/adapters/filesystem-adapter>`
+* :doc:`cache.adapter.memcached </components/cache/adapters/memcached-adapter>`
+* :doc:`cache.adapter.pdo </components/cache/adapters/pdo-doctrine-dbal-adapter>`
+* :doc:`cache.adapter.redis </components/cache/adapters/redis-adapter>`
+* :doc:`PHPFileAdapter </components/cache/adapters/php-files-adapter>`
+* :doc:`PHPArrayAdapter </components/cache/adapters/php-array-adapter>`
+
+* :doc:`ChainAdapter </components/cache/adapters/chain-adapter>`
+* :doc:`ProxyAdapter </components/cache/adapters/proxy-adapter>`
+* cache.adapter.psr6
+
+* cache.adapter.system
+* NullAdapter
+
+Some of these adapters could be configured via shortcuts. Using these shortcuts
+will create pool with service id of ``cache.[type]``
+
+.. code-block:: yaml
+
+    # config/packages/cache.yaml
+    framework:
+        cache:
+            directory: '%kernel.cache_dir%/pools' # Only used with cache.adapter.filesystem
+
+            # service: cache.doctrine
+            default_doctrine_provider: 'app.doctrine_cache'
+            # service: cache.psr6
+            default_psr6_provider: 'app.my_psr6_service'
+            # service: cache.redis
+            default_redis_provider: 'redis://localhost'
+            # service: cache.memcached
+            default_memcached_provider: 'memcached://localhost'
+            # service: cache.pdo
+            default_pdo_provider: 'doctrine.dbal.default_connection'
+
+Creating Custom Pools
+---------------------
+
+You can also create more customized pools. All you need is an adapter:
+
+.. code-block:: yaml
+
+    # config/packages/cache.yaml
+    framework:
+        cache:
+            default_memcached_provider: 'memcached://localhost'
+            pools:
+                my_cache_pool:
+                    adapter: cache.adapter.array
+                cache.acme:
+                    adapter: cache.adapter.memcached
+                cache.foobar:
+                    adapter: cache.adapter.memcached
+                    provider: 'memcached://user:password@example.com'
+
+The configuration above will create 3 services: ``my_cache_pool``, ``cache.acme``
+and ``cache.foobar``.  The ``my_cache_pool`` pool is using the ArrayAdapter
+and the other two are using the :doc:`MemcachedAdapter </components/cache/adapters/memcached-adapter>`.
+The ``cache.acme`` pool is using the Memcached server on localhost and ``cache.foobar``
+is using the Memcached server at example.com.
+
+For advanced configurations it could sometimes be useful to use a pool as an adapter.
+
+.. code-block:: yaml
+
+    # config/packages/cache.yaml
+    framework:
+        cache:
+            pools:
+                my_cache_pool:
+                    adapter: cache.adapter.memcached
+                    provider: 'memcached://user:password@example.com'
+                cache.short_cache:
+                    adapter: my_cache_pool
+                    default_lifetime: 60
+                cache.long_cache:
+                    adapter: my_cache_pool
+                    default_lifetime: 604800
+
+Creating a Cache Chain
+----------------------
+
+Different cache adapters has different strengths and weaknesses. Some might be really
+quick but small and some may be able to contain a lot of data but are quite slow.
+To get the best of both worlds you may use a chain of adapters. The idea is to
+first look at the quick adapter and then move on to slower adapters. In the worst
+case the value needs to be recalculated.
+
+.. code-block:: yaml
+
+    # config/services.yaml
+    services:
+        app.my_cache_chain_adapter:
+            class: Symfony\Component\Cache\Adapter\ChainAdapter
+            arguments:
+                - ['cache.adapter.array', 'cache.my_redis', 'cache.adapter.file']
+                - 31536000 # One year
+
+    # config/packages/cache.yaml
+    framework:
+        cache:
+            pools:
+                my_cache_pool:
+                    adapter: app.my_cache_chain_adapter
+                cache.my_redis:
+                    adapter: cache.adapter.redis
+                    provider: 'redis://user:password@example.com'
+
+.. note::
+
+    In this configuration there is a ``cache.my_redis`` pool that is used as an
+    adapter in the ``app.my_cache_chain_adapter``
+
+
+Clearing the Cache
+------------------
+
+To clear the cache you can use the ``bin/console cache:pool:clear [pool]`` command.
+That will remove all the entries from your storage and you wil have to recalcuate
+all values. You can also group your pools into "cache clearers". There 3 cache clearer
+by default:
+
+* cache.global_clearer
+* cache.system_clearer
+* cache.app_clearer
+
+The global clearer clears all the cache in every pool. The system cache clearer
+is used in the ``bin/console cache:clear`` command. The app clearer is the default
+clearer.
+
+.. code-block:: terminal
+
+    $ php bin/console cache:pool:clear cache.app_clearer

index.rst

@@ -32,6 +32,7 @@ Topics
     :maxdepth: 1
 
     bundles
+    cache
     console
     doctrine
     deployment