Messenger Bundle Laravel Package

Product Decisions This Supports

• Build vs. buy for event ingestion. This bundle is the "buy" answer to a recurring question: how do we consume Keboola platform events (Connection audit log and application events) without hand-rolling queue plumbing per cloud. Adopting it replaces a bespoke consumer scaffold with a maintained, versioned dependency.
• Cloud-agnostic delivery strategy. One platform setting (aws / azure / gcp) selects the correct serializer, so a single product codebase can ship to SQS/SNS, Event Grid/Service Bus, and Pub/Sub deployments. This directly supports a roadmap decision to run the same service on multiple clouds rather than forking per cloud.
• Feature scoping: push vs. poll. If the roadmap includes reacting to Keboola events in near-real-time (provisioning changes, job outcomes, audit trails), this package is the fastest path to a working consumer. It converts "we need a queue consumer" from a project into a configuration task.
• Roadmap item sizing for new platforms. The extension design makes platform expansion a known, bounded cost: one enum case, one serializer, one branch in the extension. That is a defensible estimate for "add support for cloud X," and it tells you the marginal cost of each new cloud is small once the pattern is in place.
• Schema-evolution policy. The event-factory pattern (typed class per known event, generic fallback for unknown ones) is a product decision you can make explicitly: do we want consumers to fail loudly on unrecognized events, or degrade gracefully? Choosing the generic fallback buys resilience but trades away alerting on upstream schema drift — worth deciding deliberately rather than inheriting.
• Operational safety defaults. The GPS transport decorator injects REST and connect timeouts because otherwise a consumer blocks forever on a dead connection. This is the kind of default that removes an entire class of production incident from your backlog.
• Onboarding and support cost. The README documents DSN formats per platform, Terraform-based local setup, and a procedure for reverse-engineering events off a real queue. That is a real reduction in time-to-first-consumer for new engineers, and it is a factor in staffing and ramp-up planning.

When to Consider This Package

Adopt when:

• You are building a service that consumes Keboola platform events — specifically Connection connection/audit-log and application events — and you want that work to be configuration rather than architecture.
• You deploy to more than one cloud, or expect to. The single-switch platform model is the core value; on a single fixed cloud the benefit shrinks to "someone else maintains the serializer."
• You already run Symfony with Messenger, or are willing to. This bundle preconfigures Messenger transports; it does not replace it.
• You want the "installed but inactive" posture — with platform unset the extension returns early and registers nothing, so the dependency can be added to a shared codebase ahead of the feature that uses it.
• You can live with the contribution model: this repository is a read-only mirror, so any fix or feature you need must be raised against the keboola/platform-libraries monorepo, and your release cadence is coupled to that monorepo's green builds.

Look elsewhere when:

• You are not on the Keboola platform. The serializers unwrap Keboola's specific envelope shapes; the event factories map Keboola's event names. Retargeting this at another vendor's events means writing your own serializers and factories — at which point you are using it as a pattern reference, not a dependency.
• You need vendor support, an SLA, or community validation. Zero stars, zero dependents, and a mirror-only publication mean there is no external user base to lean on and no commercial backing. Treat it as an internal library that happens to be installable.
• You need to switch platforms at runtime, per-tenant or per-request. Platform resolves at container-build time and transport config is injected during prependExtension(); this is a deploy-time decision, not a runtime one.
• Your environment is serverless or short-lived. Long-running queue workers are the assumed shape.
• You need advanced Messenger capabilities — bespoke retry/backoff, dead-letter handling, routing topologies, middleware. This bundle configures transports and serialization; those remain your engineering work, and you should budget for it rather than assume it is included.
• Your CI cannot provision real cloud queues. The queue-consumption tests require actual AWS/Azure/GCP queues via the provisioning/ Terraform setup. If you intend to fork or extend, account for that infrastructure cost; the offline suite does not cover the paths you would be changing.

Two footguns to flag before committing:

• Setting client_config explicitly in transport options or the DSN disables the default timeouts entirely rather than merging with them. Anyone overriding it takes on the blocking-forever risk the decorator exists to prevent.
• Promoting an event from the generic fallback to a typed class is a behaviour change for any handler that matches on type. That is a coordinated release concern, not a drop-in refactor.

How to Pitch It (Stakeholders)

To executives: This is a small, MIT-licensed Symfony bundle that lets our services consume Keboola platform events from any of the three major clouds by changing one configuration value instead of writing cloud-specific integration code. It ships with sensible production defaults — notably connection timeouts that prevent a dead queue from hanging a worker indefinitely — and it is inert until we explicitly enable it, so it can be adopted incrementally with no risk to existing deployments. The strategic value is that our multi-cloud roadmap stops requiring a per-cloud integration effort. The honest caveats: it is an internal Keboola library published only for package installation, with no external user base and no support contract; fixes route through Keboola's monorepo rather than a repository we can merge into; and it handles event consumption, not the broader concerns of retry policy, dead-lettering, or observability, which remain our work.

To engineering: Adopt it as the transport and serialization layer for Keboola event consumption. Configuration happens at container-build time via prependExtension(), so platform is a deploy-time decision and environment placeholders are resolved early — do not expect per-tenant switching. The platform enum is the single switch; with it unset the bundle registers nothing. Incoming events always arrive as an EventInterface through the audit-log or application-event factories, with unknown names falling back to generic classes — design your handlers accordingly, and note that adding a typed class for a previously-generic event is a breaking change for type-matching handlers. If you need to contribute, open PRs against keboola/platform-libraries under libs/messenger-bundle/; PRs against the mirror will be closed. Be aware that the queue-consumption tests need real provisioned cloud queues, and that overriding client_config silently drops the default REST and connect timeouts rather than merging with them.