# PHP Error Handling

> Implement modern PHP error and exception handling patterns. Use when implementing exception hierarchies, error handlers, or custom exceptions in PHP.

- Skill: `hoangnguyen0403/php-error-handling` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds add hoangnguyen0403/php-error-handling`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hoangnguyen0403/php-error-handling/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: HoangNguyen0403 (https://skillmd.com/u/hoangnguyen0403)
- Updated: 2026-08-19
- Page: https://skillmd.com/skills/hoangnguyen0403/php-error-handling

---

# PHP Error Handling

## **Priority: P0 (CRITICAL)**

## Structure

See [implementation examples](references/implementation.md#directory-structure) for directory layout.

## Build Exception Hierarchies

- **Exception-Driven**: Favor **`throwing exceptions`** over returning `false` or `null` for error states.
- **Custom Exceptions**: Extend **`RuntimeException`** or **`LogicException`** for domain-specific errors.
- **Multi-Catch**: Use Union types in catch blocks: **`catch (DomainException | InvalidArgumentException $e)`**.

See [implementation examples](references/implementation.md#exception-hierarchy-example) for domain exception hierarchy with multi-catch and finally.

## Configure Global Error Handling

- **Throwable Interface**: Always catch **`Throwable`** for both PHP 7/8 Errors and Exceptions.
- **Global Handler**: Use **`set_exception_handler`** and **`set_error_handler`** for top-level logging and cleanup.
- **Finally**: Always use **`finally`** for resource cleanup (e.g., closing file handles, DB connections).
- **PSR-3 Logging**: Implement **`Psr\Log\LoggerInterface`** for structured error reporting.
- **Production Guard**: Ensure **`display_errors=Off`** and **`log_errors=On`** in production `php.ini`.

## Anti-Patterns

- **No `@` error suppression**: Handle or log errors explicitly.
- **No empty catch blocks**: Log or rethrow all caught exceptions.
- **No exceptions for control flow**: Reserve for unexpected errors only.
- **No `display_errors` in production**: Log to file; never show users.

## References

- [Exception & Logging Patterns](references/implementation.md)