Doctrine Messenger Laravel Package

Getting Started

This package is a Symfony-specific bridge and does not integrate with Laravel. It provides Doctrine DBAL integration for Symfony Messenger, enabling persistent message transport using database tables. To start with Symfony:

1. Install via Composer: composer require symfony/doctrine-messenger
2. Configure a Doctrine transport in config/packages/messenger.yaml:

   framework:
       messenger:
           transports:
               async: 'doctrine://default'
   

3. Run the setup command to create the required table:

   php bin/console messenger:setup-db
   

The first use case is reliably queuing background jobs (e.g., sending emails, generating reports) without external infrastructure like RabbitMQ — ideal for environments already using Doctrine.

Implementation Patterns

• Queue separation: Use the queue_name DSN option to route messages to different logical queues in one table:

  transports:
      notifications: 'doctrine://default?queue_name=notifications'
      exports: 'doctrine://default?queue_name=exports'
  

• Consumer orchestration: Run dedicated workers per queue:

  php bin/console messenger:consume notifications --single-message
  php bin/console messenger:consume exports --time-limit=1800
  

• Retry & failure handling: Configure failure transport and middleware:

  framework:
      messenger:
          failure_transport: failed
          transports:
              async: 'doctrine://default?queue_name=async'
              failed: 'doctrine://default?queue_name=failed'
          routing:
              'App\Message\MyMessage': async
  

  Then consume the failed transport separately with messenger:consume failed.

• Custom transport options: Override table/column names and use custom Doctrine connection:

  transports:
      custom_async: 'doctrine://custom_connection?table=messaging&queue_column=channel'
  

• Observability: Create raw Doctrine queries to monitor stuck messages (e.g., SELECT COUNT(*) WHERE scheduled_at < ? AND handled_at IS NULL).

Gotchas and Tips

• MySQL deadlocks: Avoid excessive concurrent consumption on MySQL. Ensure you’re on v6.4.31+, v7.3.9+, or v8.0.3+ — older versions used SELECT FOR UPDATE that caused deadlocks. Use --memory-limit=128M in workers to reduce transaction contention.
• PostgreSQL NOTIFY behavior: With DBAL v4+, the transport now uses pg_notify() explicitly. Avoid defining triggers on the table — they’re obsolete and cause errors. Check v7.4.1+, v8.0.1+ for fixes to PHP 8.5 deprecation.
• Database-specific quirks:
  • Oracle: messenger:setup-db now handles duplicate sequences/triggers — avoid manual DDL. Use lowercase column mappings.
  • Firebird: Ensure column names match the expected lowercase schema (queue_name, body, headers).
• DBAL version mismatch: DBAL v4+ disables auto schema introspection. Run messenger:setup-db --force and verify the schema via doctrine:schema:validate.
• Unnecessary UNLISTEN calls: Fixed in v8.0.5/v6.4.33/v7.4.5. If PostgreSQL consumers disconnect unexpectedly, check your version.
• Serialization deprecations: Messages must use __serialize()/__unserialize() — __sleep()/__wakeup() were removed in PHP 8.1+ behavior and fixed in v6.4.26/v7.3.4+.
• Scaling tip: Separate long-running jobs (e.g., reports) from short-lived ones (e.g., notifications) into different queues and dedicated consumer pools to prevent lock contention and improve reliability.