[Cache] Fix doc for Doctrine DBAL adapter

Author: nicolas-grekas

cache.rst

@@ -106,10 +106,11 @@ The Cache component comes with a series of adapters pre-configured:
 
 * :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.doctrine </components/cache/adapters/doctrine_adapter>` (deprecated)
+* :doc:`cache.adapter.doctrine_dbal </components/cache/adapters/doctrine_dbal_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.pdo </components/cache/adapters/pdo_adapter>`
 * :doc:`cache.adapter.psr6 </components/cache/adapters/proxy_adapter>`
 * :doc:`cache.adapter.redis </components/cache/adapters/redis_adapter>`
 * :ref:`cache.adapter.redis_tag_aware <redis-tag-aware-adapter>` (Redis adapter optimized to work with tags)
@@ -130,16 +131,16 @@ will create pools with service IDs that follow the pattern ``cache.[type]``.
             cache:
                 directory: '%kernel.cache_dir%/pools' # Only used with cache.adapter.filesystem
 
-                # service: cache.doctrine
-                default_doctrine_provider: 'app.doctrine_cache'
+                # service: cache.doctrine_dbal
+                default_doctrine_dbal_provider: 'doctrine.dbal.default_connection'
                 # 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'
+                default_pdo_provider: 'pgsql:host=localhost'
 
     .. code-block:: xml
 
@@ -155,19 +156,19 @@ will create pools with service IDs that follow the pattern ``cache.[type]``.
         >
             <framework:config>
                 <!--
-                default_doctrine_provider: Service: cache.doctrine
+                default_doctrine_dbal_provider: Service: cache.doctrine_dbal
                 default_psr6_provider: Service: cache.psr6
                 default_redis_provider: Service: cache.redis
                 default_memcached_provider: Service: cache.memcached
                 default_pdo_provider: Service: cache.pdo
                 -->
                 <!-- "directory" attribute is only used with cache.adapter.filesystem -->
                 <framework:cache directory="%kernel.cache_dir%/pools"
-                    default_doctrine_provider="app.doctrine_cache"
+                    default_doctrine_dbal_provider="doctrine.dbal.default_connection"
                     default_psr6_provider="app.my_psr6_service"
                     default_redis_provider="redis://localhost"
                     default_memcached_provider="memcached://localhost"
-                    default_pdo_provider="doctrine.dbal.default_connection"
+                    default_pdo_provider="pgsql:host=localhost"
                 />
             </framework:config>
         </container>
@@ -181,16 +182,16 @@ will create pools with service IDs that follow the pattern ``cache.[type]``.
             $framework->cache()
                 // Only used with cache.adapter.filesystem
                 ->directory('%kernel.cache_dir%/pools')
-                // Service: cache.doctrine
-                ->defaultDoctrineProvider('app.doctrine_cache')
+                // Service: cache.doctrine_dbal
+                ->defaultDoctrineDbalProvider('doctrine.dbal.default_connection')
                 // Service: cache.psr6
                 ->defaultPsr6Provider('app.my_psr6_service')
                 // Service: cache.redis
                 ->defaultRedisProvider('redis://localhost')
                 // Service: cache.memcached
                 ->defaultMemcachedProvider('memcached://localhost')
                 // Service: cache.pdo
-                ->defaultPdoProvider('doctrine.dbal.default_connection')
+                ->defaultPdoProvider('pgsql:host=localhost')
             ;
         };
 

components/cache/adapters/doctrine_dbal_adapter.rst

@@ -0,0 +1,45 @@
+.. _doctrine-dbal-adapter:
+
+Doctrine DBAL Cache Adapter
+===========================
+
+The Doctrine DBAL adapters store the cache items in a table of an SQL database.
+
+.. note::
+
+    This adapter implements :class:`Symfony\\Component\\Cache\\PruneableInterface`,
+    allowing for manual :ref:`pruning of expired cache entries <component-cache-cache-pool-prune>`
+    by calling the ``prune()`` method.
+
+The :class:`Symfony\\Component\\Cache\\Adapter\\DoctrineDbalAdapter` requires a
+`Doctrine DBAL Connection`_, or `Doctrine DBAL URL`_ as its first parameter.
+You can pass a namespace, default cache lifetime, and options array as the other
+optional arguments::
+
+    use Symfony\Component\Cache\Adapter\DoctrineDbalAdapter;
+
+    $cache = new DoctrineDbalAdapter(
+
+        // a Doctrine DBAL connection or DBAL URL
+        $databaseConnectionOrURL,
+
+        // the string prefixed to the keys of the items stored in this cache
+        $namespace = '',
+
+        // the default lifetime (in seconds) for cache items that do not define their
+        // own lifetime, with a value 0 causing items to be stored indefinitely (i.e.
+        // until the database table is truncated or its rows are otherwise deleted)
+        $defaultLifetime = 0,
+
+        // an array of options for configuring the database table and connection
+        $options = []
+    );
+
+.. note::
+
+    DBAL Connection are lazy-loaded by default; some additional options may be
+    necessary to detect the database engine and version without opening the
+    connection.
+
+.. _`Doctrine DBAL Connection`: https://github.com/doctrine/dbal/blob/master/src/Connection.php
+.. _`Doctrine DBAL URL`: https://www.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/configuration.html#connecting-using-a-url

components/cache/adapters/filesystem_adapter.rst

@@ -41,7 +41,7 @@ and cache root path as constructor parameters::
     choices. If throughput is paramount, the in-memory adapters
     (:ref:`Apcu <apcu-adapter>`, :ref:`Memcached <memcached-adapter>`, and
     :ref:`Redis <redis-adapter>`) or the database adapters
-    (:ref:`PDO <pdo-doctrine-adapter>`) are recommended.
+    (:ref:`Doctrine DBAL <doctrine-dbal-adapter>`, :ref:`PDO <pdo-adapter>`) are recommended.
 
 .. note::
 

components/cache/adapters/pdo_adapter.rst

@@ -0,0 +1,55 @@
+.. _pdo-adapter:
+
+PDO Cache Adapter
+=================
+
+The PDO adapters store the cache items in a table of an SQL database.
+
+.. note::
+
+    This adapter implements :class:`Symfony\\Component\\Cache\\PruneableInterface`,
+    allowing for manual :ref:`pruning of expired cache entries <component-cache-cache-pool-prune>`
+    by calling the ``prune()`` method.
+
+The :class:`Symfony\\Component\\Cache\\Adapter\\PdoAdapter` requires a :phpclass:`PDO`,
+or `DSN`_ as its first parameter. You can pass a namespace,
+default cache lifetime, and options array as the other optional arguments::
+
+    use Symfony\Component\Cache\Adapter\PdoAdapter;
+
+    $cache = new PdoAdapter(
+
+        // a PDO connection or DSN for lazy connecting through PDO
+        $databaseConnectionOrDSN,
+
+        // the string prefixed to the keys of the items stored in this cache
+        $namespace = '',
+
+        // the default lifetime (in seconds) for cache items that do not define their
+        // own lifetime, with a value 0 causing items to be stored indefinitely (i.e.
+        // until the database table is truncated or its rows are otherwise deleted)
+        $defaultLifetime = 0,
+
+        // an array of options for configuring the database table and connection
+        $options = []
+    );
+
+The table where values are stored is created automatically on the first call to
+the :method:`Symfony\\Component\\Cache\\Adapter\\PdoAdapter::save` method.
+You can also create this table explicitly by calling the
+:method:`Symfony\\Component\\Cache\\Adapter\\PdoAdapter::createTable` method in
+your code.
+
+.. deprecated:: 5.4
+
+    Using :class:`Symfony\\Component\\Cache\\Adapter\\PdoAdapter` with a
+    :class:`Doctrine\\DBAL\\Connection` or a DBAL URL is deprecated since Symfony 5.4
+    and will be removed in Symfony 6.0.
+    Use :class:`Symfony\\Component\\Cache\\Adapter\\DoctrineDbalAdapter` instead.
+
+.. tip::
+
+    When passed a `Data Source Name (DSN)`_ string (instead of a database connection
+    class instance), the connection will be lazy-loaded when needed.
+
+.. _`DSN`: https://php.net/manual/pdo.drivers.php

components/cache/adapters/pdo_doctrine_dbal_adapter.rst

@@ -203,8 +203,9 @@ This shortcoming has been solved through the introduction of
 :class:`Symfony\\Component\\Cache\\PruneableInterface`, which defines the abstract method
 :method:`Symfony\\Component\\Cache\\PruneableInterface::prune`. The
 :ref:`ChainAdapter <component-cache-chain-adapter>`,
+:ref:`DoctrineDbalAdapter <doctrine-dbal-adapter>`, and
 :ref:`FilesystemAdapter <component-cache-filesystem-adapter>`,
-:ref:`PdoAdapter <pdo-doctrine-adapter>`, and
+:ref:`PdoAdapter <pdo-adapter>`, and
 :ref:`PhpFilesAdapter <component-cache-files-adapter>` all implement this new interface,
 allowing manual removal of stale cache items::