Sulu Messenger Failed Queue Bundle Laravel Package

Getting Started

Install the bundle via Composer:

composer require phpro/sulu-messenger-failed-queue-bundle

Register the bundle in config/bundles.php (Symfony Flex usually handles this):

Phpro\SuluMessengerFailedQueueBundle\SuluMessengerFailedQueueBundle::class => ['all' => true],

Then wire Symfony Messenger's failure transport so failed Sulu messages land in a queryable queue. The bundle's job is to expose that failure queue inside the Sulu admin, so the first thing to look at is config/packages/messenger.yaml — ensure a failure_transport is defined and that the transports Sulu dispatches to (e.g. sulu_audit, custom content transports, scheduled publishing) route into it.

framework:
    messenger:
        failure_transport: failed
        transports:
            failed:
                dsn: 'doctrine://default?queue_name=failed'
            # your Sulu-related transports...

First use case: publish a piece of content in Sulu with a handler that throws, confirm the message lands in the failed transport (bin/console messenger:failed:show), and then verify it appears in the Sulu "Failed messages" admin section. That two-sided check validates both the transport wiring and the admin integration — the two things that most commonly break.

Implementation Patterns

Failure transport as the integration seam. This bundle is really a thin UI/serialization layer over Symfony Messenger's failure transport. Keep all your retry/triage logic in Symfony (messenger:failed:retry, messenger:failed:remove) and use the bundle for visibility in Sulu. Don't duplicate retry logic in your own admin controllers.

Route only what Sulu dispatches. Rather than dumping every message into the failed transport, scope it to Sulu's transports. This keeps the failed queue meaningful — operators see content/publishing failures, not unrelated background jobs.

Doctrine transport for production. The doctrine:// DSN is the usual choice because it survives restarts and is trivially inspectable. Avoid in-memory:// here — failed messages are the one place where losing state on deploy is catastrophic for operators.

Operator workflow. The typical day-to-day pattern is: a content editor publishes, a handler (e.g. an external API sync) fails, the failed-message entry surfaces in the Sulu admin, an operator retries after the upstream issue is resolved. Design handlers to be idempotent so retries are safe — the bundle gives you retry buttons, so the underlying handlers must tolerate being run twice.

Testing. Write a functional test that dispatches a deliberately failing message through a Sulu transport in a test kernel and asserts the failure transport contains the envelope. This is the fastest regression guard against messenger config drift.

Gotchas and Tips

PHP 8.4 requirement. Release 1.2.0 bumped PHP support to 8.4. If you're still on 8.3, pin to ^1.1; if you upgrade, re-run your CI matrix — this is a "feature/bump php" release, so treat it as a compatibility signal rather than a behaviour change, but lock your platform constraint appropriately.

Version alignment with Sulu. This bundle tracks Sulu's admin and Messenger integration. Before bumping the bundle, check the Sulu core version it targets in composer.json — mismatch here is the most common cause of the admin panel rendering a blank failed-message grid.

Failure transport must exist before first deploy. If failure_transport is unset, Sulu dispatches will simply throw and vanish rather than being queued. Add an explicit config assertion or a health-check command in your deploy pipeline.

Serialization matters. Failed messages are stored serialized. If you change a message class's constructor signature or namespace, previously failed messages will fail to unserialize on retry. Either keep message classes stable, or plan to drain the failed queue before deploying breaking message changes.

Permission model. Access to the failed-queue UI is gated by Sulu security. Don't assume every admin user sees it — verify role configuration in the Sulu security setup; support tickets about "missing failed queue" are almost always a permission, not a bundle, issue.

Debugging. Use bin/console messenger:failed:show -vv to see the underlying exception before touching the Sulu UI. The bundle surfaces the same data, but the CLI is faster for triage. For extension, override the bundle's admin templates under templates/bundles/SuluMessengerFailedQueueBundle/ if you need to add context (e.g. tenant or website) to the display.