Download the PHP package phpdot/error without Composer

phpdot/error

Structured error codes with context, translatable messages, and uniform output across every channel. Optional translator integration via phpdot/contracts.

Table of Contents

• Requirements
• Installation
• Usage
  • Quick Start
  • How It Works
  • Defining Error Codes
  • ErrorEntry (The DTO)
  • ErrorBag (The Collector)
  • ErrorBagFactory
  • ErrorType (9 Categories)
  • HttpStatus (Typed Enum)
  • Context
  • Translation (i18n)
  • Output Formats
  • Real-World Usage
  • API Reference
• Architecture
• Testing
• License

Requirements

Installation

Usage

Quick Start

1. Define errors for your module:

2. Collect errors:

3. Same output everywhere:

How It Works

Add flow

Two ways to construct a bag

• Direct: new ErrorBag() for a raw bag, or new ErrorBag($translator) to build one that translates description keys at add() time.
• Through ErrorBagFactory: inject the factory once, call create() for each fresh bag. The factory carries the (optional) translator, so every bag it produces is pre-wired. Designed for DI auto-wiring — services that depend on the factory never import MessageTranslatorInterface themselves.

Package Structure

7 files. Single optional dependency on phpdot/contracts for the cross-package translator interface.

Defining Error Codes

ErrorCodeInterface

Every module defines a backed string enum implementing this interface:

ErrorCodeTrait

Provides the default implementation. The trait reads from getDetails() — you only implement one method:

Module Error Enums

Each module owns its errors. No central error file.

Error Code Convention

ErrorEntry (The DTO)

Pure data. No translation, no escaping. Immutable.

ErrorBag (The Collector)

Adding Errors

Checking Errors

Filtering Errors

Merging Bags

Combine errors from sub-operations:

HTTP Status

Derived from the first error. If empty, returns 500.

Serialization

Clear and reset:

ErrorBagFactory

Produces fresh ErrorBag instances pre-wired with an optional translator. Inject the factory once, call create() whenever you need a new bag — translator threading happens automatically.

Each create() call returns a new, independent bag — no shared state between calls.

Auto-wired usage

When using phpdot/container, services that need to produce errors inject the factory directly. The translator is wired into the factory through the container and passed to every bag the factory produces — without the service ever importing MessageTranslatorInterface:

The factory is #[Scoped] so each execution unit (request, coroutine) gets its own instance with its own per-request translator.

ErrorType (9 Categories)

The frontend uses the type to decide presentation (red badge for server, yellow for validation, etc.). The error code gives the specific problem.

HttpStatus (Typed Enum)

IDE autocompletion and compile-time safety for HTTP status codes:

Context

Context is what the error relates to. Not just form fields.

Filter by context to show errors next to the right element:

Translation (i18n)

How Translation Works

The error package stores translation keys, not translated text. Translation happens at render time.

ICU Params

Dynamic values for translation interpolation. Works with any ICU-compatible i18n library — phpdot/i18n is one option, but not required.

Frontend Translation

The frontend receives the error code and description key, translates in its own i18n system:

Server-Side Translation

With any translation library:

Auto-Translation via MessageTranslatorInterface

ErrorBag accepts an optional PHPdot\Contracts\I18n\MessageTranslatorInterface in its constructor. When wired, every add() call replaces the entry's description field with the translator's output for the original key + ICU params:

The message field is never touched by the bag — it always carries the enum's English string (developer-facing documentation). The description field is the runtime-variable one: the raw translation key when no translator is wired, or the translated string when one is.

The bag does not second-guess the translator. Whatever the translator returns — including a [key] sentinel for missing keys — goes straight into description. Fallback policy is the translator's responsibility, not the bag's.

MessageTranslatorInterface ships in phpdot/contracts. phpdot/i18n's Translator already implements it, but any compatible translator works.

Output Formats

JSON API

HTML Forms

CLI

WebSocket

Same $bag->toArray() serialized as JSON. Identical structure to the API.

Real-World Usage

Service Validation

Cross-Module Merge

Frontend Grouping

API Reference

ErrorCodeInterface API

ErrorCodeTrait API

ErrorEntry API

ErrorBag API

ErrorType API

HttpStatus API

Architecture

One error. One code. One structure. Every channel. Every language.

Testing

The package is standalone-testable:

License

MIT.

This repository is a read-only mirror, generated by CI from phpdot/monorepo. Pull requests and issues belong in the monorepo.