Error Handler Laravel Package

Product Decisions This Supports

Build vs. buy on error handling infrastructure. This component is the answer to "do we write our own error/exception bootstrap for non-HTTP contexts?" It is the maintained, MIT-licensed primitive that Symfony's own framework, FrameworkBundle, and CLI tooling sit on. Buying (adopting) is nearly free; building an equivalent means owning PHP fatal-error parsing, memory-exhaustion handling, and version-by-version compatibility work that only shows up in production incidents.

Roadmap: reliability of background and non-HTTP workloads. Laravel's default error pipeline is HTTP-centric — Illuminate\Foundation\Exceptions\Handler, Ignition, Collision. The gap is in queue workers, scheduled commands, long-running daemons, and scripts, where a raw PHP warning or a silenced @ failure can silently corrupt data instead of throwing. ErrorHandler::call() gives us a scoped, opt-in wrapper to convert those into catchable exceptions for retries and fallbacks on critical flows (payments, file writes, third-party API calls).

Decision: standardize developer-facing debugging for standalone PHP services. Where we run PHP outside a full Laravel app (internal tools, migration scripts, shared libraries, package test harnesses), Debug::enable() gives a well-tested pretty error page and class loader checks instead of each team inventing one.

Roadmap: upgrade readiness and deprecation burn-down. DebugClassLoader surfaces deprecation notices for @method annotations, return-type mismatches, and interface inheritance — a concrete lever for PHP/Symfony/framework major-version upgrades. The 7.3 feature to dump static error pages is directly useful for our edge layer (nginx/CDN-served 500/503 pages) where we currently maintain hand-rolled HTML.

Decision: error page ownership. HtmlErrorRenderer::setTemplate() lets product/design own the generic error page as an artifact rather than an engineering string literal. Small, but it is a brand and trust surface during outages.

Signal to weigh, not ignore: the feed shows 0 dependents and a middling composite score. That is almost certainly a measurement artifact — the component ships inside symfony/symfony and is pulled transitively by framework-bundle, so Composer-level dependents undercount it. Maturity signals that matter here are the release cadence, the long-lived 6.4/7.x/8.x maintenance branches, and the steady stream of bug fixes for PHP 8.5/8.6 quirks. That cadence is the real argument: PHP itself keeps changing how fatal errors are reported, and someone has to track it.

When to Consider This Package

Adopt when most of these hold:

• You have PHP execution paths outside Laravel's HTTP kernel — queue workers, Artisan commands that must fail loudly, cron jobs, daemons, SDKs/shared internal packages — and errors there are currently invisible or inconsistent.
• You need fatal-error and memory-exhaustion handling (shutdown-time capture, getTraceFromString) that the framework layer doesn't give you outside a request.
• You want scoped error-to-exception conversion, not global. ErrorHandler::call() is a surgical tool; that is exactly right for wrapping a risky block without changing app-wide behavior.
• You are planning a PHP or Symfony major upgrade and want deprecation telemetry rather than discovery-by-outage.
• You need static error pages for infrastructure that serves responses when PHP is down.
• You are building a standalone PHP service or library that shouldn't drag in the full framework just to get a decent stack trace.

Look elsewhere, or don't adopt, when:

• The scope is a standard Laravel web app. Ignition + Collision + Handler already cover it; adding a second error handler to the same process is a conflict, not a feature.
• You need production error tracking — grouping, alerting, release tracking, breadcrumbs. That is Sentry/Bugsnag/Rollbar territory. This component renders and formats; it does not aggregate.
• You need PHP < 8.1. Version alignment is strict: Symfony 8.x requires PHP 8.4. Check the matrix before committing; the package's floor becomes your floor.
• Registering it would fight the existing handler. Two set_error_handler registrations is a debugging nightmare — if you adopt, define one owner per process explicitly and document it.
• Your team has no appetite for managing a Symfony-versioned dependency with a predictable-but-nonzero deprecation cadence.

How to Pitch It (Stakeholders)

To executives: A small, free, MIT-licensed building block maintained by the Symfony core team that makes failures in our background jobs and scripts loud and diagnosable instead of silent. The cost is a dependency and a short integration spike; the return is faster incident diagnosis on revenue-critical automated flows and fewer surprises during PHP upgrades. It is not a monitoring product and does not replace our error-tracking vendor — it complements it.

To engineering: This is the error-handling substrate Symfony itself uses. It gives us three things we keep rebuilding badly: a scoped ErrorHandler::call() that forces exceptions even through the @ operator, shutdown-time fatal-error capture that survives memory exhaustion, and DebugClassLoader deprecation reporting that pays for itself at the next major upgrade. In Laravel apps it plugs into non-HTTP contexts only — we are not replacing Handler or Ignition, and we will not register a competing global handler.

To design/product: The generic production error page becomes a reviewable template file instead of an engineering afterthought, and we can export static copies for the edge layer so users still see something coherent when PHP is down.

Recommendation: Adopt narrowly — background workers, CLI tooling, standalone PHP services, and static error pages — behind a documented ownership boundary with Laravel's exception handler. Defer broad adoption until we have a spike validating no handler conflicts and a clear PHP version floor.