Vdm Library Doctrine Transport Bundle Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies

   composer require 3slab/vdm-library-doctrine-transport-bundle symfony/messenger symfony/orm-pack
   

   (or doctrine/mongodb-odm-bundle for ODM).

2. Configure Messenger Transport Add to config/packages/messenger.yaml:

   framework:
       messenger:
           transports:
               vdm_transport:
                   dsn: 'vdm+doctrine_orm://default'
                   options:
                       default_entity: 'App\Entity\YourEntity'
   

3. First Use Case Dispatch a message to persist an entity:

   use Vdm\Library\DoctrineTransportBundle\Message\VdmMessage;
   
   $message = new VdmMessage(
       'App\Entity\YourEntity',
       ['id' => '123', 'name' => 'Test']
   );
   $this->messageBus->dispatch($message);
   

Implementation Patterns

Core Workflows

1. Entity Persistence via Messages Use VdmMessage to trigger CRUD operations:

   // Create
   $this->messageBus->dispatch(new VdmMessage('App\Entity\User', ['name' => 'John']));
   
   // Update
   $this->messageBus->dispatch(new VdmMessage('App\Entity\User', ['id' => 1, 'name' => 'Updated']));
   
   // Delete
   $this->messageBus->dispatch(new VdmMessage('App\Entity\User', ['id' => 1, '__action__' => 'DELETE']));
   

2. Custom Selectors Override default entity selection logic:

   options:
       entities:
           App\Entity\Order:
               selector: 'orderNumber'  # Uses this field instead of 'id'
   

3. Async Processing Combine with Symfony Messenger’s async transports (e.g., doctrine or amqp):

   transports:
       async_vdm:
           dsn: 'vdm+doctrine_orm://default'
           retry_strategy:
               max_retries: 3
           router:
               type: 'single'
   

Integration Tips

• Event Listeners: Attach listeners to VdmMessage for pre/post-processing:

  public function __invoke(VdmMessage $message, DispatcherInterface $dispatcher)
  {
      if ($message->getEntityClass() === User::class) {
          $dispatcher->dispatch(new UserEvent($message->getData()));
      }
  }
  

• Doctrine Events: Leverage postPersist, postUpdate, etc., to sync with other systems.
• Validation: Use Symfony Validator to validate message payloads before dispatching.

Gotchas and Tips

Pitfalls

1. DSN Format Strictness

   • Incorrect DSN (e.g., missing vdm+doctrine_orm://) throws RuntimeException.
   • Fix: Verify DSN matches vdm+doctrine_[orm|odm]://[connection].

2. Entity Not Found

   • If default_entity is set but the entity doesn’t exist, the transport fails silently.
   • Fix: Validate entity classes exist in bootstrap.php or a service compiler pass.

3. Transaction Handling

   • Messages are processed outside the current Doctrine transaction.
   • Fix: Use DoctrineExecutor with explicit transactions if needed:

     options:
         doctrine_executor: 'app.custom_doctrine_executor'
     

4. ODM vs. ORM Quirks

   • ODM requires _id field for selection; ORM defaults to id.
   • Fix: Configure selector explicitly for ODM entities.

Debugging Tips

• Enable Messenger Debugging Add to config/packages/dev/messenger.yaml:

  framework:
      messenger:
          transports:
              vdm_transport:
                  dsn: 'vdm+doctrine_orm://default'
                  options:
                      logger: true  # Logs all messages
  

• Check Transport Options Use dump() to inspect resolved options:

  $container->get('messenger.transport.vdm_transport')->getOptions();
  

• Custom Executor Logging Extend DefaultDoctrineExecutor to log operations:

  class CustomExecutor extends DefaultDoctrineExecutor
  {
      public function execute(VdmMessage $message): void
      {
          \Log::debug('Executing VDM message', ['entity' => $message->getEntityClass()]);
          parent::execute($message);
      }
  }
  

Extension Points

1. Custom Message Handlers Create a handler for specific message types:

   class CustomVdmHandler implements MessageHandlerInterface
   {
       public function __invoke(VdmMessage $message)
       {
           if ($message->getEntityClass() === SpecialEntity::class) {
               // Custom logic
           }
       }
   }
   

   Register in services.yaml:

   services:
       App\MessageHandler\CustomVdmHandler:
           tags:
               - { name: 'messenger.message_handler', handles: 'Vdm\Library\DoctrineTransportBundle\Message\VdmMessage' }
   

2. Dynamic Entity Mapping Use a compiler pass to dynamically configure entities:

   class VdmEntityPass implements CompilerPassInterface
   {
       public function process(ContainerBuilder $container)
       {
           $definition = $container->getDefinition('messenger.transport.vdm_transport');
           $definition->replaceArgument(
               0,
               array_merge($definition->getArgument(0), ['App\Entity\DynamicEntity' => 'dynamicId'])
           );
       }
   }
   

3. Bulk Operations Process multiple entities in a single message:

   $message = new VdmMessage('App\Entity\Product', [
       ['id' => 1, 'price' => 10.99],
       ['id' => 2, 'price' => 20.99],
       '__action__' => 'UPDATE'
   ]);
   

   Note: Requires custom executor logic to handle arrays.