Status Code Laravel Package

Technical Evaluation

Architecture fit. teapot/status-code is a micro-utility, not a framework component: it encapsulates HTTP status codes (numeric value plus reason phrase) as PHP constants or enum cases. Architecturally it is a leaf dependency with no transitive surface — it does not touch routing, middleware, PSR-7 messages, or the HTTP kernel. That makes it a near-zero-friction fit for any Laravel codebase that currently passes raw integers (return response()->json($payload, 422)) or scatters magic numbers through controllers, form requests, and API resources. It is a readability and type-safety affordance, not a capability addition.

Integration feasibility. High. For a Laravel app the realistic integration points are: (1) controller and JsonResponse return paths, (2) custom exception handlers in bootstrap/app.php / Handler::render(), (3) API Resources and Responsable objects, and (4) test assertions. All of these accept an integer today, so adoption is additive and reversible — the enum/constant can be unwrapped at the boundary, meaning no architectural commitment is created. There is no service provider, no config publish, no migration, and no runtime hook. Composer install plus a lint rule is the entire onboarding cost.

Technical risk. Low but non-zero, concentrated in three areas:

• Duplication of first-party surface. Laravel already ships Symfony\Component\HttpFoundation\Response::HTTP_* constants, and fig/http-message-util covers the PSR-7 world. Adopting a 45-star package for the same data creates a second vocabulary for the same concept — a genuine consistency risk in code review, not a runtime one.
• Maintenance concentration. 45 stars and 0 dependents is the headline concern. That is not a signal of quality; it is a signal of bus factor. A single maintainer stepping away means the package goes stale against PHP minor releases with nobody to notice.
• PHP version coupling. If the package ships enum cases (likely, given the 2025 release cadence), it imposes a PHP 8.1+ floor and any consuming code that type-hints the enum becomes non-trivially portable. Confirm the minimum PHP constraint against the oldest runtime in the fleet before adopting in shared libraries.

None of these are correctness risks. All are governance risks, and all are cheap to mitigate given the package's size.

Key questions for the maintainer/owner.

1. Does it expose a backed enum, plain class constants, or both — and is a stable API contract documented?
2. Are reason phrases included, or numeric codes only? Reason phrases are where hand-rolled constants usually diverge from the RFC/IANA registry.
3. What is the declared PHP constraint, and is there a CI matrix proving it against current PHP releases?
4. How does it track IANA registry updates (e.g., 103 Early Hints, 425 Too Early, 451)?
5. Is there a stated policy on semantic versioning and deprecation for enum case renames?

Integration Approach

Stack fit. Compatible with any Laravel 9+ / PHP 8.1+ application (verify the exact floor). It has no opinion on Laravel version, no facade, and no container bindings, so it will not collide with framework upgrades. The only real decision is where the boundary sits: adopt it strictly in the HTTP/adapter layer (controllers, exception renderers, resources) and never let the enum leak into domain or service-layer signatures. That preserves the option to remove the dependency in an afternoon.

Migration path. Three sequenced, independently shippable steps:

1. Pin and prove. Add the dependency, write a single test asserting the mapping between the package's codes and Symfony Response::HTTP_* for the subset actually used. This catches reason-phrase drift and gives a mechanical removal trigger later.
2. Choke point first. Introduce the package in the exception handler and the base API controller only. This captures the majority of status emissions with a handful of edits and avoids a broad, low-value sweep.
3. Opportunistic cleanup. Convert remaining magic integers as files are touched for other reasons. Do not run a codebase-wide refactor for this; the value does not justify the diff noise or the review load.

Compatibility and sequencing. No database, cache, queue, or config surface — so no deploy ordering constraints and no rollback ceremony beyond reverting a commit. The one sequencing rule: land the equivalence test (step 1) before any call-site changes, so a future package swap or abandonment is a one-line verification rather than an audit. If the team already standardizes on Symfony constants, the correct decision may be to not adopt and instead add a PHPStan/ Pint rule banning bare status integers — a strictly lower-risk path to the same outcome.

Operational Impact

Maintenance. Negligible runtime footprint; no configuration, no migrations, no scheduled work. The real maintenance is version hygiene: a dependency-update bot plus the equivalence test is sufficient. Budget effectively zero engineering hours per quarter.

Support. No vendor relationship and no commercial backing. Support model is "read the source" — which is feasible here, since the package is small enough to audit in full before adoption. Recommend a 30-minute read-through of the tagged release as the acceptance gate rather than relying on the star count.

Scaling. Irrelevant in the horizontal sense — no I/O, no state, no allocation beyond enum/constant resolution. There is no performance consideration at any realistic request volume. The only "scale" concern is organizational: as headcount grows, divergent conventions (some code using Symfony constants, some using this package, some using ints) become a review-time tax. Codify the choice in the style guide or drop the dependency.

Failure modes. Ranked by likelihood:

• Abandonment / stale PHP support (most likely): package stops receiving releases, blocks or complicates a future PHP upgrade. Mitigation: the equivalence test plus a documented two-hour in-house replacement (the package is a data table; a fork or a local enum is trivial).
• Convention drift (likely): mixed usage across the codebase, marginalizing the benefit. Mitigation: enforce via static analysis, not documentation alone.
• Enum/constant API break in a minor release (unlikely): consuming type hints break at autoload time — a loud, immediate failure, not a silent one. Mitigation: conservative version pinning.
• Reason-phrase mismatch with client-facing output (low): only matters if the phrase is serialized into responses; keep reason phrases out of the API contract.

Ramp-up. Effectively zero for any PHP developer — there is nothing to learn beyond the enum case names. Onboarding cost is a single line in the contributing guide. The decision cost dominates the implementation cost.

TPM recommendation. Approve as a low-stakes, reversible convenience dependency for application code, contingent on the equivalence test and a static-analysis rule pinning usage to one convention. Do not adopt it in shared internal libraries or packages, where the zero-dependent, single-maintainer profile is a poor trade against simply declaring the enum locally. If the team's existing Symfony-constant convention is already consistent, the higher-value move is enforcing that convention rather than adding a second vocabulary.