Http Exception Laravel Package

Product Decisions This Supports

• Build vs. buy (buy = adopt): This package is the buy option for "typed exceptions that map to HTTP status codes." At 2 stars, 0 dependents, and a health score of 0.14, it is effectively a reference implementation, not a maintained dependency. The decision it most directly supports is build — the entire surface area is a handful of ~10-line classes and an interface with getStatusCode(), reproducible in-house in under a day.
• Error contract standardization (roadmap): Informs whether to invest in a consistent, typed error taxonomy across API surfaces (domain exception → HTTP status → response envelope), and whether that taxonomy should be framework-agnostic or Laravel-native. The package is a useful specimen of the pattern even if we never install it.
• Architecture boundary decisions: Useful input when deciding whether domain/service layers may raise HTTP-aware exceptions, or whether HTTP mapping belongs strictly in the delivery layer. The package's premise (an exception is an HTTP status) is a real design stance worth accepting or rejecting explicitly.
• Dependency posture / supply-chain policy: A concrete test case for our minimum bar on third-party adoption — maintainer activity, dependent count, PHP version support, security advisories, release cadence. Zero dependents and single-digit stars fail any reasonable threshold, which is itself a decision worth recording.
• Use cases where it is genuinely relevant: framework-agnostic libraries (SDK clients, shared domain packages) that must not pull in symfony/http-kernel; legacy or non-Laravel PHP services that want named exception types without a framework; teams with a convention that prefers explicit classes over abort() or throwing generic HttpException.

When to Consider This Package

Consider it only in a narrow band:

• You need named, typed exception classes for common HTTP codes (400/401/403/404/409/422/500) and you cannot depend on symfony/http-kernel, Symfony, or Laravel.
• You are authoring a library or package that must stay framework-agnostic and wants a conventional, self-documenting exception taxonomy rather than raw integers at call sites.
• You have an existing codebase that already uses this style and you want a drop-in vocabulary rather than inventing names.
• You are evaluating it as a template to copy rather than a runtime dependency — read it, mirror the class list, own the code.

Look elsewhere — or build internally — when:

• You are in a Laravel app. abort(404), Symfony\Component\HttpKernel\Exception\HttpException, NotFoundHttpException, and ValidationException already ship with the framework and are wired into the exception handler, logging, and render() pipeline. Adding a parallel hierarchy creates two error paths and confusion about which one Handler::render() sees.
• You need RFC 7807 / Problem Details responses, validation error shapes, error codes, correlation IDs, or localization. This package does none of that — it only names statuses.
• You need a maintained dependency: recent commits, PHP 8.x compatibility, security advisories, tests in CI. Two stars and zero dependents means no one will notice a breakage but you.
• You need reporting/observability hooks (Sentry grouping, structured logging, alerting on 5xx). Laravel's report()/render() contract expects Throwable; a foreign hierarchy works but gives you nothing extra.
• You want type-level guarantees like enums or backed status codes (enum HttpStatus: int) — a modern PHP 8.1+ approach is shorter and more expressive.

Practical guidance if you do adopt: pin an exact version, composer audit it, read all source first (it is small enough to read fully), and be prepared to vendor/fork it. Assume it is unmaintained.

How to Pitch It (Stakeholders)

For executives (one paragraph): A small open-source library exists that turns HTTP status codes into named exception classes. It is well-intentioned but has essentially no adoption — two GitHub stars, no downstream dependents, and a health score well below our threshold for third-party code. My recommendation is not to adopt it as a dependency. The capability it provides is roughly one file of our own code and is already partially provided by Laravel. This is a low-stakes, zero-cost decision: we take no risk, add no supply-chain surface, and still get the benefit. The real decision is broader — whether we standardize our API error responses — and that is where the effort should go.

For engineering: The pattern is worth adopting; the package is not. Typed exceptions (NotFoundException, ConflictException) make error handling self-documenting and let a single mapper translate domain failures into status codes. But in a Laravel codebase, Symfony\Component\HttpKernel\Exception\HttpException plus abort() already does this and is wired into Handler::render() and report(). Dropping in a second hierarchy gives us two error paths and no owners. Recommendation: spend half a day writing an internal App\Exceptions\Http\* set — or, better on PHP 8.1+, a HttpStatus enum and one HttpException with a status property — register it in bootstrap/app.php / the exception handler, and standardize the response envelope (status, code, message, details) in one place. That gets us the readability win, keeps one error path, and becomes ours to evolve.

Framing for the room: "Same outcome, less risk, similar effort. The package is a good idea with no community behind it — so we'll take the idea and leave the dependency."