Pigeon Laravel Package

Technical Evaluation

Architecture fit

• Pigeon is a Laravel-native AMQP abstraction (dispatch(), queue(), exchange(), routing(), events()). v3.2.0 adds a single opt-in config gate, pigeon.skip_auto_declaration, exposed as PIGEON_SKIP_AUTO_DECLARATION, defaulting to false.
• This aligns the package with infrastructure-as-code environments (Terraform, Helm, RabbitMQ definitions JSON, Operator) where the broker topology is the source of truth and the application should be a pure client. That is the correct direction: it removes an application-side side effect from the hot path.
• The change is narrow and does not alter the public API surface. No new classes, no signature changes, no deprecations.

Integration feasibility

• Zero-code-change adoption for existing installations: default false preserves today's declare-on-first-use behavior, so composer update alone is behaviorally inert.
• The value is only realized by teams that already provision topology externally. For teams relying on Pigeon to self-provision, the flag should remain off.
• Two integration questions must be answered before we plan around it (see below).

Technical risk

• Config-publish drift (highest risk). The release adds a key to the package config file. Applications that previously ran vendor:publish hold a stale config/pigeon.php that lacks the key. If Driver reads config('pigeon.skip_auto_declaration') without a default and then enforces the boolean validation described in the notes, a null could raise the "clear exception" on every existing install after upgrade. If instead it uses config(..., false), this is a non-issue. The release notes do not specify which. This is the single item that could turn a backward-compatible minor into a fleet-wide outage, and it deserves a reproduction test in a scratch app before we approve the bump.
• Env-to-bool coercion. The flag is documented as an env var but validated as a boolean. Laravel's env() returns strings; PIGEON_SKIP_AUTO_DECLARATION=false under a naive (bool) cast becomes true. If the package handles this internally, fine; if the config file is expected to cast it, our published config must be updated alongside. Same class of bug that historically bites QUEUE_CONNECTION-style flags.
• Declare-path coverage gap. The summary states auto-declaration occurs on all five entry points (dispatch, queue, exchange, routing, events), but the guard is described as applied in only three (queue, exchange, routing). This is plausibly correct if dispatch() and events() funnel through routing()/exchange(), but it is unverified. If any path bypasses the guard, the flag becomes a partial switch and our "no broker writes from the app" guarantee is false — which breaks the compliance story we would use to justify adopting it.
• Test depth. Coverage is unit-level (tests/Unit/DriverTest.php) against a mocked or stubbed driver. No integration test asserts the real broker error surface when topology is absent. Acceptable for a config gate, but it means the documented failure mode ("broker error instead of silent creation") is asserted by documentation, not by CI.

Key questions

1. Does the Driver read the config with a false default, and does an absent key (stale published config) behave as false rather than throwing?
2. Is the env value coerced to bool inside the package (filter_var / (bool) on the cast value), and does PIGEON_SKIP_AUTO_DECLARATION=false reliably evaluate false?
3. Do dispatch() and events() reliably route through the guarded queue()/exchange()/routing() methods, or do they issue declarations independently?
4. What broker error codes surface on missing topology (expected 404 NOT_FOUND for missing queue/exchange, 406 PRECONDITION_FAILED for parameter mismatch), and are they distinguishable in logs?
5. Is the declare call currently per-invocation or cached per connection? This determines whether the flag is a comfort feature or a meaningful throughput win.
6. Are there any other behavior changes bundled in this release beyond the typo fix in docs/_coverpage.md?

Integration Approach

Stack fit

• Best fit: Laravel services on RabbitMQ with externally managed topology, particularly where IaC owns queues, exchanges, bindings, DLQs, and policies. Also a fit for read-only broker credentials, where the app is not permitted to declare and currently logs permission errors on first publish.
• Poor fit: single-tenant apps or early-stage services that rely on Pigeon to bootstrap topology; enabling the flag there converts a convenience into a deployment prerequisite with no upside.

Migration path

• No data or schema migration. This is a config-only behavioral switch.
• Recommended path: bump to ^3.2, republish/merge config/pigeon.php to pick up the new key (verify the merge is additive and does not clobber overrides), then leave the flag false everywhere. Enable per environment only after the topology-parity check below passes.

Compatibility

• Semver-minor, default-off, no interface changes. Safe to take in a routine dependency update provided the config-default question is resolved.
• Watch the interaction with php artisan config:cache: the flag is read once at cache time, so flipping the env var requires a cache rebuild. Our runbooks and deployment docs must state this explicitly, or operators will toggle the env var and observe no change.
• No stated minimum PHP/Laravel bump in these notes; confirm the package's composer.json constraints are still satisfied by our current matrix before scheduling.

Sequencing

1. Pre-flight in a scratch app: install 3.2.0 with a stale published config to confirm no exception; then with the env var set to false and true to confirm correct coercion.
2. Confirm guard coverage on dispatch() and events() via a broker packet capture or debug-level log inspection in a non-production environment.
3. Inventory every queue, exchange, and binding the service touches; diff against the IaC-defined topology.
4. Deploy topology changes first, verify broker-side existence, then flip the flag per environment (dev → staging → production canary → fleet).
5. Keep a one-line rollback: set the env var to false, rebuild config cache, redeploy. Rollback is instantaneous and safe.
6. Only after a clean cycle, consider whether to restrict broker credentials to publish/consume-only, which is the real prize here.

Operational Impact

Maintenance

• Low ongoing cost: one config key, one guard method, docs and changelog updated in the same change. The unrelated typo fix in docs/_coverpage.md is a good signal of general hygiene.
• New obligation introduced: topology parity is now an operational invariant rather than a nice-to-have, in any environment where the flag is on. Someone must own that diff.

Support

• Support burden shifts rather than disappears. Today, missing topology self-heals and generates no ticket. With the flag on, the same condition becomes a hard publish/consume failure with a broker-level stack trace. Expect a small spike in "queue not found" pages in the first weeks after enabling.
• Mitigation: add a runbook entry mapping 404 NOT_FOUND / 406 PRECONDITION_FAILED on publish to "check topology deployment," and ensure the IaC pipeline is the documented first responder for that alert.
• First-line triage needs to know the flag exists and where it lives. Without that, an on-call engineer may waste time debugging application code for what is a deployment-ordering problem.

Scaling

• The stated motivation (network-intensive declaration) suggests per-invocation broker round-trips on publish paths. If so, enabling the flag on high-throughput producers removes a channel round-trip from a hot path — a genuine, if modest, throughput and p99 win.
• If declarations are already cached per connection, the benefit is negligible and the case for enabling rests entirely on the IaC/least-privilege argument. Confirm before citing performance in any business case.
• No scaling regressions identified. Behavior is per-process configuration, so horizontal scaling is unaffected.

Failure modes

• Topology drift — highest severity. App publishes to a queue the IaC no longer defines: publish fails hard instead of recreating. Fails closed, which is correct, but the blast radius is the full producer path.
• Deploy ordering — if the application rolls out before the topology change lands, producers fail from first request. Ordering must be enforced in the pipeline, not by convention.
• Config-cache staleness — env var changed but not rebuilt; flag appears to have no effect. Confusing, low severity, easily documented.
• Partial guard coverage — if dispatch()/events() bypass the guard, the app still writes to the broker in a mode we've told compliance is read-only. Low probability, high credibility cost.
• Stale-config exception — per the open question above, the worst case is a post-upgrade boot failure across all instances. This is the one failure mode worth pre-verifying rather than monitoring.

Ramp-up

• Engineering: under an hour to understand — one flag, one behavior change, documented in docs/ADVANCED.md.
• Operations/SRE: roughly half a day, dominated by writing the topology-parity check and the runbook entry, not by the package itself.
• Total cost of adoption is low; the sequencing discipline (topology first, feature flag second) is where the effort actually sits and where a rushed rollout would hurt.