Advanced Configuration

Proxy Directory (*REQUIRED*)

1
<?php
$config->setProxyDir($dir);
$config->getProxyDir();
2
3

Gets or sets the directory where Doctrine generates any proxy classes. For a detailed explanation on proxy classes and how they are used in Doctrine, refer to the "Proxy Objects" section further down.

Proxy Namespace (*REQUIRED*)

1
<?php
$config->setProxyNamespace($namespace);
$config->getProxyNamespace();
2
3

Gets or sets the namespace to use for generated proxy classes. For a detailed explanation on proxy classes and how they are used in Doctrine, refer to the "Proxy Objects" section further down.

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 5 available implementations:

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

Throughout the most part of this manual the AnnotationDriver is used in the examples. For information on the usage of the XmlDriver or YamlDriver please refer to the dedicated chapters XML Mapping and YAML Mapping.

The annotation driver can be configured with a factory method on the Doctrine\ORM\Configuration:

1
<?php
$driverImpl = $config->newDefaultAnnotationDriver('/path/to/lib/MyProject/Entities');
$config->setMetadataDriverImpl($driverImpl);
2
3

The path information to the entities is required for the annotation 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 annotations, xml or yaml, 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.

Auto-generating Proxy Classes (*OPTIONAL*)

Proxy classes can either be generated manually through the Doctrine Console or automatically at runtime by Doctrine. The configuration option that controls this behavior is:

1
<?php
$config->setAutoGenerateProxyClasses($mode);
2

Possible values for $mode are:

• Doctrine\Common\Proxy\AbstractProxyFactory::AUTOGENERATE_NEVER

Never autogenerate a proxy. You will need to generate the proxies manually, for this use the Doctrine Console like so:

1
$ ./doctrine orm:generate-proxies

When you do this in a development environment, be aware that you may get class/file not found errors if certain proxies are not yet generated. You may also get failing lazy-loads if new methods were added to the entity class that are not yet in the proxy class. In such a case, simply use the Doctrine Console to (re)generate the proxy classes.

• Doctrine\Common\Proxy\AbstractProxyFactory::AUTOGENERATE_ALWAYS

Always generates a new proxy in every request and writes it to disk.

• Doctrine\Common\Proxy\AbstractProxyFactory::AUTOGENERATE_FILE_NOT_EXISTS

Generate the proxy class when the proxy file does not exist. This strategy causes a file exists call whenever any proxy is used the first time in a request.

• Doctrine\Common\Proxy\AbstractProxyFactory::AUTOGENERATE_EVAL

Generate the proxy classes and evaluate them on the fly via eval(), avoiding writing the proxies to disk. This strategy is only sane for development.

In a production environment, it is highly recommended to use AUTOGENERATE_NEVER to allow for optimal performances. The other options are interesting in development environment.

setAutoGenerateProxyClasses can accept a boolean value. This is still possible, FALSE being equivalent to AUTOGENERATE_NEVER and TRUE to AUTOGENERATE_ALWAYS.

Reference Proxies

The method EntityManager#getReference($entityName, $identifier) lets you obtain a reference to an entity for which the identifier is known, without 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. You could simply do this:

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

Here, we added an Item to a Cart without loading the Item from the database. If you invoke any method on the Item instance, it would fully initialize its state transparently from the database. Here $item is actually an instance of the proxy class that was generated for the Item class but your code does not need to care. In fact it should not care. Proxy objects should be transparent to your code.

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.

Generating Proxy classes

In a production environment, it is highly recommended to use AUTOGENERATE_NEVER to allow for optimal performances. However you will be required to generate the proxies manually using the Doctrine Console:

1
$ ./doctrine orm:generate-proxies

The other options are interesting in development environment:

• AUTOGENERATE_ALWAYS will require you to create and configure a proxy directory. Proxies will be generated and written to file on each request, so any modification to your code will be acknowledged.
• AUTOGENERATE_FILE_NOT_EXISTS will not overwrite an existing proxy file. If your code changes, you will need to regenerate the proxies manually.
• AUTOGENERATE_EVAL will regenerate each proxy on each request, but without writing them to disk.