Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: consistency for FQCN, spacing, etc #9232

Merged
merged 5 commits into from
Dec 13, 2021
+45 −55
Merged

Docs: consistency for FQCN, spacing, etc #9232

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
6bc21f8
Docs: consistent spacing, consistent array-style, consistent FQCN, av…
andrew-demb Dec 9, 2021
528c454
Docs: use special note block instead of markdown-based style
andrew-demb Dec 9, 2021
fee3d8d
Docs: Quote FQCN in table with backticks to be compatible with all re…
andrew-demb Dec 11, 2021
4c58a6d
Drop all mentions API doc - it is not available anymore
andrew-demb Dec 13, 2021
bdfdeb8
Add missed FQCN for code snippets
andrew-demb Dec 13, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 45 additions & 55 deletions docs/en/reference/second-level-cache.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,31 +31,31 @@ Each cache region resides in a specific cache namespace and has its own lifetime
Notice that when caching collection and queries only identifiers are stored.
The entity values will be stored in its own region

Something like below for an entity region :
Something like below for an entity region:

.. code-block:: php

<?php
[
'region_name:entity_1_hash' => ['id'=> 1, 'name' => 'FooBar', 'associationName'=>null],
'region_name:entity_2_hash' => ['id'=> 2, 'name' => 'Foo', 'associationName'=>['id'=>11]],
'region_name:entity_3_hash' => ['id'=> 3, 'name' => 'Bar', 'associationName'=>['id'=>22]]
'region_name:entity_1_hash' => ['id' => 1, 'name' => 'FooBar', 'associationName' => null],
'region_name:entity_2_hash' => ['id' => 2, 'name' => 'Foo', 'associationName' => ['id' => 11]],
'region_name:entity_3_hash' => ['id' => 3, 'name' => 'Bar', 'associationName' => ['id' => 22]]
];


If the entity holds a collection that also needs to be cached.
An collection region could look something like :
An collection region could look something like:

.. code-block:: php

<?php
[
'region_name:entity_1_coll_assoc_name_hash' => ['ownerId'=> 1, 'list' => [1, 2, 3]],
'region_name:entity_2_coll_assoc_name_hash' => ['ownerId'=> 2, 'list' => [2, 3]],
'region_name:entity_3_coll_assoc_name_hash' => ['ownerId'=> 3, 'list' => [2, 4]]
'region_name:entity_1_coll_assoc_name_hash' => ['ownerId' => 1, 'list' => [1, 2, 3]],
'region_name:entity_2_coll_assoc_name_hash' => ['ownerId' => 2, 'list' => [2, 3]],
'region_name:entity_3_coll_assoc_name_hash' => ['ownerId' => 3, 'list' => [2, 4]]
];

A query region might be something like :
A query region might be something like:

.. code-block:: php

Expand Down Expand Up @@ -93,8 +93,6 @@ Cache region
``Doctrine\ORM\Cache\Region`` defines a contract for accessing a particular
cache region.

`See API Doc <https://www.doctrine-project.org/api/orm/current/Doctrine/ORM/Cache/Region.html>`_.

Concurrent cache region
~~~~~~~~~~~~~~~~~~~~~~~

Expand All @@ -105,17 +103,13 @@ If you want to use an ``READ_WRITE`` cache, you should consider providing your o

``Doctrine\ORM\Cache\ConcurrentRegion`` defines a contract for concurrently managed data region.

`See API Doc <https://www.doctrine-project.org/api/orm/current/Doctrine/ORM/Cache/ConcurrentRegion.html>`_.

Timestamp region
~~~~~~~~~~~~~~~~

``Doctrine\ORM\Cache\TimestampRegion``

Tracks the timestamps of the most recent updates to particular entity.

`See API Doc <https://www.doctrine-project.org/api/orm/current/Doctrine/ORM/Cache/TimestampRegion.html>`_.

.. _reference-second-level-cache-mode:

Caching mode
Expand All @@ -132,7 +126,7 @@ Caching mode

* Read Write Cache doesn’t employ any locks but can do reads, inserts, updates and deletes.
* Good if the application needs to update data rarely.


* ``READ_WRITE``

Expand All @@ -147,21 +141,21 @@ Built-in cached persisters

Cached persisters are responsible to access cache regions.

+-----------------------+-------------------------------------------------------------------------------------------+
| Cache Usage | Persister |
+=======================+===========================================================================================+
| READ_ONLY | Doctrine\\ORM\\Cache\\Persister\\Entity\\ReadOnlyCachedEntityPersister |
+-----------------------+-------------------------------------------------------------------------------------------+
| READ_WRITE | Doctrine\\ORM\\Cache\\Persister\\Entity\\ReadWriteCachedEntityPersister |
+-----------------------+-------------------------------------------------------------------------------------------+
| NONSTRICT_READ_WRITE | Doctrine\\ORM\\Cache\\Persister\\Entity\\NonStrictReadWriteCachedEntityPersister |
+-----------------------+-------------------------------------------------------------------------------------------+
| READ_ONLY | Doctrine\\ORM\\Cache\\Persister\\Collection\\ReadOnlyCachedCollectionPersister |
+-----------------------+-------------------------------------------------------------------------------------------+
| READ_WRITE | Doctrine\\ORM\\Cache\\Persister\\Collection\\ReadWriteCachedCollectionPersister |
+-----------------------+-------------------------------------------------------------------------------------------+
| NONSTRICT_READ_WRITE | Doctrine\\ORM\\Cache\\Persister\\Collection\\NonStrictReadWriteCachedCollectionPersister |
+-----------------------+-------------------------------------------------------------------------------------------+
+-----------------------+------------------------------------------------------------------------------------------+
| Cache Usage | Persister |
+=======================+==========================================================================================+
| READ_ONLY | ``Doctrine\ORM\Cache\Persister\Entity\ReadOnlyCachedEntityPersister`` |
+-----------------------+------------------------------------------------------------------------------------------+
| READ_WRITE | ``Doctrine\ORM\Cache\Persister\Entity\ReadWriteCachedEntityPersister`` |
+-----------------------+------------------------------------------------------------------------------------------+
| NONSTRICT_READ_WRITE | ``Doctrine\ORM\Cache\Persister\Entity\NonStrictReadWriteCachedEntityPersister`` |
+-----------------------+------------------------------------------------------------------------------------------+
| READ_ONLY | ``Doctrine\ORM\Cache\Persister\Collection\ReadOnlyCachedCollectionPersister`` |
+-----------------------+------------------------------------------------------------------------------------------+
| READ_WRITE | ``Doctrine\ORM\Cache\Persister\Collection\ReadWriteCachedCollectionPersister`` |
+-----------------------+------------------------------------------------------------------------------------------+
| NONSTRICT_READ_WRITE | ``Doctrine\ORM\Cache\Persister\Collection\NonStrictReadWriteCachedCollectionPersister`` |
+-----------------------+------------------------------------------------------------------------------------------+

Configuration
-------------
Expand All @@ -172,7 +166,7 @@ Enable Second Level Cache
~~~~~~~~~~~~~~~~~~~~~~~~~

To enable the second-level-cache, you should provide a cache factory.
``\Doctrine\ORM\Cache\DefaultCacheFactory`` is the default implementation.
``Doctrine\ORM\Cache\DefaultCacheFactory`` is the default implementation.

.. code-block:: php

Expand All @@ -196,7 +190,7 @@ Cache Factory

Cache Factory is the main point of extension.

It allows you to provide a specific implementation of the following components :
It allows you to provide a specific implementation of the following components:

``QueryCache``
stores and retrieves query cache results.
Expand All @@ -209,8 +203,6 @@ It allows you to provide a specific implementation of the following components :
``CollectionHydrator``
transforms collections into cache entries and cache entries into collections

`See API Doc <https://www.doctrine-project.org/api/orm/current/Doctrine/ORM/Cache/DefaultCacheFactory.html>`_.

Region Lifetime
~~~~~~~~~~~~~~~

Expand All @@ -234,7 +226,7 @@ Cache Log
~~~~~~~~~
By providing a cache logger you should be able to get information about all cache operations such as hits, misses and puts.

``\Doctrine\ORM\Cache\Logging\StatisticsCacheLogger`` is a built-in implementation that provides basic statistics.
``Doctrine\ORM\Cache\Logging\StatisticsCacheLogger`` is a built-in implementation that provides basic statistics.

.. code-block:: php

Expand Down Expand Up @@ -269,12 +261,9 @@ By providing a cache logger you should be able to get information about all cach
$logger->getMissCount();

If you want to get more information you should implement
``\Doctrine\ORM\Cache\Logging\CacheLogger`` and collect
``Doctrine\ORM\Cache\Logging\CacheLogger`` and collect
all the information you want.

`See API Doc <https://www.doctrine-project.org/api/orm/current/Doctrine/ORM/Cache/Logging/CacheLogger.html>`_.


Entity cache definition
-----------------------
* Entity cache configuration allows you to define the caching strategy and region for an entity.
Expand Down Expand Up @@ -330,8 +319,8 @@ level cache region.
Country:
type: entity
cache:
usage : READ_ONLY
region : my_entity_region
usage: READ_ONLY
region: my_entity_region
id:
id:
type: integer
Expand Down Expand Up @@ -401,7 +390,7 @@ It caches the primary keys of association and cache each element will be cached
</id>

<field name="name" type="string" column="name"/>

<many-to-one field="country" target-entity="Country">
<cache usage="NONSTRICT_READ_WRITE" />

Expand All @@ -421,7 +410,7 @@ It caches the primary keys of association and cache each element will be cached
State:
type: entity
cache:
usage : NONSTRICT_READ_WRITE
usage: NONSTRICT_READ_WRITE
id:
id:
type: integer
Expand All @@ -439,17 +428,18 @@ It caches the primary keys of association and cache each element will be cached
country_id:
referencedColumnName: id
cache:
usage : NONSTRICT_READ_WRITE
usage: NONSTRICT_READ_WRITE

oneToMany:
cities:
targetEntity:City
mappedBy: state
cache:
usage : NONSTRICT_READ_WRITE
usage: NONSTRICT_READ_WRITE

.. note::

> Note: for this to work, the target entity must also be marked as cacheable.
for this to work, the target entity must also be marked as cacheable.

Cache usage
~~~~~~~~~~~
Expand All @@ -466,8 +456,8 @@ Basic entity cache

$country1 = $em->find('Country', 1); // Retrieve item from cache

$country1->setName("New Name");
$country1->setName('New Name');

$em->flush(); // Hit database to update the row and update cache

$em->clear(); // Clear entity manager
Expand All @@ -492,7 +482,7 @@ Association cache
$state = $em->find('State', 1);

// Hit database to update the row and update cache entry
$state->setName("New Name");
$state->setName('New Name');
$em->persist($state);
$em->flush();

Expand Down Expand Up @@ -550,7 +540,7 @@ The query cache stores the results of the query but as identifiers, entity value
->setCacheable(true)
->getResult();

$em->clear()
$em->clear();

// Check if query result is valid and load entities from cache
$result2 = $em->createQuery('SELECT c FROM Country c ORDER BY c.name')
Expand All @@ -573,7 +563,7 @@ The Cache Mode controls how a particular query interacts with the second-level c
/* @var $em \Doctrine\ORM\EntityManager */
// Will refresh the query cache and all entities the cache as it reads from the database.
$result1 = $em->createQuery('SELECT c FROM Country c ORDER BY c.name')
->setCacheMode(Cache::MODE_GET)
->setCacheMode(\Doctrine\ORM\Cache::MODE_GET)
->setCacheable(true)
->getResult();

Expand All @@ -597,7 +587,7 @@ Execute the ``UPDATE`` and invalidate ``all cache entries`` using ``Query::HINT_
<?php
// Execute and invalidate
$this->_em->createQuery("UPDATE Entity\Country u SET u.name = 'unknown' WHERE u.id = 1")
->setHint(Query::HINT_CACHE_EVICT, true)
->setHint(\Doctrine\ORM\Query::HINT_CACHE_EVICT, true)
->execute();


Expand Down Expand Up @@ -712,11 +702,11 @@ For performance reasons the cache API does not extract from composite primary ke
$article = $em->find('Article', $article);

// Supported
$id = array('source' => 1, 'target' => 2);
$id = ['source' => 1, 'target' => 2];
$reference = $em->find('Reference', $id);

// NOT Supported
$id = array('source' => new Article(1), 'target' => new Article(2));
$id = ['source' => new Article(1), 'target' => new Article(2)];
$reference = $em->find('Reference', $id);

Distributed environments
Expand Down