Product Decisions This Supports

Build vs. buy: Adopt this package rather than building in-house scaffolding for Laravel API clients when external integrations are a recurring roadmap need. v3.1.1 adds generator support for retry-enabled handlers and HMAC controller stubs, reducing bespoke auth/retry boilerplate.
Feature delivery: Standardize third-party API integrations behind handlers/controllers. Use conditional retry ($when) for selective retries and structured JSON errors for invalid base URIs to improve client-facing API behavior.
Roadmap and platform upgrades: Safe to include in Laravel 12 upgrade planning because the release resolves security audit advisories by allowing Laravel 12. This is a compatibility and security-enablement signal, not a major rewrite.
Operations: passage:list resilience to broken handlers helps teams inventory integrations without command failure. Event subscriber/logging tests support observability decisions.
Use cases: Multiple external services, webhook receivers needing HMAC validation, API clients needing caching/retry/logging, and teams wanting consistent controller/handler patterns.

When to Consider This Package

Consider when the product is Laravel/PHP, has or will have several external HTTP integrations, and needs repeatable patterns for retries, caching, auth (including HMAC), event logging, and handler discovery.
Consider when engineering wants scaffolding (passage:controller --with-retry) to speed delivery and reduce inconsistency across integrations.
Consider when Laravel 12 compatibility and security advisory resolution matter to platform roadmap.
Look elsewhere for a single trivial HTTP call, non-Laravel stacks, or if you already have an API gateway/service mesh that owns retries, auth, caching, and observability.
Look elsewhere if you require vendor-backed SLA/support, complex orchestration (GraphQL/SOAP, BPMN-style flows), or a large plugin ecosystem. v3.1.1 shows active maintenance but remains a focused package; do not assume enterprise support guarantees beyond release notes.

Executive summary: Passage offers a standardized Laravel integration layer that can reduce custom code for external APIs while improving reliability through retries and structured errors, security through HMAC support, and upgrade readiness through Laravel 12 compatibility. Adopt it as an accelerator for multi-integration roadmaps, not as a replacement for an API gateway.
Engineering summary: v3.1.1 is additive and maintenance-focused, not a breaking release. It scaffolds retry-enabled handlers, adds HMAC controller stubs, documents conditional retry callbacks, hardens invalid base URI responses, and makes integration listing resilient. Recommend piloting on one or two integrations, validating retry/caching/observability behavior, then standardizing patterns. Keep an exit plan if integration complexity outgrows the package.