PHPackages                             maduser/argon-error - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. maduser/argon-error

ActiveLibrary[Logging & Monitoring](/categories/logging)

maduser/argon-error
===================

Exception policy and error response handling for the Argon runtime stack.

v1.0.0(2mo ago)0272MITPHP

Since May 24Pushed 2mo agoCompare

[ Source](https://github.com/judus/argon-error)[ Packagist](https://packagist.org/packages/maduser/argon-error)[ RSS](/packages/maduser-argon-error/feed)WikiDiscussions main Synced 3w ago

READMEChangelogDependencies (10)Versions (3)Used By (2)

Argon Error
===========

[](#argon-error)

[![PHP](https://camo.githubusercontent.com/ce3e396e4f1bbbd326f628872a1414656d28065f2712cda0868d8eff07320aec/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d382e322b2d626c7565)](https://www.php.net/)[![Build](https://github.com/judus/argon-error/actions/workflows/php.yml/badge.svg)](https://github.com/judus/argon-error/actions)[![codecov](https://camo.githubusercontent.com/37e9ad1184f09bf4c2225aac8435fc4e51be560fd5065e0be11695bbcded5118/68747470733a2f2f636f6465636f762e696f2f67682f6a756475732f6172676f6e2d6572726f722f6272616e63682f6d61737465722f67726170682f62616467652e737667)](https://codecov.io/gh/judus/argon-error)[![Psalm Level](https://camo.githubusercontent.com/712d209f616f7960a5720f5999dd73f8d71b29a0bc439a65a5cff5777542addd/68747470733a2f2f73686570686572642e6465762f6769746875622f6a756475732f6172676f6e2d6572726f722f636f7665726167652e737667)](https://shepherd.dev/github/judus/argon-error)[![Latest Version](https://camo.githubusercontent.com/eeb5c4b6dc003feb00dafda14655b17d890332dfd80ec88ffa1c534a129a5bd5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d6164757365722f6172676f6e2d6572726f722e737667)](https://packagist.org/packages/maduser/argon-error)[![Downloads](https://camo.githubusercontent.com/21802e47228464cbe31306b7c550cf584e0368638b9a80c8465a8eefe7556441/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d6164757365722f6172676f6e2d6572726f722e737667)](https://packagist.org/packages/maduser/argon-error)[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)

`maduser/argon-error` is the HTTP error-handling layer for Argon applications. It turns uncaught throwables into PSR-7 responses, lets applications register exception-specific reporting and rendering policies, and integrates with the shared Argon runtime error-handler contract.

The package stays intentionally small:

- `ErrorHandler` bridges Argon runtime failures to the dispatcher/formatter stack.
- `ExceptionDispatcher` runs registered exception policies before falling back to the formatter.
- `ExceptionFormatter` creates JSON or plain-text PSR-7 responses.
- `ErrorHandlerServiceProvider` wires the package into an `ArgonContainer`.

Installation
------------

[](#installation)

```
composer require maduser/argon-error
```

The formatter depends on PSR-17 response and stream factories. In a full Argon stack those are normally provided by `maduser/argon-http-message`.

Service Provider
----------------

[](#service-provider)

Register the provider during application boot:

```
use Maduser\Argon\Container\ArgonContainer;
use Maduser\Argon\Error\Provider\ErrorHandlerServiceProvider;

$container = new ArgonContainer();
$container->register(ErrorHandlerServiceProvider::class);
$container->boot();
```

The provider binds:

- `Maduser\Argon\Support\Contracts\ErrorHandlerInterface`
- `Maduser\Argon\Error\Contracts\ExceptionDispatcherInterface`
- `Maduser\Argon\Error\Contracts\ExceptionFormatterInterface`
- `Maduser\Argon\Error\Contracts\ExceptionPolicyRegistryInterface`

Any service tagged as `ExceptionPolicyInterface` can register custom exception reporting and rendering during container boot.

```
use App\Http\AppExceptionPolicy;
use Maduser\Argon\Error\Contracts\ExceptionPolicyInterface;

$container->set(AppExceptionPolicy::class)->tag(ExceptionPolicyInterface::class);
```

Exception Policies
------------------

[](#exception-policies)

Policies separate side effects from response creation:

- reporters run first for all matching exception types;
- renderers run after reporters and may return a `ResponseInterface`;
- a renderer returning `null` lets the dispatcher continue;
- if no renderer returns a response, the formatter creates the fallback response.

```
use Maduser\Argon\Error\Contracts\ExceptionPolicyInterface;
use Maduser\Argon\Error\Contracts\ExceptionPolicyRegistryInterface;
use App\Exceptions\PaymentFailed;
use Psr\Http\Message\ResponseFactoryInterface;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Message\StreamFactoryInterface;
use Psr\Log\LoggerInterface;
use RuntimeException;
use Throwable;

final readonly class AppExceptionPolicy implements ExceptionPolicyInterface
{
    public function __construct(
        private LoggerInterface $logger,
        private ResponseFactoryInterface $responses,
        private StreamFactoryInterface $streams,
    ) {
    }

    public function register(ExceptionPolicyRegistryInterface $exceptions): void
    {
        $exceptions->report(
            Throwable::class,
            fn(Throwable $e, ServerRequestInterface $request): void => $this->logger->error(
                $e->getMessage(),
                ['exception' => $e, 'path' => $request->getUri()->getPath()]
            )
        );

        $exceptions->report(
            PaymentFailed::class,
            fn(PaymentFailed $e): void => $this->notifyBillingChannel($e)
        );

        $exceptions->render(
            RuntimeException::class,
            fn(RuntimeException $e): ?ResponseInterface => $this->responses
                ->createResponse(500)
                ->withHeader('Content-Type', 'application/json')
                ->withBody($this->streams->createStream('{"error":"Runtime failure"}'))
        );
    }
}
```

Renderer selection is deterministic. More specific exception classes win before parent classes or interfaces. If two renderers are registered for the same specificity, registration order wins.

Reporter and renderer failures are logged and swallowed. Exception handling must not fail because an application callback failed.

Formatting
----------

[](#formatting)

`ExceptionFormatter` uses the request `Accept` header:

- `application/json` returns a JSON error payload.
- anything else returns `text/plain`.

HTTP status resolution is deliberately conservative:

- exceptions implementing `HttpExceptionInterface` may provide an explicit status code;
- otherwise throwable codes in the `400..599` range are used;
- invalid or non-HTTP codes fall back to `500`.

Stack traces are hidden by default. They are included only when debug mode is enabled or the exception implements `SafeToDisplayExceptionInterface`.

###  Health Score

36

—

LowBetter than 79% of packages

Maintenance88

Actively maintained with recent releases

Popularity7

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity35

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

61d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/7fb9da5a15010d335622bf9f465a32ef79c8d1cffcd139c2a9114736b72e2c13?d=identicon)[jdu](/maintainers/jdu)

---

Top Contributors

[![judus](https://avatars.githubusercontent.com/u/1478654?v=4)](https://github.com/judus "judus (20 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPsalm

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/maduser-argon-error/health.svg)

```
[![Health](https://phpackages.com/badges/maduser-argon-error/health.svg)](https://phpackages.com/packages/maduser-argon-error)
```

###  Alternatives

[tempest/framework

The PHP framework that gets out of your way.

2.2k34.4k16](/packages/tempest-framework)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

85036.3k](/packages/flow-php-flow)[cakephp/cakephp

The CakePHP framework

8.8k19.5M1.8k](/packages/cakephp-cakephp)[pagemachine/typo3-formlog

Form log for TYPO3

23238.6k8](/packages/pagemachine-typo3-formlog)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

585.6M600](/packages/shopware-core)[typo3/cms

TYPO3 CMS is a free open source Content Management Framework initially created by Kasper Skaarhoj and licensed under GNU/GPL.

1.2k1.9M122](/packages/typo3-cms)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)