8000 minor #18698 [Cache] Fix doc for Doctrine DBAL adapter (nicolas-grekas) · symfony/symfony-docs@e5376be · GitHub
[go: up one dir, main page]
Skip to content

Commit e5376be

Browse files
javiereguiluzjaviereguiluz
committed
minor #18698 [Cache] Fix doc for Doctrine DBAL adapter (nicolas-grekas)
This PR was merged into the 5.4 branch. Discussion ---------- [Cache] Fix doc for Doctrine DBAL adapter Fix #15903 Commits ------- 1e41505 [Cache] Fix doc for Doctrine DBAL adapter
2 parents 86f3ad5 + 1e41505 commit e5376be

File tree

6 files changed

+115
-108
lines changed

6 files changed

+115
-108
lines changed

‎cache.rst

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -106,10 +106,11 @@ The Cache component comes with a series of adapters pre-configured:
106106

107107
* :doc:`cache.adapter.apcu </components/cache/adapters/apcu_adapter>`
108108
* :doc:`cache.adapter.array </components/cache/adapters/array_cache_adapter>`
109-
* :doc:`cache.adapter.doctrine </components/cache/adapters/doctrine_adapter>`
109+
* :doc:`cache.adapter.doctrine </components/cache/adapters/doctrine_adapter>` (deprecated)
110+
* :doc:`cache.adapter.doctrine_dbal </components/cache/adapters/doctrine_dbal_adapter>`
110111
* :doc:`cache.adapter.filesystem </components/cache/adapters/filesystem_adapter>`
111112
* :doc:`cache.adapter.memcached </components/cache/adapters/memcached_adapter>`
112-
* :doc:`cache.adapter.pdo </components/cache/adapters/pdo_doctrine_dbal_adapter>`
113+
* :doc:`cache.adapter.pdo </components/cache/adapters/pdo_adapter>`
113114
* :doc:`cache.adapter.psr6 </components/cache/adapters/proxy_adapter>`
114115
* :doc:`cache.adapter.redis </components/cache/adapters/redis_adapter>`
115116
* :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]``.
130131
cache:
131132
directory: '%kernel.cache_dir%/pools' # Only used with cache.adapter.filesystem
132133
133-
# service: cache.doctrine
134-
default_doctrine_provider: 'app.doctrine_cache'
134+
# service: cache.doctrine_dbal
135+
default_doctrine_dbal_provider: 'doctrine.dbal.default_connection'
135136
# service: cache.psr6
136137
default_psr6_provider: 'app.my_psr6_service'
137138
# service: cache.redis
138139
default_redis_provider: 'redis://localhost'
139140
# service: cache.memcached
140141
default_memcached_provider: 'memcached://localhost'
141142
# service: cache.pdo
142-
default_pdo_provider: 'doctrine.dbal.default_connection'
143+
default_pdo_provider: 'pgsql:host=localhost'
143144
144145
.. code-block:: xml
145146
@@ -155,19 +156,19 @@ will create pools with service IDs that follow the pattern ``cache.[type]``.
155156
>
156157
<framework:config>
157158
<!--
158-
default_doctrine_provider: Service: cache.doctrine
159+
default_doctrine_dbal_provider: Service: cache.doctrine_dbal
159160
default_psr6_provider: Service: cache.psr6
160161
default_redis_provider: Service: cache.redis
161162
default_memcached_provider: Service: cache.memcached
162163
default_pdo_provider: Service: cache.pdo
163164
-->
164165
<!-- "directory" attribute is only used with cache.adapter.filesystem -->
165166
<framework:cache directory="%kernel.cache_dir%/pools"
166-
default_doctrine_provider="app.doctrine_cache"
167+
default_doctrine_dbal_provider="doctrine.dbal.default_connection"
167168
default_psr6_provider="app.my_psr6_service"
168169
default_redis_provider="redis://localhost"
169170
default_memcached_provider="memcached://localhost"
170-
default_pdo_provider="doctrine.dbal.default_connection"
171+
default_pdo_provider="pgsql:host=localhost"
171172
/>
172173
</framework:config>
173174
</container>
@@ -181,16 +182,16 @@ will create pools with service IDs that follow the pattern ``cache.[type]``.
181182
$framework->cache()
182183
// Only used with cache.adapter.filesystem
183184
->directory('%kernel.cache_dir%/pools')
184-
// Service: cache.doctrine
185-
->defaultDoctrineProvider('app.doctrine_cache')
185+
// Service: cache.doctrine_dbal
186+
->defaultDoctrineDbalProvider('doctrine.dbal.default_connection')
186187
// Service: cache.psr6
187188
->defaultPsr6Provider('app.my_psr6_service')
188189
// Service: cache.redis
189190
->defaultRedisProvider('redis://localhost')
190191
// Service: cache.memcached
191192
->defaultMemcachedProvider('memcached://localhost')
192193
// Service: cache.pdo
193-
->defaultPdoProvider('doctrine.dbal.default_connection')
194+
->defaultPdoProvider('pgsql:host=localhost')
194195
;
195196
};
196197

‎components/cache/adapters/doctrine_dbal_adapter.rst

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
.. _doctrine-dbal-adapter:
2+
3+
Doctrine DBAL Cache Adapter
4+
===========================
F438 5+
6+
The Doctrine DBAL adapters store the cache items in a table of an SQL database.
7+
8+
.. note::
9+
10+
This adapter implements :class:`Symfony\\Component\\Cache\\PruneableInterface`,
11+
allowing for manual :ref:`pruning of expired cache entries <component-cache-cache-pool-prune>`
12+
by calling the ``prune()`` method.
13+
14+
The :class:`Symfony\\Component\\Cache\\Adapter\\DoctrineDbalAdapter` requires a
15+
`Doctrine DBAL Connection`_, or `Doctrine DBAL URL`_ as its first parameter.
16+
You can pass a namespace, default cache lifetime, and options array as the other
17+
optional arguments::
18+
19+
use Symfony\Component\Cache\Adapter\DoctrineDbalAdapter;
20+
21+
$cache = new DoctrineDbalAdapter(
22+
23+
// a Doctrine DBAL connection or DBAL URL
24+
$databaseConnectionOrURL,
25+
26+
// the string prefixed to the keys of the items stored in this cache
27+
$namespace = '',
28+
29+
// the default lifetime (in seconds) for cache items that do not define their
30+
// own lifetime, with a value 0 causing items to be stored indefinitely (i.e.
31+
// until the database table is truncated or its rows are otherwise deleted)
32+
$defaultLifetime = 0,
33+
34+
// an array of options for configuring the database table and connection
35+
$options = []
36+
);
37+
38+
.. note::
39+
40+
DBAL Connection are lazy-loaded by default; some additional options may be
41+
necessary to detect the database engine and version without opening the
42+
connection.
43+
44+
.. _`Doctrine DBAL Connection`: https://github.com/doctrine/dbal/blob/master/src/Connection.php
45+
.. _`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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ and cache root path as constructor parameters::
4141
choices. If throughput is paramount, the in-memory adapters
4242
(:ref:`Apcu <apcu-adapter>`, :ref:`Memcached <memcached-adapter>`, and
4343
:ref:`Redis <redis-adapter>`) or the database adapters
44-
(:ref:`PDO <pdo-doctrine-adapter>`) are recommended.
44+
(:ref:`Doctrine DBAL <doctrine-dbal-adapter>`, :ref:`PDO <pdo-adapter>`) are recommended.
4545

4646
.. note::
4747

‎components/cache/adapters/pdo_adapter.rst

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
.. _pdo-adapter:
2+
3+
PDO Cache Adapter
4+
=================
5+
6+
The PDO adapters store the cache items in a table of an SQL database.
7+
8+
.. note::
9+
10+
This adapter implements :class:`Symfony\\Component\\Cache\\PruneableInterface`,
11+
allowing for manual :ref:`pruning of expired cache entries <component-cache-cache-pool-prune>`
12+
by calling the ``prune()`` method.
13+
14+
The :class:`Symfony\\Component\\Cache\\Adapter\\PdoAdapter` requires a :phpclass:`PDO`,
15+
or `DSN`_ as its first parameter. You can pass a namespace,
16+
default cache lifetime, and options array as the other optional arguments::
17+
18+
use Symfony\Component\Cache\Adapter\PdoAdapter;
19+
20+
$cache = new PdoAdapter(
21+
22+
// a PDO connection or DSN for lazy connecting through PDO
23+
$databaseConnectionOrDSN,
24+
25+
// the string prefixed to the keys of the items stored in this cache
26+
$namespace = '',
27+
28+
// the default lifetime (in seconds) for cache items that do not define their
29+
// own lifetime, with a value 0 causing items to be stored indefinitely (i.e.
30+
// until the database table is truncated or its rows are otherwise deleted)
31+
$defaultLifetime = 0,
32+
33+
// an array of options for configuring the database table and connection
34+
$options = []
35+
);
36+
37+
The table where values are stored is created automatically on the first call to
38+
the :method:`Symfony\\Component\\Cache\\Adapter\\PdoAdapter::save` method.
39+
You can also create this table explicitly by calling the
40+
:method:`Symfony\\Component\\Cache\\Adapter\\PdoAdapter::createTable` method in
41+
your code.
42+
43+
.. deprecated:: 5.4
44+
45+
Using :class:`Symfony\\Component\\Cache\\Adapter\\PdoAdapter` with a
46+
:class:`Doctrine\\DBAL\\Connection` or a DBAL URL is deprecated since Symfony 5.4
47+
and will be removed in Symfony 6.0.
48+
Use :class:`Symfony\\Component\\Cache\\Adapter\\DoctrineDbalAdapter` instead.
49+
50+
.. tip::
51+
52+
When passed a `Data Source Name (DSN)`_ string (instead of a database connection
53+
class instance), the connection will be lazy-loaded when needed.
54+
55+
.. _`DSN`: https://php.net/manual/pdo.drivers.php

‎components/cache/adapters/pdo_doctrine_dbal_adapter.rst

Lines changed: 0 additions & 95 deletions
This file was deleted.

‎components/cache/cache_pools.rst

Lines changed: 2 additions & 1 deletion
Original file li 8321 ne numberDiff line numberDiff line change
@@ -203,8 +203,9 @@ This shortcoming has been solved through the introduction of
203203
:class:`Symfony\\Component\\Cache\\PruneableInterface`, which defines the abstract method
204204
:method:`Symfony\\Component\\Cache\\PruneableInterface::prune`. The
205205
:ref:`ChainAdapter <component-cache-chain-adapter>`,
206+
:ref:`DoctrineDbalAdapter <doctrine-dbal-adapter>`, and
206207
:ref:`FilesystemAdapter <component-cache-filesystem-adapter>`,
207-
:ref:`PdoAdapter <pdo-doctrine-adapter>`, and
208+
:ref:`PdoAdapter <pdo-adapter>`, and
208209
:ref:`PhpFilesAdapter <component-cache-files-adapter>` all implement this new interface,
209210
allowing manual removal of stale cache items::
210211

0 commit comments

Comments
 (0)
0