Passage Laravel Package

Technical Evaluation

Architecture fit. morcen/passage is a Laravel package for structuring outbound HTTP integrations as discrete, container-resolved "handlers" with a controller interface (PassageControllerInterface), a cache manager, an event subscriber for logging, and artisan tooling (passage:list, passage:controller). That is a strong architectural fit for Laravel estates that accumulate ad-hoc Http:: calls across services and need per-integration auth, caching, retries, and observability. v3.1.1 materially improves the fit: retry-enabled handler scaffolding (--with-retry), an HMAC controller stub, documented $when conditional-retry callbacks, and resilience in passage:list all target the operational gaps that typically block standardization.

Integration feasibility. Composer-installable, config-published, generator-driven — a low-ceremony onboarding path. The most consequential change is PR #81, which resolves security audit advisories by allowing Laravel 12. That removes a hard framework-version blocker for teams on Laravel 12 and is the single item that most affects go/no-go. The remaining changes are additive: new stubs, tests, docblocks, and CI dependency bumps with no runtime impact.

Technical risk.

• Version hygiene: v3.1.1 is a patch release containing feat: commits (HMAC stub, retry scaffolding). Semver-conservative consumers using ~3.1.0 will absorb new code generation behavior without a minor bump. Pin exactly and review generated output.
• Behavior change: invalid base URIs now return structured JSON (PR #71) rather than whatever the prior failure path produced. Any consumer parsing error bodies must be checked.
• Silent resilience: passage:list tolerating broken handlers (PR #74) is good for DX but can mask misconfiguration in CI or dashboards. Pair with explicit health checks.
• Scaffold ≠ implementation: the HMAC stub and retry scaffolding generate starting points, not vetted crypto or backoff policy. Generated defaults must be reviewed before production.
• Contributor concentration: three first-time contributors landed in this release alongside the maintainer. Positive for velocity; review depth and long-term bus factor remain open questions.

Key questions.

1. What is the supported PHP/Laravel matrix after PR #81 — did allowing Laravel 12 drop any older constraint?
2. What are the generated retry defaults (attempts, backoff, jitter) and does $when receive both response and exception?
3. Which HMAC algorithm, signing string, and header conventions does the stub assume, and is clock-skew handling included?
4. Are handlers auto-discovered, and what is the failure mode for duplicate or unresolvable handlers?
5. What is the CI matrix and coverage posture, and who besides the maintainer holds release rights?
6. Is there a circuit-breaker or rate-limit primitive, or only retry?

Integration Approach

Stack fit. Laravel applications already using the framework HTTP client, service container, and config publishing. The package sits alongside — not replaces — Guzzle/Http; handlers are the unit of integration, which maps cleanly to a "one handler per third-party service" ownership model.

Migration path. Greenfield: install and generate. Brownfield: inventory existing outbound calls, then migrate one handler at a time, starting with a read-only, idempotent integration. There is no data migration and no forced refactor; coexistence with existing Http:: usage is expected.

Compatibility. Confirm the resolved PHP and Laravel constraints in composer.json before adopting, specifically that your Laravel version and PHP minor are inside the newly widened range. The dependabot changes in this release are GitHub Actions and metadata tooling only — no runtime dependency risk. Verify your error-handling paths against the new structured-JSON invalid-base-URI response.

Sequencing.

1. Pin ^3.1.1 (or exact) in a non-production branch; run your application test suite.
2. Publish config; define base URIs and allowed client headers explicitly, including mixed-case headers now covered by tests.
3. Generate one handler with passage:controller; validate discovery and passage:list output.
4. Wire PassageEventSubscriber logging into your existing log/alert pipeline.
5. Add --with-retry and a $when callback only for idempotent operations; review generated backoff values.
6. Introduce the HMAC stub for signed APIs, replacing the stub body with your reviewed signing implementation.
7. Establish a team convention doc before broad rollout.

Operational Impact

Maintenance. Actively maintained: dependabot cadence, external contributions, documentation and test investment in this release. The patch-with-features pattern is the main process smell; expect to read changelogs rather than trust semver alone.

Support. Documentation improved meaningfully ($when semantics, @param/@return tags, interface usage example), but HMAC specifics and retry policy semantics remain underspecified relative to their production risk. Internal runbooks will be needed.

Scaling. Handler-per-integration scales well organizationally and keeps blast radius small. Centralized caching and retries reduce duplicate load on downstreams. Retry without jitter or a circuit breaker can amplify incidents during downstream degradation — treat retry configuration as a capacity decision, not a default.

Failure modes. Invalid base URI now fails with structured JSON — better, but confirm your monitoring parses it. Broken handlers are skipped by passage:list, so add a CI assertion that expected handlers are listed. Retries on non-idempotent calls, HMAC clock skew, cache stampede on cold keys, and swallowed handler-resolution errors are the four to instrument first.

Ramp-up. Low for Laravel-fluent engineers: generators and interface conventions cut boilerplate. Estimate one to two days for a developer to ship a first production handler with logging and retry, and roughly one sprint for a team to agree conventions, HMAC implementation, and observability. Adopt with a pinned version and a pilot integration; treat the retry and HMAC scaffolds as review-required starting points rather than finished patterns.