cloud-castle/error-handler

Обработчик ошибок и исключений для PHP 8.1+: единый перехват ошибок, исключений и фатальных сбоев, рендеринг под окружение (CLI / HTML / JSON) и логирование через PSR-3.

v1.0.2 2026-07-29 08:35 UTC

Requires

• php: >=8.1
• psr/log: ^3.0

Requires (Dev)

• deptrac/deptrac: ^3.0 || ^4.0
• ergebnis/composer-normalize: ^2.45
• friendsofphp/php-cs-fixer: ^3.75
• icanhazstring/composer-unused: ^0.9
• infection/infection: ^0.29 || ^0.33
• php-parallel-lint/php-parallel-lint: ^1.4
• phpmd/phpmd: ^2.15
• phpstan/extension-installer: ^1.4
• phpstan/phpstan: ^1.12 || ^2.1
• phpstan/phpstan-deprecation-rules: ^1.2 || ^2.0
• phpstan/phpstan-phpunit: ^1.4 || ^2.0
• phpstan/phpstan-strict-rules: ^1.6 || ^2.0
• phpunit/phpunit: ^10.5 || ^11.5
• psalm/plugin-phpunit: ^0.19 || ^0.20
• rector/rector: ^1.2 || ^2.0
• roave/security-advisories: dev-latest
• squizlabs/php_codesniffer: ^3.12 || ^4.0
• vimeo/psalm: ^6.0
• webmozart/assert: ^1.11

MIT

• CloudCastle

• php
• error-handler
• php8
• cloud-castle

Published on Packagist.org on 2026-07-29 09:00 UTC

README

🇷🇺 Русский · 🇬🇧 English · 🇩🇪 Deutsch · 🇫🇷 Français · 🇪🇸 Español · 🇮🇹 Italiano

CloudCastle ErrorHandler

Единая обработка ошибок и исключений: PHP-ошибки → исключения, логирование через PSR-3, безопасный вывод (CLI/JSON/HTML). В боевом режиме детали не раскрываются — защита от утечки внутренней информации.

Установка

composer require cloud-castle/error-handler

Требуется PHP 8.1+. Единственная зависимость — PSR-3 (psr/log).

Быстрый старт

<?php

use CloudCastle\ErrorHandler\ErrorHandler;
use CloudCastle\ErrorHandler\Renderer\JsonRenderer;

// $logger — любая PSR-3 реализация; $debug берётся из окружения (НЕ в проде).
$handler = new ErrorHandler($logger, new JsonRenderer(), debug: false);
$handler->register();

// Теперь любая PHP-ошибка превращается в исключение, необработанные
// исключения и фатальные ошибки — логируются и отдаются как безопасный JSON.

Возможности

• Единая точка — register() ставит обработчики ошибок, исключений и завершения работы (фатальные ошибки); PHP-ошибки конвертируются в ErrorException с учётом подавления оператором @.
• Логирование через PSR-3 — каждое необработанное исключение уходит в LoggerInterface::error() с самим исключением в контексте.
• Безопасный вывод по режиму — в боевом режиме (debug: false) наружу идёт только обобщённое сообщение; детали (сообщение, файл, строка, трассировка) доступны лишь в отладке. Защита от утечки чувствительных данных.
• Три представления — CliRenderer (консоль), JsonRenderer (API), HtmlRenderer (браузер, с экранированием — защита от XSS). Свой рендер — через интерфейс Contract\Renderer.

Сравнение с аналогами

Возможность	error-handler	filp/whoops	symfony/error-handler	monolog (only log)	league/booboo	nunomaduro/collision
Обработка error+exception+shutdown	✅	⚠️	✅	❌	✅	⚠️ CLI
PSR-3 логирование из коробки	🏆 ✅	❌	⚠️	—	✅	❌
Скрытие деталей в проде	🏆 ✅	❌	⚠️	—	⚠️	❌
XSS-экранирование HTML	✅	✅	✅	—	⚠️	—
Runtime-зависимостей	🏆 1 (PSR-3)	1	5+	1	2+	3+
Форматы вывода (CLI/JSON/HTML)	🏆 3	1 (HTML)	2	—	2	1 (CLI)

Когда применять. error-handler уместен как минимальный безопасный обработчик для API и приложений, где важно не раскрывать детали ошибок в проде и писать их в PSR-3. Если нужна богатая интерактивная страница отладки с подсветкой кода и контекстом запроса — берите filp/whoops или symfony/error-handler: это их сильная сторона, здесь она сознательно не воспроизводится.

Разработка

composer install
composer check    # линтеры + статический анализ + тесты
composer fix      # автоисправления (Rector, PHP CS Fixer, PHPCBF)
composer ci       # полный CI-пайплайн локально

Полный список команд с описаниями: composer run-script --list.

Документация

• Репозиторий: https://gitverse.ru/cloud-castle/error-handler
• История изменений: CHANGELOG.md
• Как внести вклад: CONTRIBUTING.md
• Кодекс поведения: CODE_OF_CONDUCT.md
• Политика безопасности: SECURITY.md

Лицензия

MIT © CloudCastle ([e-mail])

🇷🇺 Русский · 🇬🇧 English · 🇩🇪 Deutsch · 🇫🇷 Français · 🇪🇸 Español · 🇮🇹 Italiano