PHPackages                             georgeff/problem - 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. georgeff/problem

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

georgeff/problem
================

Translate exceptions to structured domain problems with a fluent builder and logger.

1.0.0(4mo ago)088MITPHPPHP ^8.4CI passing

Since Feb 22Pushed 4mo agoCompare

[ Source](https://github.com/MikeGeorgeff/problem)[ Packagist](https://packagist.org/packages/georgeff/problem)[ RSS](/packages/georgeff-problem/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (4)Versions (2)Used By (0)

georgeff/problem
================

[](#georgeffproblem)

Structured domain exceptions for PHP with a fluent builder API, exception translation, severity levels, context, correlation tracking, and serialization.

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

[](#installation)

```
composer require georgeff/problem
```

Overview
--------

[](#overview)

This package provides a set of domain-scoped exception classes that extend PHP's `\Exception` with structured fields for logging, translation, and observability:

- **Severity** — one of `critical`, `error`, `warning`, `info`, `debug`
- **Context** — arbitrary key-value data describing the failure scenario
- **Retryability** — signals whether the triggering operation can be retried
- **Correlation ID** — request-scoped trace identifier, `null` when not provided
- **Structured data** — a fully serializable snapshot for loggers and reporters

Each exception type comes with a fluent **builder** that handles message generation, code assignment, and context population for common failure scenarios. A **translator** converts arbitrary PHP exceptions into typed domain exceptions via a priority-ordered handler pipeline. A **reporter** composes translation and structured logging into a single drop-in component for application exception handlers.

Documentation
-------------

[](#documentation)

### Core

[](#core)

- [DomainException](.docs/domain-exception.md) — abstract base class for all domain exceptions
- [ExceptionBuilder](.docs/exception-builder.md) — generic fluent builder; base for all domain-specific builders

### Translation

[](#translation)

- [Translation](.docs/translation.md) — `ExceptionTranslator`, handler pattern, `PDOCatchAllHandler`, and SQLSTATE routing

### Logging

[](#logging)

- [Logging](.docs/logging.md) — `JsonStructuredLogger`, `EnvironmentEnricher`, `ContextEnricher`, and combining with translation

### Reporting

[](#reporting)

- [Reporting](.docs/reporting.md) — `ExceptionReporter`, correlation ID threading, application handler integration

### Exceptions & Builders

[](#exceptions--builders)

ExceptionSeverityRetryableError CodeDocs`DatabaseException``error``false``DB_NNNN`[database.md](.docs/database.md)`ValidationException``warning``false``VAL_NNNN`[validation.md](.docs/validation.md)`ExternalServiceException``error``true``EXT_NNNN`[external-service.md](.docs/external-service.md)`AuthenticationException``warning``true``AUTHN_NNNN`[authentication.md](.docs/authentication.md)`AuthorizationException``warning``false``AUTHZ_NNNN`[authorization.md](.docs/authorization.md)`NotFoundException``info``false``NOT_FOUND_NNNN`[not-found.md](.docs/not-found.md)`ConfigurationException``critical``false``CFG_NNNN`[configuration.md](.docs/configuration.md)`UnknownException``error``false``UNKNOWN_0000`[unknown.md](.docs/unknown.md)Quick Example
-------------

[](#quick-example)

```
use Georgeff\Problem\DatabaseExceptionBuilder;
use Georgeff\Problem\ValidationExceptionBuilder;
use Georgeff\Problem\Exception\DomainException;

// Database failure
DatabaseExceptionBuilder::new()
    ->connectionFailed()
    ->connection('db.example.com', 5432, 'myapp')
    ->throw();

// Validation failure
$builder = ValidationExceptionBuilder::new()
    ->required('email')
    ->minLength('username', 'ab', 3);

if ($builder->hasErrors()) {
    $builder->throw();
}

// Inspect any domain exception
} catch (DomainException $e) {
    $e->severity;        // "error"
    $e->retryable;       // false
    $e->context;         // ['query' => [...], ...]
    $e->correlationId;   // "a3f9..."
    $e->structuredData;  // full serializable snapshot
    $e->getErrorCode();  // "DB_0001"
}
```

License
-------

[](#license)

MIT — see [LICENSE](LICENSE).

###  Health Score

38

—

LowBetter than 83% of packages

Maintenance76

Regular maintenance activity

Popularity9

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity52

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

Unknown

Total

1

Last Release

132d ago

### Community

Maintainers

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

---

Top Contributors

[![MikeGeorgeff](https://avatars.githubusercontent.com/u/6169468?v=4)](https://github.com/MikeGeorgeff "MikeGeorgeff (6 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/georgeff-problem/health.svg)

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

###  Alternatives

[symfony/lock

Creates and manages locks, a mechanism to provide exclusive access to a shared resource

514139.2M692](/packages/symfony-lock)[matomo/matomo

Matomo is the leading Free/Libre open analytics platform

21.7k38.9k](/packages/matomo-matomo)[ecotone/ecotone

Enterprise architecture layer for Laravel and Symfony — CQRS, Event Sourcing, Durable Workflows (Sagas, Orchestrators), Projections, and Outbox messaging via PHP attributes.

564576.7k53](/packages/ecotone-ecotone)[civicrm/civicrm-core

Open source constituent relationship management for non-profits, NGOs and advocacy organizations.

751291.4k43](/packages/civicrm-civicrm-core)[illuminate/broadcasting

The Illuminate Broadcasting package.

7127.2M208](/packages/illuminate-broadcasting)[logiscape/mcp-sdk-php

Model Context Protocol SDK for PHP

368116.8k12](/packages/logiscape-mcp-sdk-php)

PHPackages © 2026

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