Http Status Code Laravel Package

Product Decisions This Supports

• Which HTTP-status convention wins project-wide. The package is ~10 lines of backed enum; the actual product decision is whether status codes become one named, greppable vocabulary across controllers, exception handlers, and public API surfaces — or stay as hand-rolled integers per team. This package is a cheap forcing function for that decision, not the decision itself.
• Build vs. buy (where "buy" is nearly free). MIT-licensed, single class, no service provider, no config, no container binding — adoption cost is one composer require and a ^3.0 constraint. But the outcome is equally reachable by copying the enum internally or standardizing on Laravel/Symfony's Response::HTTP_*. Frame the decision as convention selection, not vendor selection; mixing conventions is worse than either choice.
• Public API contract and error-taxonomy work. Directly supports initiatives where the response contract is user-facing: OpenAPI alignment, consistent 400-vs-422 discipline, idempotency/retry documentation, versioned API surfaces, partner SDKs. The enum becomes the contract; the exception handler becomes generic and unit-testable without booting the framework.
• Roadmap placement: enabler, not a line item. It belongs inside an API-standardization, SDK, or platform-conventions epic. Do not schedule it as a deliverable. With 49 stars, zero dependents, and maintenance-level activity (latest release 3.0.2, 2022-10-19, described only as "minor improvements"), it is table stakes that should not consume planning cycles.
• Developer experience and onboarding. Named cases (UNPROCESSABLE_ENTITY, IM_A_TEAPOT) cut review time spent decoding numbers and give static analysis something to check. A real but small productivity signal — use it to justify convention work, not headcount.
• Technical-debt triage. If a codebase is littered with integer literals, this package quantifies the cleanup: one import surface, one sweep of PRs, a measurable drop in inconsistent status codes. If the codebase already uses framework constants consistently, "no action" is a valid and defensible PM outcome.

When to Consider This Package

Adopt it when:

• You are on PHP 8.1+ and want a backed enum rather than loose integers. The 3.x line is the enum line — constrain to ^3.0 and treat 1.x → 2.x → 3.x as the only upgrade events worth reviewing.
• You maintain framework-agnostic PHP libraries, SDKs, or shared packages, where pulling in Laravel or Symfony just for constants creates unwanted coupling.
• Multiple teams or services need one import surface and nobody owns an internal status-code standard yet.
• You want match support, type hints, and validation in a small, reversible, low-blast-radius change.
• You have a convention gap to close cheaply, and a credible external artifact accelerates the conversation even if you later inline the enum under MIT.

Look elsewhere, or copy the enum internally, when:

• You are on Laravel or Symfony. symfony/http-foundation already ships Response::HTTP_*. A reviewer will reasonably ask why a constants list is a Composer dependency. This is the default answer for most Laravel shops and the decision is reversible in an afternoon.
• Supply-chain or bus-factor review is non-trivial. 49 stars, zero dependents, single maintainer, last release 2022-10-19. 3.0.2 is a positive "not abandoned" signal, but it is one minor patch after a long quiet period — characterize as maintained, low-activity, never actively developed. Fork/attestation overhead exceeds the value of a constants list.
• You need behavior, not names. No middleware, no exception renderer, no RFC 7807 problem-details responses, no localized reason phrases, no config, no facade. If that is the ask, this is the wrong tool.
• You need application-specific codes (499/599, vendor extensions, Retry-After companions). Backed enums cannot be extended — you must wrap, and at that point you own a class anyway.
• You need business-semantic guidance — retryability, idempotency, client-error taxonomy. That is a design document, not a constants class.

How to Pitch It (Stakeholders)

Executives (one paragraph, no procurement): This is a tiny, MIT-licensed convenience library that gives our PHP services a single, named vocabulary for HTTP status codes. Cost is effectively zero, runtime risk is negligible, and it removes a recurring class of inconsistency bugs in API responses and error contracts. The honest caveats: Laravel and Symfony already ship equivalent constants, the same result is achievable with roughly 50 lines of internal code, and the project is low-activity — 49 stars, zero downstream dependents, and a latest release (3.0.2) that is a minor patch with no new capability. Recommendation: delegate to engineering as a developer-convenience choice inside an API-conventions effort; no vendor review, no budget line, no roadmap slot. The decision is reversible in an afternoon, which is precisely why it should not consume planning cycles.

Engineering (the working brief): It is an enum of HTTP status codes with IANA-style case names — typed, autocompletable, static-analysis friendly, framework-agnostic, no service provider, no config, no container binding. Three integration patterns pay off: (1) enum cases at the response boundary in controllers; (2) a statusMap array in the exception handler mapping domain exceptions to cases; (3) a status(): HttpStatusCode method on domain exceptions so they are self-describing and testable without the framework. Guardrails: it is an enum, not an int — response()->json() and === comparisons need ->value, so run PHPStan/Larastan at a reasonable level; use tryFrom() and branch on null for dynamic codes, never from(), which turns bad input into a 500; reason phrases are English and not localised, so keep user-facing copy in lang files; and pick this enum or Response::HTTP_* project-wide — don't mix.