PHPackages                             frootbox/exceptions - 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. [Utility & Helpers](/categories/utility)
4. /
5. frootbox/exceptions

ActiveLibrary[Utility & Helpers](/categories/utility)

frootbox/exceptions
===================

Frootbox Exceptions

0.1(1mo ago)03.1k4GPL-3.0-or-laterPHP

Since Jul 1Pushed 1mo agoCompare

[ Source](https://github.com/Frootbox/Exceptions)[ Packagist](https://packagist.org/packages/frootbox/exceptions)[ RSS](/packages/frootbox-exceptions/feed)WikiDiscussions master Synced today

READMEChangelogDependenciesVersions (6)Used By (4)

Frootbox Exceptions
===================

[](#frootbox-exceptions)

Small semantic exception package for Frootbox applications and libraries.

The package provides shared exception classes for common application states such as missing input, invalid input, missing resources, access denial, and runtime errors. These exceptions are intentionally transport-neutral: application code can throw them without knowing whether the error is later rendered as HTML, JSON, CLI output, or something else.

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

[](#installation)

```
composer require frootbox/exceptions
```

Basic Usage
-----------

[](#basic-usage)

```
use Frootbox\Exceptions\InputMissing;
use Frootbox\Exceptions\NotFound;

if (empty($payload['email'])) {
    throw new InputMissing('Email is required.');
}

if ($customer === null) {
    throw new NotFound('Customer not found.');
}
```

Every exception extends `Frootbox\Exceptions\BaseException`, which extends PHP's native `Exception`.

Exception Classes
-----------------

[](#exception-classes)

ExceptionIntended meaningHTTP status`AccessDenied`Authenticated actor is not allowed to perform the action`403``ClassMissing`Required PHP class is missing`500``ConfigurationMissing`Required configuration value is missing`400``InputInvalid`Provided input is present but invalid`400``InputMissing`Required input value is missing`400``NotFound`Requested resource or database row does not exist`404``NotLoggedIn`Authentication is required`401``ParameterMissing`Required parameter is missing`400``PermissionDenied`Actor has insufficient permission`403``ResourceInvalid`Resource exists but cannot be used as requested`400``ResourceMissing`Required resource is missing`404``RuntimeError`Internal application/runtime failure`500`HTTP Boundary Contract
----------------------

[](#http-boundary-contract)

Exceptions also implement:

```
Frootbox\Exceptions\Interfaces\HttpException
```

This interface exposes metadata for framework or adapter packages that need to render an error at an HTTP boundary:

```
public function getHttpStatusCode(): int;
public function getErrorCode(): string;
public function hasPublicMessage(): bool;
```

Example mapper:

```
use Frootbox\Exceptions\Interfaces\HttpException;

try {
    $response = $controller->execute();
}
catch (HttpException $exception) {
    http_response_code($exception->getHttpStatusCode());
    header('Content-Type: application/json; charset=utf-8');

    echo json_encode([
        'error' => [
            'code' => $exception->getErrorCode(),
            'message' => $exception->hasPublicMessage()
                ? $exception->getMessage()
                : 'Unexpected API error.',
        ],
    ]);

    exit;
}
```

Transport packages such as REST servers should depend on this interface instead of matching every concrete exception class individually.

Error Codes
-----------

[](#error-codes)

Each exception exposes a stable machine-readable code through `getErrorCode()`.

```
(new NotFound('Customer not found.'))->getErrorCode(); // not_found
```

If a concrete exception does not define a custom code, `BaseException` derives one from the class name.

Public Messages
---------------

[](#public-messages)

Most domain and validation exceptions expose their message publicly. Internal failures such as `RuntimeError` and `ClassMissing` mark their message as non-public:

```
$exception->hasPublicMessage(); // false
```

HTTP renderers should respect this and replace the message with a generic one.

Properties
----------

[](#properties)

All exceptions accept optional properties for structured context:

```
throw new InputMissing(properties: [ 'email' ]);
```

The properties can be read with:

```
$exception->getProperties();
```

`InputMissing` keeps the existing legacy behavior: when no message is provided but properties are present, its message becomes `Field`.

Translated Messages
-------------------

[](#translated-messages)

`toString()` builds a translation key compatible with Frootbox translators:

```
$exception->toString($translator);
```

If no translation is found, it falls back to the explicit exception message.

###  Health Score

47

—

FairBetter than 93% of packages

Maintenance90

Actively maintained with recent releases

Popularity20

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 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

Every ~628 days

Total

5

Last Release

49d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/fcec2f1b7299cf187eff1364cf8d442431845a14e202900c2756929f5ff36432?d=identicon)[82912759](/maintainers/82912759)

---

Top Contributors

[![JnHbbBrnng](https://avatars.githubusercontent.com/u/45029139?v=4)](https://github.com/JnHbbBrnng "JnHbbBrnng (7 commits)")

### Embed Badge

![Health badge](/badges/frootbox-exceptions/health.svg)

```
[![Health](https://phpackages.com/badges/frootbox-exceptions/health.svg)](https://phpackages.com/packages/frootbox-exceptions)
```

###  Alternatives

[salla/zatca

A helper to generate the QR code and signed it for ZATCA e-invoicing

164449.9k2](/packages/salla-zatca)[pixeloution/true-random

Interface for getting random datra from random.org

441.3k](/packages/pixeloution-true-random)

PHPackages © 2026

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