README

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

CloudCastle Logger

Быстрый PSR-3 логгер для PHP 8.1+ с маскированием персональных данных «из коробки». Хендлеры (поток, ротация, fingers-crossed, группа), форматтеры (строка, JSON), процессоры, иммутабельные записи и инъекция часов. Нулевые внешние зависимости (только psr/log и psr/clock).

Установка

composer require cloud-castle/logger

Требуется PHP 8.1+.

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

<?php

use CloudCastle\Logger\Logger;
use CloudCastle\Logger\Handler\StreamHandler;
use CloudCastle\Logger\Level;
use CloudCastle\Logger\Processor\PdMaskingProcessor;
use CloudCastle\Logger\Processor\PsrMessageProcessor;

$logger = new Logger(
    channel: 'payments',
    handlers: [new StreamHandler('/var/log/app.log', Level::Info)],
    processors: [new PdMaskingProcessor(), new PsrMessageProcessor()],
);

// Персональные данные маскируются в сообщении И контексте.
$logger->info('оплата картой {card}', ['card' => '4111111111111111']);
// → оплата картой ************1111

$logger->error('сбой шлюза', ['gateway' => 'acme', 'code' => 502]);

Возможности

PSR-3 совместимый логгер: 8 уровней, {плейсхолдеры}, LoggerInterface.
Маскирование ПД из коробки (PdMaskingProcessor): карты, счета, IBAN, email в сообщении и вложенном контексте — защита от утечки в логи.
Приёмники из коробки (без внешних зависимостей): StreamHandler (файл/поток), RotatingFileHandler (посуточная ротация), SyslogHandler (системный журнал), ErrorLogHandler (error_log() PHP), SocketHandler (TCP/UDP для Graylog/Logstash/syslog-ng), FingersCrossedHandler (буфер до ошибки), GroupHandler (веерная рассылка), NullHandler, TestHandler.
Форматтеры: LineFormatter (настраиваемый шаблон), JsonFormatter (NDJSON).
Процессоры: интерполяция PSR-3, потребление памяти, маскирование ПД.
Иммутабельные записи и инъекция часов (PSR-20) — детерминированные тесты.
Быстрый отбор по порогу: подавлённые записи не запускают процессоры.

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

Все таблицы ниже сгенерированы автоматически из честных сравнительных тестов (benchmarks/compare.php) на ОДИНАКОВОЙ операции для всех аналогов, PHP 8.1.34, без Xdebug.

1. Функциональность

Возможность	🏆 CloudCastle	monolog	printf¹	json¹	error_log¹	NullLogger¹
PSR-3 совместимость (LoggerInterface)	✅	✅	❌	❌	❌	✅
Маскирование ПД из коробки (карты/email/телефоны)	✅	❌	❌	❌	❌	❌
Набор приёмников (stream/rotating/syslog/socket/fingers-crossed)	✅	✅	❌	❌	❌	❌
Форматтеры и процессоры записей	✅	✅	❌	❌	❌	❌
Нулевые внешние зависимости (только psr/log)	✅	✅	✅	✅	✅	✅
Всего	🏆 5	4	1	1	1	2

2. Безопасность и корректность

Свойство	🏆 CloudCastle	monolog	printf¹	json¹	error_log¹	NullLogger¹
Маскирование ПД в сообщении и контексте из коробки	✅	❌	❌	❌	❌	❌
Изоляция сбоя приёмника (не рушит приложение)	✅	✅	❌	❌	❌	✅
Корректная фильтрация по уровням PSR-3	✅	✅	❌	❌	❌	❌
Безопасная интерполяция контекста (без утечки объектов)	✅	✅	❌	❌	❌	❌
Нулевые внешние зависимости (меньше поверхность атаки)	✅	✅	✅	✅	✅	✅
Всего	🏆 5	4	1	1	1	2

3. Производительность

Запись info с контекстом в null-приёмник, 100 000 раз (минимум из 4).

Решение	Время (мс)	Итог
NullLogger¹	7,2	базовый уровень (не библиотека)
printf¹	188,8	базовый уровень (не библиотека)
json¹	204,7	базовый уровень (не библиотека)
🏆 CloudCastle	242,7	быстрейшее среди библиотек
monolog	246,5	аналог
error_log¹	1 063,5	базовый уровень (не библиотека)

4. Потребление памяти

Пик памяти на 100 000 записей (изолированный процесс, только целевая библиотека).

Решение	Пиковая память (KB)	Итог
🏆 CloudCastle	6 964	легчайшее среди библиотек
monolog	6 964	аналог
printf¹	6 964	базовый уровень (не библиотека)
json¹	6 964	базовый уровень (не библиотека)
error_log¹	6 964	базовый уровень (не библиотека)
NullLogger¹	6 964	базовый уровень (не библиотека)

¹ Базовый уровень (нативные вызовы/примитивы без полноты решения) показан для контекста и не претендует на победу среди библиотек-аналогов.

_{Экосистема PSR-3 ^3.0 представлена monolog (apix/analog/laminas остались на
psr/log ^1 и несовместимы). Нативные приёмы (printf/json/error_log/NullLogger,
baseline) быстрее полноценного логгера, но без единого API, уровней, приёмников,
форматтеров, процессоров и маскирования ПД. cloud-castle обгоняет monolog, при
этом маскируя ПД из коробки (monolog требует свой процессор). Память измеряется
в изоляции.}

Вывод: CloudCastle Logger — самый быстрый полноценный PSR-3 логгер (быстрее monolog) и самый лёгкий по памяти, с маскированием персональных данных из коробки, набором приёмников, форматтеров и процессоров при нулевых внешних зависимостях кроме psr/log.

Разработка

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

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

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

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

Лицензия