Advanced Configuration

Metadata Driver (REQUIRED)

1
<?php
$config->setMetadataDriverImpl($driver);
$config->getMetadataDriverImpl();
2
3

Gets or sets the metadata driver implementation that is used by Doctrine to acquire the object-relational metadata for your classes.

There are currently 3 available implementations:

• Doctrine\ORM\Mapping\Driver\AttributeDriver
• Doctrine\ORM\Mapping\Driver\XmlDriver
• Doctrine\ORM\Mapping\Driver\DriverChain

Throughout the most part of this manual the AttributeDriver is used in the examples. For information on the usage of the XmlDriver please refer to the dedicated chapter XML Mapping.

The attribute driver can be injected in the Doctrine\ORM\Configuration:

1
<?php
use Doctrine\ORM\Mapping\Driver\AttributeDriver;

$driverImpl = new AttributeDriver(['/path/to/lib/MyProject/Entities'], true);
$config->setMetadataDriverImpl($driverImpl);
2
3
4
5

The path information to the entities is required for the attribute driver, because otherwise mass-operations on all entities through the console could not work correctly. All of metadata drivers accept either a single directory as a string or an array of directories. With this feature a single driver can support multiple directories of Entities.

Metadata Cache (RECOMMENDED)

1
<?php
$config->setMetadataCache($cache);
$config->getMetadataCache();
2
3

Gets or sets the cache adapter to use for caching metadata information, that is, all the information you supply via attributes, xml, so that they do not need to be parsed and loaded from scratch on every single request which is a waste of resources. The cache implementation must implement the PSR-6 Psr\Cache\CacheItemPoolInterface interface.

Usage of a metadata cache is highly recommended.

For development you should use an array cache like Symfony\Component\Cache\Adapter\ArrayAdapter which only caches data on a per-request basis.

Query Cache (RECOMMENDED)

1
<?php
$config->setQueryCache($cache);
$config->getQueryCache();
2
3

Gets or sets the cache implementation to use for caching DQL queries, that is, the result of a DQL parsing process that includes the final SQL as well as meta information about how to process the SQL result set of a query. Note that the query cache does not affect query results. You do not get stale data. This is a pure optimization cache without any negative side-effects (except some minimal memory usage in your cache).

Usage of a query cache is highly recommended.

For development you should use an array cache like Symfony\Component\Cache\Adapter\ArrayAdapter which only caches data on a per-request basis.

SQL Logger (Optional)

1
<?php
$config->setSQLLogger($logger);
$config->getSQLLogger();
2
3

Gets or sets the logger to use for logging all SQL statements executed by Doctrine. The logger class must implement the deprecated Doctrine\DBAL\Logging\SQLLogger interface.

Reference Proxies

The method EntityManager#getReference($entityName, $identifier) lets you obtain a reference to an entity for which the identifier is known, without necessarily loading that entity from the database. This is useful, for example, as a performance enhancement, when you want to establish an association to an entity for which you have the identifier.

Consider the following example:

1
<?php
// $em instanceof EntityManager, $cart instanceof MyProject\Model\Cart
// $itemId comes from somewhere, probably a request parameter
$item = $em->getReference('MyProject\Model\Item', $itemId);
$cart->addItem($item);
2
3
4
5

Whether the object being returned from EntityManager#getReference() is a proxy or a direct instance of the entity class may depend on different factors, including whether the entity has already been loaded into memory or entity inheritance being used. But your code does not need to care and in fact it should not care. Proxy objects should be transparent to your code.

When using the EntityManager#getReference() method, you need to be aware of a few peculiarities.

At the best case, the ORM can avoid querying the database at all. But, that also means that this method will not throw an exception when an invalid value for the $identifier parameter is passed. $identifier values are not checked and there is no guarantee that the requested entity instance even exists – the method will still return a proxy object.

Its only when the proxy has to be fully initialized or associations cannot be written to the database that invalid $identifier values may lead to exceptions.

The EntityManager#getReference() is mostly useful when you only need a reference to some entity to make an association, like in the example above. In that case, it can save you from loading data from the database that you don't need. But remember – as soon as you read any property values besides those making up the ID, a database request will be made to initialize all fields.

Association proxies

The second most important situation where Doctrine uses proxy objects is when querying for objects. Whenever you query for an object that has a single-valued association to another object that is configured LAZY, without joining that association in the same query, Doctrine puts proxy objects in place where normally the associated object would be. Just like other proxies it will transparently initialize itself on first access.