diff --git a/cache.rst b/cache.rst index 118ef13a326..a22912c36b1 100644 --- a/cache.rst +++ b/cache.rst @@ -106,10 +106,11 @@ The Cache component comes with a series of adapters pre-configured: * :doc:`cache.adapter.apcu ` * :doc:`cache.adapter.array ` -* :doc:`cache.adapter.doctrine ` +* :doc:`cache.adapter.doctrine ` (deprecated) +* :doc:`cache.adapter.doctrine_dbal ` * :doc:`cache.adapter.filesystem ` * :doc:`cache.adapter.memcached ` -* :doc:`cache.adapter.pdo ` +* :doc:`cache.adapter.pdo ` * :doc:`cache.adapter.psr6 ` * :doc:`cache.adapter.redis ` * :ref:`cache.adapter.redis_tag_aware ` (Redis adapter optimized to work with tags) @@ -130,8 +131,8 @@ 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 @@ -139,7 +140,7 @@ will create pools with service IDs that follow the pattern ``cache.[type]``. # 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,7 +156,7 @@ will create pools with service IDs that follow the pattern ``cache.[type]``. > @@ -181,8 +182,8 @@ 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 @@ -190,7 +191,7 @@ will create pools with service IDs that follow the pattern ``cache.[type]``. // Service: cache.memcached ->defaultMemcachedProvider('memcached://localhost') // Service: cache.pdo - ->defaultPdoProvider('doctrine.dbal.default_connection') + ->defaultPdoProvider('pgsql:host=localhost') ; }; diff --git a/components/cache/adapters/doctrine_dbal_adapter.rst b/components/cache/adapters/doctrine_dbal_adapter.rst new file mode 100644 index 00000000000..3b955832147 --- /dev/null +++ b/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 ` + 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 diff --git a/components/cache/adapters/filesystem_adapter.rst b/components/cache/adapters/filesystem_adapter.rst index 331dbb2dff6..237ac3bc60e 100644 --- a/components/cache/adapters/filesystem_adapter.rst +++ b/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 `, :ref:`Memcached `, and :ref:`Redis `) or the database adapters - (:ref:`PDO `) are recommended. + (:ref:`Doctrine DBAL `, :ref:`PDO `) are recommended. .. note:: diff --git a/components/cache/adapters/pdo_adapter.rst b/components/cache/adapters/pdo_adapter.rst new file mode 100644 index 00000000000..62d4dcc90aa --- /dev/null +++ b/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 ` + 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 diff --git a/components/cache/adapters/pdo_doctrine_dbal_adapter.rst b/components/cache/adapters/pdo_doctrine_dbal_adapter.rst deleted file mode 100644 index 3615d5a1bbf..00000000000 --- a/components/cache/adapters/pdo_doctrine_dbal_adapter.rst +++ /dev/null @@ -1,95 +0,0 @@ -.. _pdo-doctrine-adapter: - -PDO & Doctrine DBAL Cache Adapter -================================= - -The PDO and Doctrine DBAL adapters store the cache items in a table of an SQL database. - -.. note:: - - These adapters implement :class:`Symfony\\Component\\Cache\\PruneableInterface`, - allowing for manual :ref:`pruning of expired cache entries ` - by calling the ``prune()`` method. - -Using PHP PDO -------------- - -The :class:`Symfony\\Component\\Cache\\Adapter\\PdoAdapter` requires a :phpclass:`PDO`, -or `Data Source Name (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. DBAL Connection - are lazy-loaded by default; some additional options may be necessary to detect - the database engine and version without opening the connection. - -Using Doctrine DBAL -------------------- - -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 -.. _`Data Source Name (DSN)`: https://en.wikipedia.org/wiki/Data_source_name diff --git a/components/cache/cache_pools.rst b/components/cache/cache_pools.rst index ac7cf945429..bd4488f2b48 100644 --- a/components/cache/cache_pools.rst +++ b/components/cache/cache_pools.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 `, +:ref:`DoctrineDbalAdapter `, and :ref:`FilesystemAdapter `, -:ref:`PdoAdapter `, and +:ref:`PdoAdapter `, and :ref:`PhpFilesAdapter ` all implement this new interface, allowing manual removal of stale cache items::