composer require 3slab/vdm-library-doctrine-transport-bundle
You need to have either (or both) doctrine ORM or ODM installed
composer require symfony/orm-pack
Or
composer require doctrine/mongodb-odm-bundle
There are two parts ton configure: the transport, and Doctrine's behaviour.
In messenger.yaml
:
framework:
messenger:
transports:
producer:
dsn: vdm+doctrine_orm://mycustomconnection
options:
doctrine_executor: ~
default_entity: ~
entities:
App\Entity\Demande:
selector: RefDemande
Configuration | Description |
---|---|
dsn | Use vdm+doctrine_orm:// (if entity manager) or vdm+doctrine_odm:// (if document manager). Optionnaly, you can specify the connection to use with vdm+doctrine_orm://mycustomconnection (fits into doctrine.orm.xxx_entity_manager ). |
options.doctrine_executor | set the id (in the container of services) of a custom doctrine executor to use instead of the DefaultDoctrineExecutor |
options.default_entity | set the class of default entity to populate if none passed in the message metadatas |
options.entities | Array of entities to register. At least one entity must be declared. |
options.entities.FQCN.selector | (optional) Define how the executor will try and fetch a pre-existing entity before persisting (see below) |
Before persisting anything, this transport will always try to find an existing entity. You need to tell it how to proceed. You have several ways of doing it.
It means that your entity bears a unique identifier value, such as:
/**
* @ORM\Id()
*/
private $id;
If this value is carried by the incoming message, then you have nothing to configure. The only responsability on your end is making sure there is a public getter for this property (if there isn't you'll get a clear error message anyway).
Note: in this case, the sender will use the find
method on the repository.
In case you don't have a mono-column primary key (ex: no key at all or composite key), you can turn to another
approach and tell the executor which fields should be used to retrieve a pre-existing entity. For instance, if
your entity has two fields representing its identity (let's say code
and hash
), and they both have a natural
getter (i.e. getCode
and getHash
), then you need to configure the options like this:
framework:
messenger:
transports:
producer:
dsn: vdm+doctrine://
options:
entities:
App\Entity\Demande:
selector:
- code
- hash
Under the hood, the repository will be called like:
$repo->findOneBy([ 'code' => $yourEntity->getCode(), 'hash' => $yourEntity->getHash() ])
Note: Notice the findOneBy
. The sender will use the first matching entity. It's your responsability to provide
a unique set of filter.
In case the fields related to the identity have unnatural getters (ex: legacy code, multilingual code), you can
define which getter to use to fetch the appropriate property. Let's say the identity is made of two fields: label
and hash
, which respective getters are getLibelle()
and hash()
. You will need configure the sender as such:
framework:
messenger:
transports:
producer:
dsn: vdm+doctrine://
options:
entities:
App\Entity\Demande:
selector:
label: getLibelle
hash: hash
Under the hood, the repository will be called like:
$repo->findOneBy([ 'label' => $yourEntity->getLibelle(), 'hash' => $yourEntity->hash() ])
The same policy as natural getters apply: you have to make sure it returns something as unique as possible.
You can define several entities at once, and mix natural and non-natural getters. However, you will have to prefix your natural getters with integer keys. The key itself doesn't matter (as long as you don't create duplicates), it just needs to be an integer. If the key is an integer, the getter will be guessed. Otherwise, the getter will be what you provide
framework:
messenger:
transports:
producer:
dsn: vdm+doctrine://
options:
entities:
App\Entity\Foo:
selector:
0: code # hack to mix natural and non-natural getters
label: getLibelle #non natural getter
hash: hash #non natural getter
App\Entity\Bar: ~ # Bar has a single-field identity (id) with natural getter, no configuration needed
App\Entity\Baz:
selector:
- reference # Baz uses a filter based on its reference with natural getter (getReference)
Under the hood, the repository will fetch the entities like this:
// Foo
$repo->findOneBy([ 'code' => $foo->getCode(), 'label' => $foo->getLibelle(), 'hash' => $foo->hash() ]);
// Bar
$repo->find($bar->getId());
// Baz
$repo->findOneBy([ 'reference' => $baz->getReference() ]);
Doctrine executor allows you to customize the behavior of the doctrine ORM transport per transport definition
inside your messenger.yaml
file.
If you don't set a custom doctrine_executor
option when declaring the transport, the default
DefaultDoctrineExecutor is used.
You can override this behavior in your project by providing a class that extends
Vdm\Bundle\LibraryDoctrineTransportBundle\Executor\AbstractDoctrineExecutor
.
namespace App\Executor\Doctrine;
use Vdm\Bundle\LibraryDoctrineTransportBundle\Executor\AbstractDoctrineExecutor;
use Vdm\Bundle\LibraryBundle\Model\Message;
class CustomDoctrineExecutor extends AbstractDoctrineExecutor
{
public function execute(Message $message): void
{
if (!$this->manager) {
throw new NoConnectionException('No connection was defined.');
}
$entityMetadatas = $message->getMetadatasByKey('entity');
$entityMetadata = array_shift($entityMetadatas);
$entityClass = $entityMetadata->getValue();
$entity = $this->serializer->denormalize($message->getPayload(), $entityClass);
$entity = $this->matchEntity($entity);
$this->manager->persist($entity);
$this->manager->flush();
}
}
Then references this custom executor in your transport definition in your project messenger.yaml
:
framework:
messenger:
transports:
store-entity:
options:
doctrine_executor: App\Executor\Doctrine\CustomDoctrineExecutor
For the transport to know to which entities or documents the payload should be persisted, you can either :
- provide the entity's fully qualified class name in the message's metadata, with key
entity
. Examplenew Metadata('entity', 'App\Entity\Foo')
. - configure a default entity on the transport level
framework:
messenger:
transports:
store-entity:
options:
default_entity: App\Entity\Foo
You cannot use different connections for different entities within one single transport. Should you have such a need, you should define one transport per connection, extends the library's Message (one per producer) and route the correct message to the correct producer.