From 6bc21f8855b1900d21dbe2cb813f2730176257f9 Mon Sep 17 00:00:00 2001 From: Andrii Dembitskyi Date: Thu, 9 Dec 2021 23:11:22 +0200 Subject: [PATCH 1/5] Docs: consistent spacing, consistent array-style, consistent FQCN, avoid double escaped slashes, avoid double quotes if not necessary --- docs/en/reference/second-level-cache.rst | 82 ++++++++++++------------ 1 file changed, 41 insertions(+), 41 deletions(-) diff --git a/docs/en/reference/second-level-cache.rst b/docs/en/reference/second-level-cache.rst index bf7153612bc..c4f2b4f80dd 100644 --- a/docs/en/reference/second-level-cache.rst +++ b/docs/en/reference/second-level-cache.rst @@ -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 ['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 ['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 @@ -132,7 +132,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`` @@ -147,21 +147,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 ------------- @@ -172,7 +172,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 @@ -196,7 +196,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. @@ -234,7 +234,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 @@ -269,7 +269,7 @@ 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 `_. @@ -330,8 +330,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 @@ -401,7 +401,7 @@ It caches the primary keys of association and cache each element will be cached - + @@ -421,7 +421,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 @@ -439,14 +439,14 @@ 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: for this to work, the target entity must also be marked as cacheable. @@ -466,8 +466,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 @@ -492,7 +492,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(); @@ -550,7 +550,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') @@ -712,11 +712,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 From 528c45457f742194a4973a900c0ce7074e1cc927 Mon Sep 17 00:00:00 2001 From: Andrii Dembitskyi Date: Thu, 9 Dec 2021 23:11:52 +0200 Subject: [PATCH 2/5] Docs: use special note block instead of markdown-based style --- docs/en/reference/second-level-cache.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/en/reference/second-level-cache.rst b/docs/en/reference/second-level-cache.rst index c4f2b4f80dd..a1a38c83f1a 100644 --- a/docs/en/reference/second-level-cache.rst +++ b/docs/en/reference/second-level-cache.rst @@ -448,8 +448,9 @@ It caches the primary keys of association and cache each element will be cached cache: 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 ~~~~~~~~~~~ From fee3d8d6dbcad1398b96caa6db03e54706061c51 Mon Sep 17 00:00:00 2001 From: Andrii Dembitskyi Date: Sat, 11 Dec 2021 23:26:01 +0200 Subject: [PATCH 3/5] Docs: Quote FQCN in table with backticks to be compatible with all render engines --- docs/en/reference/second-level-cache.rst | 30 ++++++++++++------------ 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/en/reference/second-level-cache.rst b/docs/en/reference/second-level-cache.rst index a1a38c83f1a..ba64ef8006c 100644 --- a/docs/en/reference/second-level-cache.rst +++ b/docs/en/reference/second-level-cache.rst @@ -147,21 +147,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 ------------- From 4c58a6da9387214b751264208245de75ec325b65 Mon Sep 17 00:00:00 2001 From: Andrii Dembitskyi Date: Mon, 13 Dec 2021 16:40:34 +0200 Subject: [PATCH 4/5] Drop all mentions API doc - it is not available anymore --- docs/en/reference/second-level-cache.rst | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/docs/en/reference/second-level-cache.rst b/docs/en/reference/second-level-cache.rst index ba64ef8006c..2dbd9d44a87 100644 --- a/docs/en/reference/second-level-cache.rst +++ b/docs/en/reference/second-level-cache.rst @@ -93,8 +93,6 @@ Cache region ``Doctrine\ORM\Cache\Region`` defines a contract for accessing a particular cache region. -`See API Doc `_. - Concurrent cache region ~~~~~~~~~~~~~~~~~~~~~~~ @@ -105,8 +103,6 @@ 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 `_. - Timestamp region ~~~~~~~~~~~~~~~~ @@ -114,8 +110,6 @@ Timestamp region Tracks the timestamps of the most recent updates to particular entity. -`See API Doc `_. - .. _reference-second-level-cache-mode: Caching mode @@ -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 `_. - Region Lifetime ~~~~~~~~~~~~~~~ @@ -272,9 +264,6 @@ If you want to get more information you should implement ``Doctrine\ORM\Cache\Logging\CacheLogger`` and collect all the information you want. -`See API Doc `_. - - Entity cache definition ----------------------- * Entity cache configuration allows you to define the caching strategy and region for an entity. From bdfdeb88cbd6092ebcb4cbf3e6ccfa7cb35ab062 Mon Sep 17 00:00:00 2001 From: Andrii Dembitskyi Date: Mon, 13 Dec 2021 16:44:02 +0200 Subject: [PATCH 5/5] Add missed FQCN for code snippets --- docs/en/reference/second-level-cache.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/reference/second-level-cache.rst b/docs/en/reference/second-level-cache.rst index 2dbd9d44a87..f2643af5c0b 100644 --- a/docs/en/reference/second-level-cache.rst +++ b/docs/en/reference/second-level-cache.rst @@ -563,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(); @@ -587,7 +587,7 @@ Execute the ``UPDATE`` and invalidate ``all cache entries`` using ``Query::HINT_ _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();