georgeff/problem

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

Installation

composer require georgeff/problem

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

Core

• DomainException — abstract base class for all domain exceptions
• ExceptionBuilder — generic fluent builder; base for all domain-specific builders

Translation

• Translation — ExceptionTranslator, handler pattern, PDOCatchAllHandler, and SQLSTATE routing

Logging

• Logging — JsonStructuredLogger, EnvironmentEnricher, ContextEnricher, and combining with translation

Reporting

• Reporting — ExceptionReporter, correlation ID threading, application handler integration

Exceptions & Builders

Exception	Severity	Retryable	Error Code	Docs
DatabaseException	error	false	DB_NNNN	database.md
ValidationException	warning	false	VAL_NNNN	validation.md
ExternalServiceException	error	true	EXT_NNNN	external-service.md
AuthenticationException	warning	true	AUTHN_NNNN	authentication.md
AuthorizationException	warning	false	AUTHZ_NNNN	authorization.md
NotFoundException	info	false	NOT_FOUND_NNNN	not-found.md
ConfigurationException	critical	false	CFG_NNNN	configuration.md
UnknownException	error	false	UNKNOWN_0000	unknown.md

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

MIT — see LICENSE.