Worker Message Failed Event Bundle Laravel Package

Getting Started

Install the bundle with Composer:

composer require smartassert/worker-message-failed-event-bundle

If you are not using Symfony Flex, register it manually in config/bundles.php:

return [
    // ...
    SmartAssert\WorkerMessageFailedEventBundle\WorkerMessageFailedEventBundle::class => ['all' => true],
];

Where to look first

1. README.md in the repository — check the documented event class name and any required config keys.
2. src/ — look for the event subscriber (typically something like WorkerMessageFailedEventSubscriber) that listens to Symfony Messenger's WorkerMessageFailedEvent.
3. src/DependencyInjection/ — confirm whether the bundle exposes configuration or requires services (e.g. an event dispatcher, logger, or event-store client) to be present.

First use case

The bundle bridges Symfony Messenger failures into your application's event system. The minimal workflow is:

1. Dispatch a message onto a Messenger transport.
2. Let it fail (or force failure in a test).
3. Observe the bundle dispatching its own "message failed" event through your event dispatcher.

A quick smoke test:

use Symfony\Component\Messenger\MessageBusInterface;
use Symfony\Component\Messenger\Stamp\TransportNamesStamp;

$bus->dispatch(new SomeMessage(), [new TransportNamesStamp(['async'])]);

Then inspect logs, your event subscriber, or messenger:failed:show to confirm the failure was captured and the bundle's event fired. Start with a throwaway message class that always throws — this isolates the bundle from your domain logic.

Implementation Patterns

Reacting to the dispatched failure event

The bundle's purpose is to turn a Messenger failure into an application event you can subscribe to. Register a listener in your own service config:

namespace App\EventListener;

use SmartAssert\WorkerMessageFailedEventBundle\Event\WorkerMessageFailedEvent; // verify exact FQCN
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;

#[AsEventListener]
final class FailedMessageObserver
{
    public function __invoke(WorkerMessageFailedEvent $event): void
    {
        // route to metrics, incident alerts, dead-letter dashboards, etc.
    }
}

Confirm the concrete event class and its accessors in src/ before coding against it — the package is small and the public surface is whatever the subscriber actually dispatches.

Routing failures into observability

A common production pattern is to treat this as your single funnel for Messenger failures:

• Metrics: increment a counter tagged with the transport and message class.
• Alerting: send to Slack/PagerDuty only when the failure is terminal (not a retry attempt — see gotchas).
• Audit: persist a record of the failed envelope and exception message.

Keep this listener thin and delegate to dedicated services so it stays testable.

Pairing with Symfony's retry strategy

By default Messenger retries messages. The WorkerMessageFailedEvent is thrown on each attempt, so if you want an alert only on final failure, guard on the retry flag:

if ($event->willRetry()) {
    return; // transient failure, a retry is queued
}

(Exact method name depends on the Symfony version and event class exposed by the bundle — check whether it forwards willRetry() from WorkerMessageFailedEvent or wraps it.)

Integrating with the failed transport

The bundle complements, not replaces, Messenger's failure transport. Configure both:

# config/packages/messenger.yaml
framework:
    messenger:
        failure_transport: failed
        transports:
            failed: 'doctrine://default?queue_name=failed'
            async: '%env(MESSENGER_TRANSPORT_DSN)%'

Use the bundle for reactive behavior (events, metrics, alerts) and the failed transport for inspection and replay.

Testing

Point Messenger at the in-memory transport and dispatch a deliberately failing message in a kernel test. Then assert your subscriber was called (for example by injecting an in-memory event dispatcher or a spy service). This is the cheapest way to verify the bundle's wiring survives framework upgrades.

Gotchas and Tips

• Fires on every retry, not just terminal failure. If your listener sends alerts, you will get one per attempt. Always check the retry state before escalating.
• Auto-registration depends on Flex. Without it, a missing config/bundles.php entry means silent no-ops — no error, no events. Verify the bundle is actually loaded with bin/console debug:container --tag=kernel.event_subscriber.
• Subscriber priority matters. If another listener on the same Messenger event stops propagation, this bundle may never see the failure. Check debug:event-dispatcher for ordering, and don't throw from your own failure listener — an exception there can mask the original one.
• Serialization of the failed envelope. If your message carries unserializable state, downstream consumers of the dispatched event may break. Keep the payload you forward small (IDs, class names, exception message) rather than the full envelope.
• Obscure package, zero dependents. Treat it as self-maintained code: pin the version in composer.json, read the subscriber source before upgrades, and be prepared to inline it if the project stalls. The MIT license makes that viable.
• Debugging: use bin/console messenger:failed:show and messenger:failed:retry to inspect the actual failed envelopes the bundle reacted to; enable messenger debug logging to see dispatch order.
• Extension point: if the bundle's default event shape doesn't fit, decorate the event dispatcher or add a higher-priority listener that adapts the event before yours runs, rather than forking the bundle.
• Config quirks: if the bundle requires a specific dispatcher service (e.g. an event-store client), boot will fail or the subscriber will be skipped. Check services.yaml in the bundle's Resources/config to see what it expects to be injected.