Messenger Bundle Laravel Package

Getting Started

Install the bundle through Composer, then activate it by giving it a platform:

composer require keboola/messenger-bundle

# config/packages/keboola_messenger.yaml
keboola_messenger:
    platform: aws        # aws | azure | gcp
    # connection DSN / options per the README

The single required decision is platform. That enum (aws / azure / gcp) is the only switch the bundle exposes publicly — it selects which serializer is bound to the connection-event and audit-log transports. Leave platform unset and the bundle registers nothing: that is the supported "installed but inactive" state, useful in libraries that ship the bundle but only enable it in a consumer app.

Where to look first:

1. The README — it is the real reference: per-platform DSN formats, Terraform-backed local setup, and a procedure for reverse-engineering events off a real queue. Read the DSN section for your platform before touching Symfony Messenger config.
2. ConnectionEvent\ApplicationEvent\ApplicationEventFactory and ConnectionEvent\AuditLog\AuditEventFactory — they define what event objects a handler will actually receive.
3. Transport\GpsTransportFactoryDecorator if you plan to use gps:// transports.

A good first use case: consume an application event (application-event transport) from your platform queue and log it, then swap in the audit-log transport. Both share the serializer machinery, so getting one working proves the configuration.

Implementation Patterns

Handlers are plain Symfony Messenger handlers. Bind against EventInterface (or a concrete typed event) and let the factories do the mapping:

final class AuditLogHandler
{
    public function __invoke(\Keboola\MessengerBundle\ConnectionEvent\EventInterface $event): void
    {
        // ...
    }
}

Prefer matching on concrete event classes, not on instanceof of the interface. The factories map known event names to typed classes and fall back to GenericAuditLogEvent / GenericApplicationEvent for anything unrecognized. If you want a handler to fire for a specific event, declare that class in the parameter type. Handlers typed to the generic class will silently start receiving less once a typed class exists — see Gotchas.

Routing is normal Messenger routing. The bundle prepends transport definitions into framework.messenger in prependExtension(), so framework.messenger.routing refers to the transport names the bundle creates (connection-event, audit-log, application-event, plus your own). You do not declare those transports yourself; you only wire messages to them.

Use gps:// only if you understand the timeout defaults. GpsTransportFactoryDecorator injects restOptions.timeout: 120 and connect_timeout: 10 so a dead connection doesn't block a consumer forever. If you need different values, set client_config explicitly — but see the gotcha below.

Integration tips:

• Run consumers under a supervisor (Symfony's messenger:consume in a worker or a Kubernetes job), since a Keboola queue is long-lived.
• Keep handlers idempotent. Cloud-queue delivery semantics mean redelivery is expected.
• Treat the bundle as infrastructure: your application code should only know about EventInterface and typed events, never about SQS/SNS/Pub/Sub envelope shapes.

Gotchas and Tips

platform must resolve at container build time. The extension does its work in prependExtension() and calls resolveEnvPlaceholders(..., true) explicitly. That means an env var driving platform has to be set when the container is compiled, not merely at runtime. In Docker/CI, bake the platform into the build stage or you will get an inactive bundle by surprise.

Setting client_config disables the GPS timeout defaults entirely. The decorator's defaults are not merged with your value — the presence of client_config (in transport options or DSN query) replaces them. If you set it for one thing, you must set the timeouts too, or a consumer can block indefinitely on a dead connection.

Unknown events do not fail. The factories always return an EventInterface, falling back to the generic classes. This is a feature (no consumer crashes on a new event name), but it means "my handler never fires" is usually a routing or type-mismatch problem, not a missing event. Adding a typed class for a name that previously fell through is a behavioural change for any handler matching the generic class — audit your handlers before upgrading.

This repo is a read-only mirror. Do not open PRs or commit against keboola/messenger-bundle. Changes go to keboola/platform-libraries under libs/messenger-bundle/; mirror commits are force-overwritten. For day-to-day use this mostly matters when you file a bug or want to extend a serializer — you need to file against the monorepo.

Debugging DI failures: a stale var/cache is the usual cause of confusing container errors when changing platform config or transports. Clear the cache before chasing anything deeper.

Testing: the serializers are unit-testable offline (phpunit --filter testSerializer tests/ConnectionEvent/Serializer in the bundle repo), but the consumption tests for SQS / Azure Service Bus / Pub/Sub require real cloud queues provisioned via the bundle's provisioning/ Terraform. Plan for at least one integration environment where you can exercise a real queue; mock the serializers for the rest.

PHPStan is selected by APP_ENV in the bundle repo (phpstan-${APP_ENV}.neon), so if you clone it and APP_ENV is unset, composer phpstan fails with a missing-config error. Not a problem for consumers, but it will bite anyone reproducing a bug in the mirror or the monorepo.