Sulu Messenger Failed Queue Bundle Laravel Package

Getting Started

Know what you're installing first. This is a Symfony bundle for Sulu CMS 2.x, not a Laravel package — there is no service provider, no config/failed-queue.php, no artisan command. It puts a Sulu Admin screen on top of Symfony Messenger's failure transport, so operators can inspect, retry, and delete failed async messages without touching the database. If you're in a pure Laravel app, the equivalent ground you already stand on is failed_jobs + queue:failed + Horizon; read this assessment as "the pattern to copy," not "the package to install."

Minimal path if you do have a Sulu app:

1. composer require tailrdigital/sulu-messenger-failed-queue-bundle (PHP 8.x, Sulu 2.x, symfony/messenger).

2. Register the bundle in config/bundles.php (...::class => ['all' => true]), then bin/console cache:clear. Check the README for the exact FQCN — 0.x naming has moved.

3. In config/packages/messenger.yaml, declare a durable failed transport and point Messenger at it:

   framework:
       messenger:
           failure_transport: failed
           transports:
               async:  'doctrine://default'
               failed: 'doctrine://default?queue_name=failed'
   

4. Create the tables: bin/console messenger:setup-transports.

5. Verify from the CLI before the UI: dispatch a message that throws, watch retries exhaust, then bin/console messenger:failed:show.

First use case: an async job (index rebuild, mail send, webhook fan-out) blows past max_retries. Instead of someone SQL-ing the messenger_messages table at 2am, an editor opens Sulu Admin → failed queue, reads the exception, and either retries after your fix ships or deletes a poison message.

Implementation Patterns

• Tune the retry strategy at the transport, not in the bundle. retry_strategy: { max_retries: 3, delay: 1000, multiplier: 2 } decides when something becomes a "failed" item. Everything downstream — UI, alerting, triage — assumes that boundary is sane.
• One failure transport, or several. If the bundle exposes transport selection, split by domain (payments vs. search indexing) so retrying a batch doesn't drag unrelated messages along. If it doesn't, keep one and tag messages with a correlation id you can filter on.
• Lock down the security context. Sulu permissions are context-based; grant the bundle's context to editor roles, not just superadmins. Retry is a write operation against production queues — treat it like one.
• Alert, then triage. Poll the failure transport (row count for Doctrine, queue depth for AMQP) into your health endpoint / Prometheus. The admin UI is the resolution surface, not the detection surface.
• Retry is a post-deploy action. Fix → deploy → then bulk retry, so retried messages re-enter the original transport against corrected code. Retrying before the deploy just burns the message again.
• Local dev: keep sync:// for the default transport but retain a real failure transport, otherwise you'll never see the failure path until prod.
• Laravel translation of the pattern: Filament/Nova resource over failed_jobs, actions mapped to queue:retry {id} and queue:forget {id}, plus a queue.failed count in your health check. The bundle's value is entirely in that UX, and you can rebuild it in an afternoon.

Gotchas and Tips

• 0.4.1 is a dev-dependency bump only — jackalope-doctrine-dbal, the PHPCR/Jackalope stack used to boot a test Sulu kernel. No runtime code, no API surface, no config schema change. Drop-in safe from 0.4.0.
• Still pre-1.0. Pin to ~0.4.0 and read changelogs before minor bumps; the admin route/controller layer is the most likely thing to shift.
• The failure transport cannot be sync. Failed messages need durable storage; a sync failure transport silently loses them.
• messenger:setup-transports in every environment, including prod. The failure transport may need its own queue/table provisioned separately from the default one, and it's easy to set up async and forget failed.
• Serialized payloads pin class names. Rename or move a message class and retry fails at unserialize time — the message is now only deletable. Keep messages in a stable namespace, or ship a serializer that tolerates moves.
• Retry counts can carry over. A message that already exhausted its retries may fail instantly on the first retry attempt; check whether the counter resets before promising editors "retry will give it three more goes."
• Clear the cache after bundle registration or messenger config edits. Sulu Admin is aggressively cached and a stale container produces very confusing "route not found" symptoms.
• Extension points: decorate the failure-transport service or the admin controller to add custom actions (e.g. "retry with a patched payload"), and register a dedicated security context for granular role access.
• Debugging: messenger:failed:show <id> -vvv gives the full stack trace; the admin view truncates. When an editor reports "it just says failed," you want the CLI output.