Doctrine Internals explained

How Doctrine keeps track of Objects

Doctrine uses the Identity Map pattern to track objects. Whenever you fetch an object from the database, Doctrine will keep a reference to this object inside its UnitOfWork. The array holding all the entity references is two-levels deep and has the keys "root entity name" and "id". Since Doctrine allows composite keys the id is a sorted, serialized version of all the key columns.

This allows Doctrine room for optimizations. If you call the EntityManager and ask for an entity with a specific ID twice, it will return the same instance:

1
public function testIdentityMap(): void
{
    $objectA = $this->entityManager->find('EntityName', 1);
    $objectB = $this->entityManager->find('EntityName', 1);

    $this->assertSame($objectA, $objectB)
}
2
3
4
5
6
7

Only one SELECT query will be fired against the database here. In the second EntityManager#find() call Doctrine will check the identity map first and doesn't need to make that database roundtrip.

Even if you get a proxy object first then fetch the object by the same id you will still end up with the same reference:

1
public function testIdentityMapReference(): void
{
    $objectA = $this->entityManager->getReference('EntityName', 1);
    // check entity is not initialized
    $this->assertTrue($this->entityManager->isUninitializedObject($objectA));

    $objectB = $this->entityManager->find('EntityName', 1);

    $this->assertSame($objectA, $objectB)
}
2
3
4
5
6
7
8
9
10

The identity map being indexed by primary keys only allows shortcuts when you ask for objects by primary key. Assume you have the following persons table:

id | name
-------------
1  | Benjamin
2  | Bud

Take the following example where two consecutive calls are made against a repository to fetch an entity by a set of criteria:

1
public function testIdentityMapRepositoryFindBy()
{
    $repository = $this->entityManager->getRepository('Person');
    $objectA = $repository->findOneBy(array('name' => 'Benjamin'));
    $objectB = $repository->findOneBy(array('name' => 'Benjamin'));

    $this->assertSame($objectA, $objectB);
}
2
3
4
5
6
7
8

This query will still return the same references and $objectA and $objectB are indeed referencing the same object. However when checking your SQL logs you will realize that two queries have been executed against the database. Doctrine only knows objects by id, so a query for different criteria has to go to the database, even if it was executed just before.

But instead of creating a second Person object Doctrine first gets the primary key from the row and check if it already has an object inside the UnitOfWork with that primary key. In our example it finds an object and decides to return this instead of creating a new one.

The identity map has a second use-case. When you call EntityManager#flush Doctrine will ask the identity map for all objects that are currently managed. This means you don't have to call EntityManager#persist over and over again to pass known objects to the EntityManager. This is a NO-OP for known entities, but leads to much code written that is confusing to other developers.

The following code WILL update your database with the changes made to the Person object, even if you did not call EntityManager#persist:

1
<?php
$user = $entityManager->find("Person", 1);
$user->setName("Guilherme");
$entityManager->flush();
2
3
4

How Doctrine Detects Changes

Doctrine is a data-mapper that tries to achieve persistence-ignorance (PI). This means you map PHP objects into a relational database that don't necessarily know about the database at all. A natural question would now be, "how does Doctrine even detect objects have changed?".

For this Doctrine keeps a second map inside the UnitOfWork. Whenever you fetch an object from the database Doctrine will keep a copy of all the properties and associations inside the UnitOfWork. Because variables in the PHP language are subject to "copy-on-write" the memory usage of a PHP request that only reads objects from the database is the same as if Doctrine did not keep this variable copy. Only if you start changing variables PHP will create new variables internally that consume new memory.

Now whenever you call EntityManager#flush Doctrine will iterate over the Identity Map and for each object compares the original property and association values with the values that are currently set on the object. If changes are detected then the object is queued for a SQL UPDATE operation. Only the fields that actually changed are updated.

This process has an obvious performance impact. The larger the size of the UnitOfWork is, the longer this computation takes. There are several ways to optimize the performance of the Flush Operation:

• Mark entities as read only. These entities can only be inserted or removed, but are never updated. They are omitted in the changeset calculation.
• Temporarily mark entities as read only. If you have a very large UnitOfWork but know that a large set of entities has not changed, just mark them as read only with $entityManager->getUnitOfWork()->markReadOnly($entity).
• Flush only a single entity with $entityManager->flush($entity).
• Use Change Tracking Policies to use more explicit strategies of notifying the UnitOfWork what objects/properties changed.

Query Internals

The different ORM Layers

Doctrine ships with a set of layers with different responsibilities. This section gives a short explanation of each layer.