What is new in Doctrine ORM 2.5?

Events: PostLoad now triggered after associations are loaded

Before Doctrine 2.5 if you had an entity with a @PostLoad event defined then Doctrine would trigger listeners after the fields were loaded, but before assocations are available.

• DDC-54
• Commit

Events: Add API to programatically add event listeners to Entity

When developing third party libraries or decoupled applications it can be interesting to develop an entity listener without knowing the entities that require this listener.

You can now attach entity listeners to entities using the AttachEntityListenersListener class, which is listening to the loadMetadata event that is fired once for every entity during metadata generation:

1
<?php
use Doctrine\ORM\Tools\AttachEntityListenersListener;
use Doctrine\ORM\Events;

$listener = new AttachEntityListenersListener();
$listener->addEntityListener(
    'MyProject\Entity\User', 'MyProject\Listener\TimestampableListener',
    Events::prePersist, 'onPrePersist'
);

$evm->addEventListener(Events::loadClassMetadata, $listener);

class TimestampableListener
{
    public function onPrePersist($event)
    {
        $entity = $event->getEntity();
        $entity->setCreated(new \DateTime('now'));
    }
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

Embeddedable Objects

Doctrine now supports creating multiple PHP objects from one database table implementing a feature called Embeddedable Objects. Next to an @Entity class you can now define a class that is embeddable into a database table of an entity using the @Embeddable annotation. Embeddable objects can never be saved, updated or deleted on their own, only as part of an entity (called root-entity or aggregate). Consequently embeddables don't have a primary key, they are identified only by their values.

Example of defining and using embeddables classes:

1
<?php

/** @Entity */
class Product
{
    /** @Id @Column(type="integer") @GeneratedValue */
    private $id;

    /** @Embedded(class = "Money") */
    private $price;
}

/** @Embeddable */
class Money
{
    /** @Column(type = "decimal") */
    private $value;

    /** @Column(type = "string") */
    private $currency = 'EUR';
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

You can read more on the features of Embeddables objects in the documentation.

This feature was developed by external contributor Johannes Schmitt

• DDC-93
• Pull Request

Second-Level-Cache

Since version 2.0 of Doctrine, fetching the same object twice by primary key would result in just one query. This was achieved by the identity map pattern (first-level-cache) that kept entities in memory.

The newly introduced second-level-cache works a bit differently. Instead of saving objects in memory, it saves them in a fast in-memory cache such as Memcache, Redis, Riak or MongoDB. Additionally it allows saving the result of more complex queries than by primary key. Summarized this feature works like the existing Query result cache, but it is much more powerful.

As an example lets cache an entity Country that is a relation to the User entity. We always want to display the country, but avoid the additional query to this table.

1
<?php
/**
 * @Entity
 * @Cache(usage="READ_ONLY", region="country_region")
 */
class Country
{
    /**
     * @Id
     * @GeneratedValue
     * @Column(type="integer")
     */
    protected $id;

    /**
     * @Column(unique=true)
     */
    protected $name;
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

In this example we have specified a caching region name called country_region, which we have to configure now on the EntityManager:

1
$config = new \Doctrine\ORM\Configuration();
$config->setSecondLevelCacheEnabled();

$cacheConfig  =  $config->getSecondLevelCacheConfiguration();
$regionConfig =  $cacheConfig->getRegionsConfiguration();
$regionConfig->setLifetime('country_region', 3600); 
2
3
4
5
6

Now Doctrine will first check for the data of any country in the cache instead of the database.

• Documentation
• Pull Request

Criteria API: Support for ManyToMany assocations

We introduced support for querying collections using the Criteria API in 2.4. This only worked efficently for One-To-Many assocations, not for Many-To-Many. With the start of 2.5 also Many-To-Many associations get queried instead of loading them into memory.

Criteria API: Add new contains() expression

It is now possible to use the Criteria API to check for string contains needle using contains(). This translates to using a column LIKE '%needle%' SQL condition.

1
<?php
use \Doctrine\Common\Collections\Criteria;

$criteria = Criteria::create()
    ->where(Criteria::expr()->contains('name', 'Benjamin'));

$users = $repository->matching($criteria);
2
3
4
5
6
7

Criteria API: Support for EXTRA_LAZY

A collection that is marked as fetch="EXTRA_LAZY" will now return another lazy collection when using Collection::matching($criteria):

1
<?php

class Post
{
    /** @OneToMany(targetEntity="Comment", fetch="EXTRA_LAZY") */
    private $comments;
}

$criteria = Criteria::create()
    ->where(Criteria->expr()->eq("published", 1));

$publishedComments = $post->getComments()->matching($criteria);

echo count($publishedComments);
2
3
4
5
6
7
8
9
10
11
12
13
14

The lazy criteria currently supports the count() and contains() functionality lazily. All other operations of the Collection interface trigger a full load of the collection.

This feature was contributed by Michaël Gallego.

• Pull Request #1
• Pull Request #2

Mapping: Allow configuring Index flags

It is now possible to control the index flags in the DBAL schema abstraction from the ORM using metadata. This was possible only with a schema event listener before.

1
<?php

/**
 * @Table(name="product", indexes={@Index(columns={"description"},flags={"fulltext"})})
 */
class Product
{
    private $description;
}
2
3
4
5
6
7
8
9

This feature was contributed by Adrian Olek.

• Pull Request

SQLFilter API: Check if a parameter is set

You can now check in your SQLFilter if a parameter was set. This allows to more easily control which features of a filter to enable or disable.

Extending on the locale example of the documentation:

1
<?php
class MyLocaleFilter extends SQLFilter
{
    public function addFilterConstraint(ClassMetadata $targetEntity, $targetTableAlias)
    {
        if (!$targetEntity->reflClass->implementsInterface('LocaleAware')) {
            return "";
        }

        if (!$this->hasParameter('locale')) {
            return "";
        }

        return $targetTableAlias.'.locale = ' . $this->getParameter('locale');
    }
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

This feature was contributed by Miroslav Demovic

• Pull Request

EXTRA_LAZY Improvements

1. Efficient query when using EXTRA_LAZY and containsKey When calling Collection::containsKey($key) on one-to-many and many-to-many collections using indexBy and EXTRA_LAZY a query is now executed to check for the existance for the item. Prevoiusly this operation was performed in memory by loading all entities of the collection. .. code-block:: php <?php class User { /* @OneToMany(targetEntity="Group", indexBy="id") / private $groups; } if ($user->getGroups()->containsKey($groupId)) { echo "User is in group $groupId\n"; } This feature was contributed by Asmir Mustafic
• Pull Request
2. Add EXTRA_LAZY Support for get() for owning and inverse many-to-many This was contributed by Sander Marechal.

Improve efficiency of One-To-Many EAGER

When marking a one-to-many association with fetch="EAGER" it will now execute one query less than before and work correctly in combination with indexBy.

Better support for EntityManagerInterface

Many of the locations where previously only the Doctrine\ORM\EntityManager was allowed are now changed to accept the EntityManagerInterface that was introduced in 2.4. This allows you to more easily use the decorator pattern to extend the EntityManager if you need. It's still not replaced everywhere, so you still have to be careful.

DQL Improvements

1. It is now possible to add functions to the ORDER BY clause in DQL statements:

1
<?php
$dql = "SELECT u FROM User u ORDER BY CONCAT(u.username, u.name)";
2

1. Support for functions in IS NULL expressions:

1
<?php
$dql = "SELECT u.name FROM User u WHERE MAX(u.name) IS NULL";
2

1. A LIKE expression is now suported in HAVING clause.
2. Subselects are now supported inside a NEW() expression:

1
<?php
$dql = "SELECT new UserDTO(u.name, SELECT count(g.id) FROM Group g WHERE g.id = u.id) FROM User u";
2

1. MEMBER OF expression now allows to filter for more than one result:

1
<?php
$dql = "SELECT u FROM User u WHERE :groups MEMBER OF u.groups";
$query = $entityManager->createQuery($dql);
$query->setParameter('groups', array(1, 2, 3));

$users = $query->getResult();
2
3
4
5
6

1. Expressions inside COUNT() now allowed

1
<?php
$dql = "SELECT COUNT(DISTINCT CONCAT(u.name, u.lastname)) FROM User u";
2

1. Add support for HOUR in DATE_ADD()/DATE_SUB() functions

Custom DQL Functions: Add support for factories

Previously custom DQL functions could only be provided with their full-qualified class-name, preventing runtime configuration through dependency injection.

A simplistic approach has been contributed by Matthieu Napoli to pass a callback instead that resolves the function:

1
<?php

$config = new \Doctrine\ORM\Configuration();

$config->addCustomNumericFunction(
    'IS_PUBLISHED', function($funcName) use ($currentSiteId) {
        return new IsPublishedFunction($currentSiteId);
     }
);
2
3
4
5
6
7
8
9

Query API: WHERE IN Query using a Collection as parameter

When performing a WHERE IN query for a collection of entities you can now pass the array collection of entities as a parameter value to the query object:

1
<?php

$categories = $rootCategory->getChildren();

$queryBuilder
    ->select('p')
    ->from('Product', 'p')
    ->where('p.category IN (:categories)')
    ->setParameter('categories', $categories)
;
2
3
4
5
6
7
8
9
10

This feature was contributed by Michael Perrin.

• Pull Request
• DDC-2319

Query API: Add suport for default Query Hints

To configure multiple different features such as custom AST Walker, fetch modes, locking and other features affecting DQL generation we have had a feature called query hints since version 2.0.

It is now possible to add query hints that are always enabled for every Query:

1
<?php

$config = new \Doctrine\ORM\Configuration();
$config->setDefaultQueryHints(
    'doctrine.customOutputWalker' => 'MyProject\CustomOutputWalker'
);
2
3
4
5
6

This feature was contributed by Artur Eshenbrener.

• Pull Request

ResultSetMappingBuilder: Add support for Single-Table Inheritance

Before 2.5 the ResultSetMappingBuilder did not work with entities that are using Single-Table-Inheritance. This restriction was lifted by adding the missing support.

YAML Mapping: Many-To-Many doesnt require join column definition

In Annotations and XML it was not necessary using conventions for naming the many-to-many join column names, in YAML it was not possible however.

A many-to-many definition in YAML is now possible using this minimal definition:

1
manyToMany:
    groups:
        targetEntity: Group
        joinTable:
            name: users_groups
2
3
4
5

Schema Validator Command: Allow to skip sub-checks

The Schema Validator command executes two independent checks for validity of the mappings and if the schema is synchronized correctly. It is now possible to skip any of the two steps when executing the command:

$ php vendor/bin/doctrine orm:validate-schema --skip-mapping
$ php vendor/bin/doctrine orm:validate-schema --skip-sync

This allows you to write more specialized continuous integration and automation checks. When no changes are found the command returns the exit code 0 and 1, 2 or 3 when failing because of mapping, sync or both.

EntityGenerator Command: Avoid backups

When calling the EntityGenerator for an existing entity, Doctrine would create a backup file every time to avoid loosing changes to the code. You can now skip generating the backup file by passing the --no-backup flag:

$ php vendor/bin/doctrine orm:generate-entities src/ --no-backup

Support for Objects as Identifiers

It is now possible to use Objects as identifiers for Entities as long as they implement the magic method __toString().

1
<?php

class UserId
{
    private $value;

    public function __construct($value)
    {
        $this->value = $value;
    }

    public function __toString()
    {
        return (string)$this->value;
    }
}

class User
{
    /** @Id @Column(type="userid") */
    private $id;

    public function __construct(UserId $id)
    {
        $this->id = $id;
    }
}

class UserIdType extends \Doctrine\DBAL\Types\Type
{
    // ...
}

Doctrine\DBAL\Types\Type::addType('userid', 'MyProject\UserIdType');
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