Caching Regions

Second level cache does not store instances of an entity, instead it caches only entity identifier and values. Each entity class, collection association and query has its region, where values of each instance are stored.

Caching Regions are specific region into the cache provider that might store entities, collection or queries. Each cache region resides in a specific cache namespace and has its own lifetime configuration.

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:

1 <?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]]
];
2
3
4
5
6

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

1 <?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]]
];
2
3
4
5
6

A query region might be something like:

1 <?php
[
  'region_name:query_1_hash' => ['list' => [1, 2, 3]],
  'region_name:query_2_hash' => ['list' => [2, 3]],
  'region_name:query_3_hash' => ['list' => [2, 4]]
];
2
3
4
5
6

The following data structures represents now the cache will looks like, this is not actual cached data.

Cache Regions

Doctrine\ORM\Cache\Region\DefaultRegion is the default implementation.: A simplest cache region compatible with all doctrine-cache drivers but does not support locking.

Doctrine\ORM\Cache\Region and Doctrine\ORM\Cache\ConcurrentRegion define contracts that should be implemented by a cache provider.

It allows you to provide your own cache implementation that might take advantage of specific cache driver.

If you want to support locking for READ_WRITE strategies you should implement ConcurrentRegion; CacheRegion otherwise.

Cache region

Doctrine\ORM\Cache\Region defines a contract for accessing a particular cache region.

Concurrent cache region

A Doctrine\ORM\Cache\ConcurrentRegion is designed to store concurrently managed data region. By default, Doctrine provides a very simple implementation based on file locks Doctrine\ORM\Cache\Region\FileLockRegion.

If you want to use an READ_WRITE cache, you should consider providing your own cache region.

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

Timestamp region

Doctrine\ORM\Cache\TimestampRegion

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

Caching mode

READ_ONLY (DEFAULT)
- Can do reads, inserts and deletes, cannot perform updates or employ any locks.
- Useful for data that is read frequently but never updated.
- Best performer.
- It is Simple.
NONSTRICT_READ_WRITE
- 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
- Read Write cache employs locks before update/delete.
- Use if data needs to be updated.
- Slowest strategy.
- To use it a the cache region implementation must support locking.

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

Configuration

Doctrine allows you to specify configurations and some points of extension for the second-level-cache

Enable Second Level Cache

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

1 <?php
/** @var \Doctrine\ORM\Cache\RegionsConfiguration $cacheConfig */
/** @var \Psr\Cache\CacheItemPoolInterface $cache */
/** @var \Doctrine\ORM\Configuration $config */

$factory = new \Doctrine\ORM\Cache\DefaultCacheFactory($cacheConfig, $cache);

// Enable second-level-cache
$config->setSecondLevelCacheEnabled();

// Cache factory
$config->getSecondLevelCacheConfiguration()
    ->setCacheFactory($factory);
2
3
4
5
6
7
8
9
10
11
12
13

Cache Factory

Cache Factory is the main point of extension.

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

QueryCache: stores and retrieves query cache results.
CachedEntityPersister: stores and retrieves entity results.
CachedCollectionPersister: stores and retrieves query results.
EntityHydrator: transforms entities into a cache entries and cache entries into entities
CollectionHydrator: transforms collections into cache entries and cache entries into collections

Region Lifetime

To specify a default lifetime for all regions or specify a different lifetime for a specific region.

1 <?php
/** @var \Doctrine\ORM\Configuration $config */
/** @var \Doctrine\ORM\Cache\CacheConfiguration $cacheConfig */
/** @var \Doctrine\ORM\Cache\RegionsConfiguration $regionConfig */
$cacheConfig  =  $config->getSecondLevelCacheConfiguration();
$regionConfig =  $cacheConfig->getRegionsConfiguration();

// Cache Region lifetime
$regionConfig->setLifetime('my_entity_region', 3600);   // Time to live for a specific region (in seconds)
$regionConfig->setDefaultLifetime(7200);                // Default time to live (in seconds)
2
3
4
5
6
7
8
9
10

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.

1 <?php
/** @var \Doctrine\ORM\Configuration $config */
$logger = new \Doctrine\ORM\Cache\Logging\StatisticsCacheLogger();

// Cache logger
$config->setSecondLevelCacheEnabled(true);
$config->getSecondLevelCacheConfiguration()
    ->setCacheLogger($logger);


// Collect cache statistics

// Get the number of entries successfully retrieved from a specific region.
$logger->getRegionHitCount('my_entity_region');

// Get the number of cached entries *not* found in a specific region.
$logger->getRegionMissCount('my_entity_region');

// Get the number of cacheable entries put in cache.
$logger->getRegionPutCount('my_entity_region');

// Get the total number of put in all regions.
$logger->getPutCount();

// Get the total number of entries successfully retrieved from all regions.
$logger->getHitCount();

// Get the total number of cached entries *not* found in all regions.
$logger->getMissCount();
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

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

Entity cache definition

Entity cache configuration allows you to define the caching strategy and region for an entity.
- usage specifies the caching strategy: READ_ONLY,

NONSTRICT_READ_WRITE, READ_WRITE. See Caching mode. * region is an optional value that specifies the name of the second level cache region.

1 <?php
#[Entity]
#[Cache(usage: 'READ_ONLY', region: 'my_entity_region')]
class Country
{
    #[Id]
    #[GeneratedValue]
    #[Column]
    protected int|null $id = null;

    #[Column(unique: true)]
    protected string $name;

    // other properties and methods
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15

1 <?php
/**
 * @Entity
 * @Cache("NONSTRICT_READ_WRITE")
 */
class State
{
    /**
     * @Id
     * @GeneratedValue
     * @Column(type="integer")
     */
    protected int|null $id = null;

    /**
     * @Column(unique=true)
     */
    protected string $name;

    // other properties and methods
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

1 <?xml version="1.0" encoding="utf-8"?>
<doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
                  xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
                  xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                                      https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
  <entity name="Country">
    <cache usage="READ_ONLY" region="my_entity_region" />
    <id name="id" type="integer" column="id">
      <generator strategy="IDENTITY"/>
    </id>
    <field name="name" type="string" column="name"/>
  </entity>
</doctrine-mapping>
2
3
4
5
6
7
8
9
10
11
12
13

1 Country:
  type: entity
  cache:
    usage: READ_ONLY
    region: my_entity_region
  id:
    id:
      type: integer
      id: true
      generator:
        strategy: IDENTITY
  fields:
    name:
      type: string
2
3
4
5
6
7
8
9
10
11
12
13
14

Association cache definition

The most common use case is to cache entities. But we can also cache relationships. It caches the primary keys of association and cache each element will be cached into its region.

1 <?php
#[Entity]
#[Cache(usage: 'NONSTRICT_READ_WRITE')]
class State
{
    #[Id]
    #[GeneratedValue]
    #[Column]
    protected int|null $id = null;

    #[Column(unique: true)]
    protected string $name;

    #[Cache(usage: 'NONSTRICT_READ_WRITE')]
    #[ManyToOne(targetEntity: Country::class)]
    #[JoinColumn(name: 'country_id', referencedColumnName: 'id')]
    protected Country|null $country = null;

    /** @var Collection<int, City> */
    #[Cache(usage: 'NONSTRICT_READ_WRITE')]
    #[OneToMany(targetEntity: City::class, mappedBy: 'state')]
    protected Collection $cities;

    // other properties and methods
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

1 <?php
/**
 * @Entity
 * @Cache("NONSTRICT_READ_WRITE")
 */
class State
{
    /**
     * @Id
     * @GeneratedValue
     * @Column(type="integer")
     */
    protected int|null $id = null;

    /**
     * @Column(unique=true)
     */
    protected string $name;

    /**
     * @Cache("NONSTRICT_READ_WRITE")
     * @ManyToOne(targetEntity="Country")
     * @JoinColumn(name="country_id", referencedColumnName="id")
     */
    protected Country|null $country;

    /**
     * @Cache("NONSTRICT_READ_WRITE")
     * @OneToMany(targetEntity="City", mappedBy="state")
     * @var Collection<int, City>
     */
    protected Collection $cities;

    // other properties and methods
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

1 <?xml version="1.0" encoding="utf-8"?>
<doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
                  xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
                  xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                                      https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
  <entity name="State">

    <cache usage="NONSTRICT_READ_WRITE" />

    <id name="id" type="integer" column="id">
      <generator strategy="IDENTITY"/>
    </id>

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

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

      <join-columns>
        <join-column name="country_id" referenced-column-name="id"/>
      </join-columns>
    </many-to-one>

    <one-to-many field="cities" target-entity="City" mapped-by="state">
      <cache usage="NONSTRICT_READ_WRITE"/>
    </one-to-many>
  </entity>
</doctrine-mapping>
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

1 State:
  type: entity
  cache:
    usage: NONSTRICT_READ_WRITE
  id:
    id:
      type: integer
      id: true
      generator:
        strategy: IDENTITY
  fields:
    name:
      type: string

  manyToOne:
    state:
      targetEntity: Country
      joinColumns:
        country_id:
          referencedColumnName: id
      cache:
        usage: NONSTRICT_READ_WRITE

  oneToMany:
    cities:
      targetEntity:City
      mappedBy: state
      cache:
        usage: NONSTRICT_READ_WRITE
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

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

Cache usage

Basic entity cache

1 <?php
$em->persist(new Country($name));
$em->flush();                         // Hit database to insert the row and put into cache

$em->clear();                         // Clear entity manager

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

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

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

$em->clear();                         // Clear entity manager

$country2  = $em->find('Country', 1); // Retrieve item from cache
                                      // Notice that $country1 and $country2 are not the same instance.
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Association cache

1 <?php
// Hit database to insert the row and put into cache
$em->persist(new State($name, $country));
$em->flush();

// Clear entity manager
$em->clear();

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

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

// Create a new collection item
$city = new City($name, $state);
$state->addCity($city);

// Hit database to insert new collection item,
// put entity and collection cache into cache.
$em->persist($city);
$em->persist($state);
$em->flush();

// Clear entity manager
$em->clear();

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

// Retrieve association from cache
$country = $state->getCountry();

// Retrieve collection from cache
$cities = $state->getCities();

echo $country->getName();
echo $state->getName();

// Retrieve each collection item from cache
foreach ($cities as $city) {
    echo $city->getName();
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

Notice that all entities should be marked as cacheable.

Using the query cache

The second level cache stores the entities, associations and collections. The query cache stores the results of the query but as identifiers, entity values are actually stored in the 2nd level cache.

Query cache should always be used in conjunction with the second-level-cache for those entities which should be cached.

1 <?php
/** @var \Doctrine\ORM\EntityManager $em */

// Execute database query, store query cache and entity cache
$result1 = $em->createQuery('SELECT c FROM Country c ORDER BY c.name')
    ->setCacheable(true)
    ->getResult();

$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')
    ->setCacheable(true)
    ->getResult();
2
3
4
5
6
7
8
9
10
11
12
13
14

Cache mode

The Cache Mode controls how a particular query interacts with the second-level cache:

Cache::MODE_GET - May read items from the cache, but will not add items.
Cache::MODE_PUT - Will never read items from the cache, but will add items to the cache as it reads them from the database.
Cache::MODE_NORMAL - May read items from the cache, and add items to the cache.
Cache::MODE_REFRESH - The query will never read items from the cache, but will refresh items to the cache as it reads them from the database.

1 <?php
/** @var \Doctrine\ORM\EntityManager $em */
// 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(\Doctrine\ORM\Cache::MODE_GET)
    ->setCacheable(true)
    ->getResult();
2
3
4
5
6
7

The default query cache mode is `Cache::MODE_NORMAL`

DELETE / UPDATE queries

DQL UPDATE / DELETE statements are ported directly into a database and bypass the second-level cache. Entities that are already cached will NOT be invalidated. However the cached data could be evicted using the cache API or an special query hint.

Execute the UPDATE and invalidate all cache entries using Query::HINT_CACHE_EVICT

1 <?php
// Execute and invalidate
$this->_em->createQuery("UPDATE Entity\Country u SET u.name = 'unknown' WHERE u.id = 1")
    ->setHint(\Doctrine\ORM\Query::HINT_CACHE_EVICT, true)
    ->execute();
2
3
4
5

Execute the UPDATE and invalidate all cache entries using the cache API

1 <?php
// Execute
$this->_em->createQuery("UPDATE Entity\Country u SET u.name = 'unknown' WHERE u.id = 1")
    ->execute();
// Invoke Cache API
$em->getCache()->evictEntityRegion('Entity\Country');
2
3
4
5
6

Execute the UPDATE and invalidate a specific cache entry using the cache API

1 <?php
// Execute
$this->_em->createQuery("UPDATE Entity\Country u SET u.name = 'unknown' WHERE u.id = 1")
    ->execute();
// Invoke Cache API
$em->getCache()->evictEntity('Entity\Country', 1);
2
3
4
5
6

Using the repository query cache

As well as Query Cache all persister queries store only identifier values for an individual query. All persisters use a single timestamp cache region to keep track of the last update for each persister, When a query is loaded from cache, the timestamp region is checked for the last update for that persister. Using the last update timestamps as part of the query key invalidate the cache key when an update occurs.

1 <?php
// load from database and store cache query key hashing the query + parameters + last timestamp cache region..
$entities   = $em->getRepository('Entity\Country')->findAll();

// load from query and entities from cache..
$entities   = $em->getRepository('Entity\Country')->findAll();

// update the timestamp cache region for Country
$em->persist(new Country('zombieland'));
$em->flush();
$em->clear();

// Reload from database.
// At this point the query cache key is no longer valid, the select goes straight to the database
$entities   = $em->getRepository('Entity\Country')->findAll();
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Cache API

Caches are not aware of changes made by another application. However, you can use the cache API to check / invalidate cache entries.

1 <?php
/** @var \Doctrine\ORM\Cache $cache */
$cache = $em->getCache();

$cache->containsEntity('Entity\State', 1)      // Check if the cache exists
$cache->evictEntity('Entity\State', 1);        // Remove an entity from cache
$cache->evictEntityRegion('Entity\State');     // Remove all entities from cache

$cache->containsCollection('Entity\State', 'cities', 1);   // Check if the cache exists
$cache->evictCollection('Entity\State', 'cities', 1);      // Remove an entity collection from cache
$cache->evictCollectionRegion('Entity\State', 'cities');   // Remove all collections from cache
2
3
4
5
6
7
8
9
10
11

Limitations

Composite primary key

Composite primary key are supported by second level cache, however when one of the keys is an association the cached entity should always be retrieved using the association identifier. For performance reasons the cache API does not extract from composite primary key.

1 <?php

#[Entity]
class Reference
{
    #[Id]
    #[ManyToOne(targetEntity: Article::class, inversedBy: 'references')]
    #[JoinColumn(name: 'source_id', referencedColumnName: 'article_id')]
    private Article|null $source = null;

    #[Id]
    #[ManyToOne(targetEntity: Article::class, inversedBy: 'references')]
    #[JoinColumn(name: 'target_id', referencedColumnName: 'article_id')]
    private $target;
}

// Supported
/** @var Article $article */
$article = $em->find('Article', 1);

// Supported
/** @var Article $article */
$article = $em->find('Article', $article);

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

// NOT Supported
$id        = ['source' => new Article(1), 'target' => new Article(2)];
$reference = $em->find('Reference', $id);
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

Distributed environments

Some cache driver are not meant to be used in a distributed environment. Load-balancer for distributing workloads across multiple computing resources should be used in conjunction with distributed caching system such as memcached, redis, riak ...

Caches should be used with care when using a load-balancer if you don't share the cache. While using APC or any file based cache update occurred in a specific machine would not reflect to the cache in other machines.

Paginator

Count queries generated by Doctrine\ORM\Tools\Pagination\Paginator are not cached by second-level cache. Although entities and query result are cached, count queries will hit the database every time.

1	<?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]] ];
2
3
4
5
6

1	<?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]] ];
2
3
4
5
6

1	<?php [ 'region_name:query_1_hash' => ['list' => [1, 2, 3]], 'region_name:query_2_hash' => ['list' => [2, 3]], 'region_name:query_3_hash' => ['list' => [2, 4]] ];
2
3
4
5
6

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`

1	<?php /** @var \Doctrine\ORM\Cache\RegionsConfiguration $cacheConfig / /* @var \Psr\Cache\CacheItemPoolInterface $cache / /* @var \Doctrine\ORM\Configuration $config */ $factory = new \Doctrine\ORM\Cache\DefaultCacheFactory($cacheConfig, $cache); // Enable second-level-cache $config->setSecondLevelCacheEnabled(); // Cache factory $config->getSecondLevelCacheConfiguration() ->setCacheFactory($factory);
2
3
4
5
6
7
8
9
10
11
12
13

1	<?php /** @var \Doctrine\ORM\Configuration $config / /* @var \Doctrine\ORM\Cache\CacheConfiguration $cacheConfig / /* @var \Doctrine\ORM\Cache\RegionsConfiguration $regionConfig */ $cacheConfig = $config->getSecondLevelCacheConfiguration(); $regionConfig = $cacheConfig->getRegionsConfiguration(); // Cache Region lifetime $regionConfig->setLifetime('my_entity_region', 3600); // Time to live for a specific region (in seconds) $regionConfig->setDefaultLifetime(7200); // Default time to live (in seconds)
2
3
4
5
6
7
8
9
10

1	<?php #[Entity] #[Cache(usage: 'READ_ONLY', region: 'my_entity_region')] class Country { #[Id] #[GeneratedValue] #[Column] protected int\|null $id = null; #[Column(unique: true)] protected string $name; // other properties and methods }
2
3
4
5
6
7
8
9
10
11
12
13
14
15

1	<?php /** * @Entity * @Cache("NONSTRICT_READ_WRITE") / class State { /* * @Id * @GeneratedValue * @Column(type="integer") / protected int\|null $id = null; /* * @Column(unique=true) */ protected string $name; // other properties and methods }
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

1	<?xml version="1.0" encoding="utf-8"?> <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd"> <entity name="Country"> <cache usage="READ_ONLY" region="my_entity_region" /> <id name="id" type="integer" column="id"> <generator strategy="IDENTITY"/> </id> <field name="name" type="string" column="name"/> </entity> </doctrine-mapping>
2
3
4
5
6
7
8
9
10
11
12
13

1	Country: type: entity cache: usage: READ_ONLY region: my_entity_region id: id: type: integer id: true generator: strategy: IDENTITY fields: name: type: string
2
3
4
5
6
7
8
9
10
11
12
13
14

1	<?php #[Entity] #[Cache(usage: 'NONSTRICT_READ_WRITE')] class State { #[Id] #[GeneratedValue] #[Column] protected int\|null $id = null; #[Column(unique: true)] protected string $name; #[Cache(usage: 'NONSTRICT_READ_WRITE')] #[ManyToOne(targetEntity: Country::class)] #[JoinColumn(name: 'country_id', referencedColumnName: 'id')] protected Country\|null $country = null; /** @var Collection<int, City> */ #[Cache(usage: 'NONSTRICT_READ_WRITE')] #[OneToMany(targetEntity: City::class, mappedBy: 'state')] protected Collection $cities; // other properties and methods }
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

1	State: type: entity cache: usage: NONSTRICT_READ_WRITE id: id: type: integer id: true generator: strategy: IDENTITY fields: name: type: string manyToOne: state: targetEntity: Country joinColumns: country_id: referencedColumnName: id cache: usage: NONSTRICT_READ_WRITE oneToMany: cities: targetEntity:City mappedBy: state cache: usage: NONSTRICT_READ_WRITE
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

1	<?php $em->persist(new Country($name)); $em->flush(); // Hit database to insert the row and put into cache $em->clear(); // Clear entity manager $country1 = $em->find('Country', 1); // Retrieve item from cache $country1->setName('New Name'); $em->flush(); // Hit database to update the row and update cache $em->clear(); // Clear entity manager $country2 = $em->find('Country', 1); // Retrieve item from cache // Notice that $country1 and $country2 are not the same instance.
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

1	<?php // Hit database to insert the row and put into cache $em->persist(new State($name, $country)); $em->flush(); // Clear entity manager $em->clear(); // Retrieve item from cache $state = $em->find('State', 1); // Hit database to update the row and update cache entry $state->setName('New Name'); $em->persist($state); $em->flush(); // Create a new collection item $city = new City($name, $state); $state->addCity($city); // Hit database to insert new collection item, // put entity and collection cache into cache. $em->persist($city); $em->persist($state); $em->flush(); // Clear entity manager $em->clear(); // Retrieve item from cache $state = $em->find('State', 1); // Retrieve association from cache $country = $state->getCountry(); // Retrieve collection from cache $cities = $state->getCities(); echo $country->getName(); echo $state->getName(); // Retrieve each collection item from cache foreach ($cities as $city) { echo $city->getName(); }
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

1	<?php /** @var \Doctrine\ORM\EntityManager $em */ // Execute database query, store query cache and entity cache $result1 = $em->createQuery('SELECT c FROM Country c ORDER BY c.name') ->setCacheable(true) ->getResult(); $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') ->setCacheable(true) ->getResult();
2
3
4
5
6
7
8
9
10
11
12
13
14

1	<?php // Execute and invalidate $this->_em->createQuery("UPDATE Entity\Country u SET u.name = 'unknown' WHERE u.id = 1") ->setHint(\Doctrine\ORM\Query::HINT_CACHE_EVICT, true) ->execute();
2
3
4
5

1	<?php // Execute $this->_em->createQuery("UPDATE Entity\Country u SET u.name = 'unknown' WHERE u.id = 1") ->execute(); // Invoke Cache API $em->getCache()->evictEntityRegion('Entity\Country');
2
3
4
5
6

1	<?php // load from database and store cache query key hashing the query + parameters + last timestamp cache region.. $entities = $em->getRepository('Entity\Country')->findAll(); // load from query and entities from cache.. $entities = $em->getRepository('Entity\Country')->findAll(); // update the timestamp cache region for Country $em->persist(new Country('zombieland')); $em->flush(); $em->clear(); // Reload from database. // At this point the query cache key is no longer valid, the select goes straight to the database $entities = $em->getRepository('Entity\Country')->findAll();
2
3
4
5
6
7
8
9
10
11
12
13
14
15

1	<?php /** @var \Doctrine\ORM\Cache $cache */ $cache = $em->getCache(); $cache->containsEntity('Entity\State', 1) // Check if the cache exists $cache->evictEntity('Entity\State', 1); // Remove an entity from cache $cache->evictEntityRegion('Entity\State'); // Remove all entities from cache $cache->containsCollection('Entity\State', 'cities', 1); // Check if the cache exists $cache->evictCollection('Entity\State', 'cities', 1); // Remove an entity collection from cache $cache->evictCollectionRegion('Entity\State', 'cities'); // Remove all collections from cache
2
3
4
5
6
7
8
9
10
11

1	<?php #[Entity] class Reference { #[Id] #[ManyToOne(targetEntity: Article::class, inversedBy: 'references')] #[JoinColumn(name: 'source_id', referencedColumnName: 'article_id')] private Article\|null $source = null; #[Id] #[ManyToOne(targetEntity: Article::class, inversedBy: 'references')] #[JoinColumn(name: 'target_id', referencedColumnName: 'article_id')] private $target; } // Supported /** @var Article $article / $article = $em->find('Article', 1); // Supported /* @var Article $article */ $article = $em->find('Article', $article); // Supported $id = ['source' => 1, 'target' => 2]; $reference = $em->find('Reference', $id); // NOT Supported $id = ['source' => new Article(1), 'target' => new Article(2)]; $reference = $em->find('Reference', $id);
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

Maintained

Unmaintained