Pigeon Laravel Package

Product Decisions This Supports

• Infrastructure ownership model (build vs. buy vs. platform-team-owned): PIGEON_SKIP_AUTO_DECLARATION turns a hidden runtime side effect into an explicit architectural choice. Teams can now decide who owns AMQP topology — the application (default, zero-config, developer-friendly) or the platform/IaC layer (Terraform, CloudFormation, Helm charts, broker operator). This is a roadmap-relevant decision, not just a config flag.
• Production hardening / go-live readiness: Auto-declaration is convenient in dev but risky in regulated or multi-tenant production environments. This release gives you a documented, tested switch to disable implicit broker mutations — useful for security review, change-management approval, and audit requirements where "the app silently created a queue" is a finding.
• Performance and cost decisions: Auto-declaration is network-intensive on every dispatch(), queue(), exchange(), routing() or events() call. Turning it off reduces round-trips per publish and can materially cut broker connection overhead and latency on high-throughput paths — a lever for scaling conversations without re-architecting.
• Environment parity strategy: You can keep auto-declaration true locally/CI and false… rather, true for convenience and set PIGEON_SKIP_AUTO_DECLARATION=true in staging/production where topology is pre-provisioned. One codebase, per-environment behavior, configured purely via .env.
• Use cases it unlocks: Multi-tenant SaaS with per-tenant vhosts provisioned by an operator; regulated fintech/health workloads requiring immutable topology; teams migrating to managed RabbitMQ (Amazon MQ, CloudAMQP) where broker permissions are locked down and apps are denied queue.declare / exchange.declare.
• Risk/effort signal for roadmap planning: This is an opt-in, backward-compatible, default-off change. Low adoption cost, no migration work, no breaking change — it can be scheduled as a routine dependency bump rather than a dedicated epic.

When to Consider This Package

Adopt when:

• You are on Laravel and need first-class RabbitMQ/AMQP messaging without hand-rolling php-amqplib wiring — publishing, consuming, queue/exchange/routing binding, and event integration are already abstracted.
• You want a Laravel-native DX (config file + .env, facades/fluent API, Artisan-driven consumers) rather than a generic PHP AMQP client.
• You need a pragmatic topology story: auto-declaration by default for fast local development, with the new PIGEON_SKIP_AUTO_DECLARATION escape hatch for environments where infrastructure-as-code owns the broker.
• Your ops model is either "app owns topology" (leave default) or "platform owns topology" (set the flag). Both are now supported without forking or patching.
• You are standardizing messaging across multiple Laravel services and want a consistent publish/consume surface.

Look elsewhere / proceed with caution when:

• You need a full-featured message-bus abstraction with first-class support for multiple transports (SQS, Redis, Kafka) behind one API — Laravel's own queue system plus a driver, or a dedicated bus library, may fit better.
• You require advanced AMQP features that a thin wrapper may not expose (complex dead-letter topologies, quorum queues, publisher confirms semantics, stream queues) — verify coverage against your requirements.
• You want declarative topology managed by the app in code (a "migrations for queues" model). Pigeon's model is implicit-by-default or external-IaC; there is no formal topology-as-code DSL here.
• Critical caveat with the new flag: with PIGEON_SKIP_AUTO_DECLARATION=true, publishing or consuming against a missing queue/exchange raises a broker error rather than being silently created. This shifts a class of failures from "silently self-healing" to "loud and immediate." That is usually desirable in production, but it means your deploy pipeline must guarantee topology exists before the app starts; otherwise you trade a network cost for a 404-style outage at first message. Pair the flag with a deployment-order/health-check decision.
• Your team relies on the current implicit behavior in production and has no IaC coverage — flipping the flag prematurely is a self-inflicted incident.

How to Pitch It (Stakeholders)

To executives (one paragraph): Pigeon v3.2.0 ships a single, low-risk configuration flag, PIGEON_SKIP_AUTO_DECLARATION, that lets applications stop silently creating RabbitMQ queues and exchanges on the fly and instead connect to topology provisioned by our infrastructure pipeline. It is off by default and fully backward compatible — nothing changes unless we opt in. For us it is a governance and efficiency lever: it aligns messaging with infrastructure-as-code, removes an implicit broker-modification behavior that security and audit reviews tend to flag, and reduces per-message network chatter in high-volume paths. No migration, no rewrite, no downtime — a config line and a deploy-order check.

To engineering:

• New config pigeon.skip_auto_declaration backed by PIGEON_SKIP_AUTO_DECLARATION (default false, so a no-op upgrade).
• When enabled, the Driver's skipAutoDeclaration() guard suppresses queueDeclare() / exchange_declare() inside queue(), exchange(), and routing(); the value is validated as a boolean with a clear exception on misconfiguration.
• Behavioral contract: missing topology now surfaces as a broker error instead of being auto-created. Rollout must sequence topology provisioning (IaC apply) before the app deploy, and we should add a startup/health assertion or smoke test that the expected queues and exchanges exist.
• Docs updated (docs/ADVANCED.md "Skipping Auto Declaration", docs/INSTALLATION.md), changelog entry under Unreleased, and unit coverage in tests/Unit/DriverTest.php for both the skip path and the boolean-validation error.
• Recommended rollout: (1) land the dependency bump with the flag unset; (2) confirm IaC fully covers topology in staging; (3) enable in staging and run a publish/consume smoke test; (4) enable in production during a low-traffic window with rollback = unset the env var.
• Ask: a short spike to inventory every queue/exchange/routing key Pigeon currently auto-creates in production, so the IaC coverage gap is known before we flip the switch.