Download the PHP package hradigital/php-exceptions-laravel without Composer

php-exceptions-laravel

Laravel wiring and JSON / web renderers for the hradigital/php-exceptions domain exception tree.

The base library ships platform-agnostic exceptions - AbstractBaseException and the Client/ and Server/ trees, aligned with HTTP 4xx/5xx semantics - and knows nothing about a transport, leaving every application to decide again how a thrown domain exception becomes a response.

This package decides it once. API requests get a uniform JSON body; web requests throwing a 422 land back on the originating form with errors and old input; every other package exception is answered on the web with the HTTP status it declares. An exception that does not extend AbstractBaseException falls through to Laravel's own handler, untouched.

• ExceptionRenderer - the JSON strategy dispatcher, resolving an exception to the first strategy that supports it, with an always-matching fallback.
• WebRenderer - the web strategy dispatcher, resolving an exception to the first strategy that supports it, with an always-matching fallback.
• ExceptionsServiceProvider - auto-discovered, binding both dispatchers as singletons and registering two renderable() hooks on Laravel's exception handler.
• API detection - one shared rule across both hooks: the Accept header, a JSON body, an api/* path, or an api.* route name.
• Bundled strategies - DefaultRenderer and InputFailureRenderer for JSON, InputFailureWebRenderer, UnprocessableEntityWebRenderer and DefaultWebRenderer for the web.
• Custom strategies - resolve the singleton and prepend your own; the last registration wins.

Requirements

Laravel 13 itself requires PHP ^8.3, so PHP 8.2 is supported on the Laravel 12 line only.

Installation

Registration

The service provider is auto-discovered — no manual registration needed in most apps. If auto-discovery is disabled for this package, register it explicitly:

bootstrap/providers.php:

What the provider does

On boot(), the provider:

1. Binds ExceptionRenderer and WebRenderer as singletons in the container (so app code can resolve them and add custom strategies).
2. Registers two renderable() hooks on Laravel's exception handler — one for API requests (returns JsonResponse), one for web requests (returns Response).

Both hooks are type-hinted AbstractBaseException, so Laravel dispatches them for every exception in this package and every application subclass of one, and for nothing else. No configuration, no publishing step and no application wiring is involved — the provider is auto-discovered through extra.laravel.providers.

API detection is shared between both hooks:

• The JSON hook runs only for API requests; for web requests it returns null.
• The web hook runs only for non-API requests, and answers every AbstractBaseException. UnprocessableEntityException and its RequestFailureException specialisation redirect back to the form; everything else is rendered by DefaultWebRenderer with the status the exception declares. An exception from outside this package never reaches the hook, so Laravel's default handler keeps rendering its usual HTML / Whoops / Blade error pages for those.

Response shapes

Default

Any AbstractBaseException rendered via DefaultRenderer:

data is omitted when the exception was raised without structured payload (hasData() === false).

Input / validation failures

Exceptions implementing HraDigital\Components\Exceptions\Client\Request\RequestFailureInterface are rendered via InputFailureRenderer:

rules mirrors getFailures() (the field-keyed rule list). failed is the flattened, per-message list derived from getFailedMessages() — one entry per {fieldName, message} pair, preserving field order.

Web responses

For non-API requests the WebRenderer runs its strategies in order, then falls back:

The fallback is what keeps a 401, 403, 404, 409 or 429 from rendering as a 500. Laravel reads no HTTP status off a DomainException, so without it any exception no strategy claimed reached the framework's generic handler and lost its status. An exception declaring no code, or a code outside 400-599, is answered 500.

This means:

• Forms throwing RequestFailureException::withFailures([...], [...]) get per-field errors flashed under the default MessageBag — Blade @error('field') / $errors->has('field') work out of the box.
• Plain UnprocessableEntityException('the field is invalid') flashes a single error key — render it in the layout via @if (session('error')) ... @endif.
• Submitted input is always flashed via withInput() so old('field') works in the form.

Adding a custom renderer strategy

Resolve the singleton and prepend a strategy. The first strategy whose supports() returns true wins; the bundled DefaultRenderer is the always-matching fallback.

add() always prepends, so later registrations override earlier ones.

Public API

Local development

A Makefile wraps the same tools with scoping and a silent-on-success mode — run make help for the full list:

Any target accepts QUIET=1, which suppresses all output on success (the test target prints only its final summary) and prints everything on failure. FILES="a.php b.php" scopes the file-based gates, FILTER=SomeTest narrows the test run, and EXEC="docker exec <name>" runs the PHP tools inside a container instead of natively.

Note that the Makefile follows the machine-wide target naming, which differs from the Composer scripts: make lint is PHPCS, whereas composer lint is the php -l syntax pass (make syntax).

Continuous Integration

.github/workflows/ci.yml runs on every push and PR to master. It executes lint → phpcs → phpstan → phpunit against the supported PHP × Laravel matrix:

Laravel 13 requires PHP ^8.3, so it has no 8.2 cell. Each Laravel line is paired with its own Testbench major — Laravel 12 with orchestra/testbench 10.*, Laravel 13 with 11.*.

The workflow pins illuminate/* and orchestra/testbench per matrix cell with composer require --no-update before installing.

Laravel 10 and 11 were dropped: both branches are past security support, so every laravel/framework release in them carries open security advisories and Composer refuses to install them.

Testing

The tests/ suite covers every class in the package:

• ExceptionRendererTest — factory wiring, fallback path, strategy routing, prepend ordering, custom-constructor wiring.
• Renderers/DefaultRendererTest — status/message/code mapping, conditional data key.
• Renderers/InputFailureRendererTest — flattening of failed, rules mirroring, empty-payload behaviour.
• WebRendererTest — default strategy wiring, fallback to DefaultWebRenderer, prepend ordering for custom strategies.
• Renderers/DefaultWebRendererTest — the status per exception family, the 500 fallback for a non-error code, and the message body.
• Renderers/InputFailureWebRendererTest — back-with-errors flash + old-input restoration.
• Renderers/UnprocessableEntityWebRendererTest — back-with-error flash, withInput, subclass support.
• ExceptionsServiceProviderTest — Testbench-based: singleton bindings, end-to-end JSON rendering for api/* requests, end-to-end redirect rendering for web routes throwing UnprocessableEntityException, end-to-end status rendering for a web route throwing a 403, proof that an exception outside the package still renders through the framework, and direct callback invocation proving each hook returns null outside its scope.
• Support/Stubs — shared anonymous-class factories for a generic exception and a RequestFailureInterface exception, excluded from the test suite.

License

Mozilla Public License 2.0 - see LICENSE. This matches the upstream hradigital/php-exceptions license.

You may use this package in closed-source and commercial products. If you modify and distribute the package's own files, those files must remain under the MPL-2.0.

The HRADigital name and package names are not covered by that licence - see TRADEMARK.md.