Advanced Configuration

The configuration of the EntityManager requires a Doctrine\ORM\Configuration instance as well as some database connection parameters. This example shows all the potential steps of configuration.

1
<?php

use Doctrine\ORM\Configuration;
use Doctrine\ORM\EntityManager;
use Symfony\Component\Cache\Adapter\ArrayAdapter;
use Symfony\Component\Cache\Adapter\PhpFilesAdapter;

// ...

if ($applicationMode == "development") {
    $queryCache = new ArrayAdapter();
    $metadataCache = new ArrayAdapter();
} else {
    $queryCache = new PhpFilesAdapter('doctrine_queries');
    $metadataCache = new PhpFilesAdapter('doctrine_metadata');
}

$config = new Configuration;
$config->setMetadataCache($metadataCache);
$driverImpl = $config->newDefaultAnnotationDriver('/path/to/lib/MyProject/Entities');
$config->setMetadataDriverImpl($driverImpl);
$config->setQueryCache($queryCache);
$config->setProxyDir('/path/to/myproject/lib/MyProject/Proxies');
$config->setProxyNamespace('MyProject\Proxies');

if ($applicationMode == "development") {
    $config->setAutoGenerateProxyClasses(true);
} else {
    $config->setAutoGenerateProxyClasses(false);
}

$connectionOptions = array(
    'driver' => 'pdo_sqlite',
    'path' => 'database.sqlite'
);

$em = EntityManager::create($connectionOptions, $config);
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

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

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

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

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

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

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

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

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

1
$ ./doctrine orm:generate-proxies

Development vs Production Configuration

You should code your Doctrine2 bootstrapping with two different runtime models in mind. There are some serious benefits of using APCu or Memcache in production. In development however this will frequently give you fatal errors, when you change your entities and the cache still keeps the outdated metadata. That is why we recommend an array cache for development.

Furthermore you should have the Auto-generating Proxy Classes option to true in development and to false in production. If this option is set to TRUE it can seriously hurt your script performance if several proxy classes are re-generated during script execution. Filesystem calls of that magnitude can even slower than all the database queries Doctrine issues. Additionally writing a proxy sets an exclusive file lock which can cause serious performance bottlenecks in systems with regular concurrent requests.

Connection Options

The $connectionOptions passed as the first argument to EntityManager::create() has to be either an array or an instance of Doctrine\DBAL\Connection. If an array is passed it is directly passed along to the DBAL Factory Doctrine\DBAL\DriverManager::getConnection(). The DBAL configuration is explained in the DBAL section.

Proxy Objects

A proxy object is an object that is put in place or used instead of the real object. A proxy object can add behavior to the object being proxied without that object being aware of it. In ORM, proxy objects are used to realize several features but mainly for transparent lazy-loading.

Proxy objects with their lazy-loading facilities help to keep the subset of objects that are already in memory connected to the rest of the objects. This is an essential property as without it there would always be fragile partial objects at the outer edges of your object graph.

Doctrine ORM implements a variant of the proxy pattern where it generates classes that extend your entity classes and adds lazy-loading capabilities to them. Doctrine can then give you an instance of such a proxy class whenever you request an object of the class being proxied. This happens in two situations:

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

1
$ ./doctrine orm:generate-proxies

Autoloading Proxies

When you deserialize proxy objects from the session or any other storage it is necessary to have an autoloading mechanism in place for these classes. For implementation reasons Proxy class names are not PSR-0 compliant. This means that you have to register a special autoloader for these classes:

1
<?php
use Doctrine\Common\Proxy\Autoloader;

$proxyDir = "/path/to/proxies";
$proxyNamespace = "MyProxies";

Autoloader::register($proxyDir, $proxyNamespace);
2
3
4
5
6
7

If you want to execute additional logic to intercept the proxy file not found state you can pass a closure as the third argument. It will be called with the arguments proxydir, namespace and className when the proxy file could not be found.

Multiple Metadata Sources

When using different components using Doctrine ORM you may end up with them using two different metadata drivers, for example XML and YAML. You can use the DriverChain Metadata implementations to aggregate these drivers based on namespaces:

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

$chain = new DriverChain();
$chain->addDriver($xmlDriver, 'Doctrine\Tests\Models\Company');
$chain->addDriver($yamlDriver, 'Doctrine\Tests\ORM\Mapping');
2
3
4
5
6

Based on the namespace of the entity the loading of entities is delegated to the appropriate driver. The chain semantics come from the fact that the driver loops through all namespaces and matches the entity class name against the namespace using a strpos() === 0 call. This means you need to order the drivers correctly if sub-namespaces use different metadata driver implementations.

Default Repository (OPTIONAL)

Specifies the FQCN of a subclass of the EntityRepository. That will be available for all entities without a custom repository class.

1
<?php
$config->setDefaultRepositoryClassName($fqcn);
$config->getDefaultRepositoryClassName();
2
3

The default value is Doctrine\ORM\EntityRepository. Any repository class must be a subclass of EntityRepository otherwise you got an ORMException

Setting up the Console

Doctrine uses the Symfony Console component for generating the command line interface. You can take a look at the vendor/bin/doctrine.php script and the Doctrine\ORM\Tools\Console\ConsoleRunner command for inspiration how to setup the cli.

In general the required code looks like this:

1
<?php
$cli = new Application('Doctrine Command Line Interface', \Doctrine\ORM\Version::VERSION);
$cli->setCatchExceptions(true);
$cli->setHelperSet($helperSet);
Doctrine\ORM\Tools\Console\ConsoleRunner::addCommands($cli);
$cli->run();
2
3
4
5
6