Semantic, HTTP-aligned domain exceptions for PHP 8.1+ DDD applications - framework-agnostic, zero runtime dependencies

php-exceptions

A curated set of reusable, semantic domain exceptions for Domain-Driven Design PHP applications. Their names mirror the HTTP 4XX/5XX families because that vocabulary is widely understood, but they are raised in the domain layer, outside any transport, and translated at the boundary into an HTTP response, RPC error, CLI exit or queue dead-letter. Throwing the right exception is part of your domain language, where a generic InvalidArgumentException leaks plumbing into it. Framework-agnostic, with zero runtime dependencies beyond the PHP standard library, on any PHP 8.1+ project.

• Client exceptions - caller-fault types aligned to the 4XX family, from BadRequestException through UnavailableForLegalReasonsException, each with a default message and status code.
• Server exceptions - system-fault types aligned to the 5XX family, from InternalServerErrorException through LoopDetectedException.
• AbstractBaseException - the common base, extending PHP's native \DomainException, so a single catch captures everything in this package.
• Request\RequestFailureException - structured per-field validation failures, for one rejected payload carrying many reasons.
• Extension by intent - every type is meant to be extended by your own named exception, so callers can still catch the broader intent.

Requirements

Installation

composer require hradigital/php-exceptions

Usage

Every exception in this package extends AbstractBaseException, which itself extends PHP's native \DomainException. Each subclass ships with a sensible default message and an HTTP-aligned status code ($code).

use HraDigital\Components\Exceptions\Client\NotFoundException;

throw new NotFoundException('User #42 does not exist.');