202 lines
6.7 KiB
ReStructuredText
202 lines
6.7 KiB
ReStructuredText
Doctrine Internals explained
|
|
============================
|
|
|
|
Object relational mapping is a complex topic and sufficiently understanding how Doctrine works internally helps you use its full power.
|
|
|
|
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 EntiyManager and
|
|
ask for an entity with a specific ID twice, it will return the same instance:
|
|
|
|
.. code-block:: php
|
|
|
|
public function testIdentityMap()
|
|
{
|
|
$objectA = $this->entityManager->find('EntityName', 1);
|
|
$objectB = $this->entityManager->find('EntityName', 1);
|
|
|
|
$this->assertSame($objectA, $objectB)
|
|
}
|
|
|
|
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:
|
|
|
|
.. code-block:: php
|
|
|
|
public function testIdentityMapReference()
|
|
{
|
|
$objectA = $this->entityManager->getReference('EntityName', 1);
|
|
// check for proxyinterface
|
|
$this->assertInstanceOf('Doctrine\ORM\Proxy\Proxy', $objectA);
|
|
|
|
$objectB = $this->entityManager->find('EntityName', 1);
|
|
|
|
$this->assertSame($objectA, $objectB)
|
|
}
|
|
|
|
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:
|
|
|
|
.. code-block:: php
|
|
|
|
public function testIdentityMapRepositoryFindBy()
|
|
{
|
|
$repository = $this->entityManager->getRepository('Person');
|
|
$objectA = $repository->findOneBy(array('name' => 'Benjamin'));
|
|
$objectB = $repository->findOneBy(array('name' => 'Benjamin'));
|
|
|
|
$this->assertSame($objectA, $objectB);
|
|
}
|
|
|
|
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``:
|
|
|
|
.. code-block:: php
|
|
|
|
<?php
|
|
$user = $entityManager->find("Person", 1);
|
|
$user->setName("Guilherme");
|
|
$entityManager->flush();
|
|
|
|
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 qeued for an 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 :doc:`Change Tracking Policies <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.
|
|
|
|
Hydration
|
|
~~~~~~~~~
|
|
|
|
Responsible for creating a final result from a raw database statement and a
|
|
result-set mapping object. The developer can choose which kind of result he
|
|
wishes to be hydrated. Default result-types include:
|
|
|
|
- SQL to Entities
|
|
- SQL to structured Arrays
|
|
- SQL to simple scalar result arrays
|
|
- SQL to a single result variable
|
|
|
|
Hydration to entities and arrays is one of most complex parts of Doctrine
|
|
algorithm-wise. It can built results with for example:
|
|
|
|
- Single table selects
|
|
- Joins with n:1 or 1:n cardinality, grouping belonging to the same parent.
|
|
- Mixed results of objects and scalar values
|
|
- Hydration of results by a given scalar value as key.
|
|
|
|
Persisters
|
|
~~~~~~~~~~
|
|
|
|
tbr
|
|
|
|
UnitOfWork
|
|
~~~~~~~~~~
|
|
|
|
tbr
|
|
|
|
ResultSetMapping
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
tbr
|
|
|
|
DQL Parser
|
|
~~~~~~~~~~
|
|
|
|
tbr
|
|
|
|
SQLWalker
|
|
~~~~~~~~~
|
|
|
|
tbr
|
|
|
|
EntityManager
|
|
~~~~~~~~~~~~~
|
|
|
|
tbr
|
|
|
|
ClassMetadataFactory
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
tbr
|
|
|