README

This Symfony bundle streamlines configuration of messenger transports and messages dispatching using the transactional outbox pattern. The benefit of using it is that you will be able to create a transaction which saves all your unit of work on entities into the database and dispatch a messenger event or command. Either both succeed or none – you always end up in a consistent state.

Requirements

• PHP: 8.4 or 8.5
• Symfony: 7.4 LTS or 8.1

Installation

⚠️ Please mind this is a work in progress and not yet a stable release – breaking changes are possible. Please provide feedback, suggestions and bug reports using GitHub issues. Pull requests are very welcome!

Install the bundle using Composer:

composer require velpl/symfony-messenger-outbox-bundle:^0.1

Configuration and usage

1. Configure messenger buses that you want to use with the outbox pattern with the middleware provided by this bundle:

framework:
    messenger:
        buses:
            command.bus:
                middleware:
                  # - ...............
                    - 'Velpl\SymfonyMessengerOutboxBundle\Messenger\Outbox\Middleware\OutboxPatternMiddleware'
                  # - ...............

1. Configure the outbox pattern in the bundle configuration (be sure to pass the same connection name as your entity manager uses so that transaction actually can be performed):

# ............
        transports:
            outbox: 'doctrine://default?queue_name=outbox'

1. Create a message you want to dispatch and add an attribute pointing to the actual transport name that should handle it:

<?php

declare(strict_types=1);

namespace App\Message\Command;

use Velpl\SymfonyMessengerOutboxBundle\Messenger\Outbox\Attribute\AsOutboxTransport;
// .........

#[AsOutboxTransport('async_todo_creation')]
final readonly class CreateTodoCommand
{
    public function __construct(private Todo $todo) {}
    // rest of the class logic, usually some getters...
    
}

You don't need to add messages with AsOutboxTransport to the messenger.yaml routing section

1. Use entity manager to wrap your unit of work and dispatch the message in transaction:

<?php
declare(strict_types=1);

namespace App\Command;

use App\Message\Command\CreateTodoCommand;
use Doctrine\ORM\EntityManagerInterface;
// ..........

final readonly class TodoApplication service {
    public function __construct(
        private EntityManagerInterface $entityManager, 
        private MessageBusInterface $messageBus
    ) {}
    
    public function create(): void {
        $todo = new Todo()
            ->setTitle('A todo list item')
        ;
        $this->entityManager->wrapInTransaction(
            function () use ($todo): void {        
                $this->entityManager->persist($todo);
                $this->entityManager->flush();
                $this->messageBus->dispatch(new CreateTodoCommand($todo))
            }
        );
    }
}

1. Create actual handler for the CreateTodoCommand message and wire it to the command.bus with AsMessageHandler(bus: 'command.bus') attriute

2. Consume the outbox transport – it will read AsOutboxTransport on outbox message and re-dispatch it to the appropriate transport (async_todo_creation in this example - you can then consume it from there using Doctrine or any other transport like RabbitMQ):

bin/console messenger:consume outbox

License

MIT