A workaround implementation for nullable embeddables in Doctrine entities.

v2.0.0 2018-05-19 09:57 UTC

This package is not auto-updated.

Last update: 2021-10-22 13:37:20 UTC


This listener enables you to have truly null values for your Doctrine embeddables. The listener hooks into the postLoad lifecycle callback and replaces embeddable values that are null.

It implements a workaround for this open issue:

The listener depends on an evaluator to check whether to instruct a nullator to actually replace the embeddable with null. This helper library ships with different implementations and respective interfaces to roll your own.

The default evaluator requires the embeddable class to implement the Tarifhaus\Doctrine\ORM\NullableEmbeddableInterface. It contains a method isNull(): bool which tells the evaluator, whether the loaded embeddable should be treated as and therefore replaced with null.

The nullator actually replaces the embeddable with null in a specific way.


There are two things you have to do, in order to have this listener working correctly.

  1. An entry to the property map has to be made. This is done by calling the \Tarifhaus\Doctrine\ORM\NullableEmbeddableListener::addMapping. It receives the FQCN (fully qualified class name) of the entity and the name of the property the embeddable resides in.

    For example:

    use Tarifhaus\Doctrine\ORM\NullableEmbeddableListenerFactory;
    $listener = NullableEmbeddableListenerFactory::createWithClosureNullator();
    $listener->addMapping('App\Domain\User\Model\UserProfile', 'address');
  2. Now the listener needs to be registered with the Doctrine EventManager.

    use Doctrine\Common\EventManager;
    use Doctrine\ORM\Events;
    use Tarifhaus\Doctrine\ORM\NullableEmbeddableListenerFactory;
    $listener = NullableEmbeddableListenerFactory::createWithClosureNullator();
    $listener->addMapping('App\Domain\User\Model\UserProfile', 'address');
    $evm = new EventManager();
    $evm->addEventListener([Events::postLoad], $listener);

Tip: It's highly recommended to use Doctrine entity listener when configuring the listener, so it is only executed for the entities it actually applies to.


In case you are using Symfony with Doctrine, you can register the listener as a service.

        public: false
        class: Tarifhaus\Doctrine\ORM\NullableEmbeddable\PropertyAccessor
            - '@property_accessor'

        public: false
        class: Tarifhaus\Doctrine\ORM\NullableEmbeddable\ClosureNullator

        public: false
        class: Tarifhaus\Doctrine\ORM\NullableEmbeddableListener
            - '@tarifhaus.doctrine.nullable_embeddable.property_accessor'
            - '@tarifhaus.doctrine.nullable_embeddable_closure_nullator'
            - ['addMapping', ['App\Domain\User\Model\UserProfile', 'address']]
            - { name: 'doctrine.orm.entity_listener', entity: '\App\Domain\User\Model\UserProfile', event: 'postLoad' }