classes/Logger.md

Класс `Logger`

Пространство имён: goodboyalex\php_components_pack

Полное имя класса: goodboyalex\php_components_pack\Logger

Тип: финальный класс

Версия: 1.1

Доступно с: 1.3

ВНИМАНИЕ: Начиная с версии 1.1 (1.3.1) класс Logger реализует интерфейс ILogger.

Описание

Класс представляет собой систему журналирования с расширенным функционалом, включающую:

Управление обработчиками логов
Настройку форматирования сообщений
Конфигурацию уровней журналирования
Гибкую систему записи сообщений

Автор

Имя: Александр Бабаев
Email: contact_with_us@babaev-an.ru

Зависимости

Интерфейсы:
- ILogFormatter
- ILogHandler
Классы:
- DefaultLogFormatter
Перечисления:
- MessageType

Методы

Конструктор

public function __construct(array $config = [])

Описание:
Инициализирует систему журналирования с заданной конфигурацией.

Параметр:

$config (array) — конфигурация системы журналирования.

Управление обработчиками

public function addHandler(ILogHandler $handler): void

Описание:
Добавляет новый обработчик в систему журналирования.

Параметр:

$handler (ILogHandler) — экземпляр обработчика.

public function setFormatter(ILogFormatter $formatter, bool $needToUpdate = true): void

Описание:
Устанавливает форматер сообщений.

Параметры:

$formatter (ILogFormatter) — форматер сообщений.
$needToUpdate (bool) — флаг обновления существующих обработчиков (по умолчанию true).

Конфигурация

public function setConfig(array $config = []): void

Описание:
Обновляет конфигурацию системы журналирования.

Параметр:

$config (array) — новая конфигурация.

public function setLevel(MessageType $level): void

Описание:
Устанавливает минимальный уровень журналируемых сообщений.

Параметр:

$level (MessageType) — уровень сообщений.

Запись сообщений

public function log(MessageType $level, string $message, array $context = []): void

Описание:
Записывает сообщение заданного уровня.

Параметры:

$level (MessageType) — уровень сообщения.
$message (string) — текст сообщения.
$context (array) — контекстные данные.

public function debug(string $message, array $context = []): void

Описание:
Записывает отладочное сообщение.

Параметры:

$message (string) — текст сообщения.
$context (array) — контекстные данные.

public function info(string $message, array $context = []): void

Описание:
Записывает информационное сообщение.

Параметры:

$message (string) — текст сообщения.
$context (array) — контекстные данные.

public function warning(string $message, array $context = []): void

Описание:
Записывает предупреждающее сообщение.

Параметры:

$message (string) — текст сообщения.
$context (array) — контекстные данные.

public function error(string $message, array $context = []): void

Описание:
Записывает сообщение об ошибке.

Параметры:

$message (string) — текст сообщения.
$context (array) — контекстные данные.

Примеры использования

Базовый пример

// Создание системы журналирования с конфигурацией
$logger = new Logger([
    'level' => MessageType::DEBUG,
    'handlers' => [
        // Настройка обработчиков
    ]
]);

// Установка форматера
$logger->setFormatter(new DefaultLogFormatter());

// Запись сообщений
$logger->info('Операция выполнена успешно');
$logger->error('Произошла ошибка', ['error' => 'Описание ошибки']);

Расширенное описание класса Logger

Уровни журналирования

Поддерживаемые уровни:

DEBUG — отладочные сообщения
INFO — информационные сообщения
WARNING — предупреждения
ERROR — сообщения об ошибках

Конфигурация системы

Параметры конфигурации:

level — минимальный уровень журналирования
handlers — массив обработчиков
formatter — форматер по умолчанию

Пример конфигурации:

// Создадим обработчики
$consoleHandler = new ConsoleHandler();
$fileHandler = new FileHandler();
$rotatingFileHandler = new RotatingFileHandler();
$bufferedFileHandler = new BufferedFileHandler();
$bufferedRotatingFileHandler = new BufferedRotatingFileHandler();

// Создадим обработчик форматирования сообщений
$formatter = new RussianLogFormatter();

// И, собственно, конфигурация
$config = [
    // Базовая конфигурация (обязательна для всех типов системы журналирования)
    'base' => [
        // Уровень журналирования: DEBUG < INFO < WARNING < ERROR.
        // По умолчанию: WARNING
        // Чем ниже уровень, тем больше сообщений будет записано.
        // Например: на уровне ERROR будут записаны только ошибки,
        // а на уровне INFO — все ошибки, предупреждения и информационные сообщения.
        // При разработке приложения рекомендуется использовать DEBUG,
        // в продакшене — WARNING или ERROR.
        'level' => MessageType::DEBUG,
        // Задаём обработчик форматирования сообщений
        'formatter' => $formatter,
        // - и список обработчиков
        'handlers' => [
            $consoleHandler,
            $fileHandler,
            $rotatingFileHandler,
            $bufferedFileHandler,
            $bufferedRotatingFileHandler
            ]
        ],
    
    // Конфигурация для каждого обработчика
    // - консольный обработчик
    'ConsoleHandler' => [
        // - цветовая схема
        'color' => [
            // голубой
            'DEBUG' => "\033[36m",
            // зелёный
            'INFO' => "\033[32m",
            // жёлтый
            'WARNING' => "\033[33m",
            // красный
            'ERROR' => "\033[31m"
            ]
        ],
    // - файловый обработчик
    'FileHandler' => [
        // - имя файла
        'file' => 'fileHandler.log'
        ],
    
    // - обработчик файлов с ротацией
    'RotatingFileHandler' => [
        // - имя файла
        'file' => 'rotatingFileHandler.log',
        // - максимальный размер файла
        'max_size' => 1,
        // - максимальное количество файлов
        'max_files' => 2
        ],
    
    // - обработчик файлов с буферизацией
    'BufferedFileHandler' => [
        // - имя файла
        'file' => 'bufferedFileHandler.log',
        // - порог для записи в файл
        'flush_threshold' => 2
        ],
    
    // - обработчик файлов с буферизацией и ротацией
    'BufferedRotatingFileHandler' => [
        // - имя файла
        'file' => 'bufferedRotatingFileHandler.log',
        // - максимальный размер файла
        'max_size' => 1,
        // - максимальное количество файлов
        'max_files' => 2,
        // - порог для записи в файл
        'flush_threshold' => 2
        ]
    ];

Работа с обработчиками

Добавление обработчика:

$logger = new Logger();
$handler = new FileHandler();
$handler->setFile('my_log.log');
$logger->addHandler($handler);

Настройка форматирования

Установка форматера:

$formatter = new DefaultLogFormatter();
$logger->setFormatter($formatter, true);

Примеры использования

Базовый пример

// Создание системы журналирования с базовой конфигурацией
$logger = new Logger([
    'level' => MessageType::DEBUG,
    'handlers' => [
        new FileLogHandler(),
        new ConsoleLogHandler()
    ],
    // - файловый обработчик
    'FileHandler' => [
        // - имя файла
        'file' => self::FileHandlerFileName
        ],
]);

// Запись сообщений разных уровней
$logger->debug('Отладочная информация');
$logger->info('Операция успешно завершена');
$logger->warning('Обнаружено предупреждение');
$logger->error('Произошла критическая ошибка');

Расширенный пример

// Настройка своего форматера
class CustomLogFormatter implements ILogFormatter {
    public function formatMessage (MessageType $level, string $message, array $context = []): string
        {
            // Задаю базовую информацию
            $result = sprintf(
                '%s [%s] %s',
                date('Y-m-d H:i:s'),
                strtoupper($level->toString()),
                $message
            );
            
            // Если контекст не пуст
            if (!empty($context))
                // - то выдаю контекст
                $result .= ' | ' . json_encode($context, JSON_UNESCAPED_UNICODE);
            
            // Возвращаю результат
            return $result;
        }
}

$customFormatter = new CustomLogFormatter();

$logger->setFormatter($customFormatter);

// Запись сообщения с контекстом
$logger->error(
    'Ошибка при обработке запроса',
    [
        'request_id' => '12345',
        'user_id' => 100,
        'error_code' => 500
    ]
);

Обработка ошибок

Возможные сценарии:

Ошибка при записи в файл
Отсутствие прав доступа
Проблемы с форматом сообщения

Обработка исключений:

try {
    $logger->log(
        MessageType::ERROR,
        'Критическая ошибка',
        ['error' => $exception->getMessage()]
    );
} catch (\Exception $e) {
    // Обработка ошибки журналирования
}

Расширяемость

Создание кастомных обработчиков:

class CustomLogHandler implements ILogHandler {
    // Реализация методов интерфейса
}

Создание кастомных форматеров:

class CustomLogFormatter implements ILogFormatter {
    // Реализация методов интерфейса
}

Безопасность

Важные аспекты:

Не журналируйте чувствительные данные!
Настройте права доступа к файлам логов
Используйте безопасные форматы хранения

На главную | Содержание

classes/Logger.md

Класс Logger

Описание

Автор

Зависимости

Методы

Конструктор

Управление обработчиками

Конфигурация

Запись сообщений

Примеры использования

Базовый пример

Расширенное описание класса Logger

Уровни журналирования

Конфигурация системы

Работа с обработчиками

Настройка форматирования

Примеры использования

Базовый пример

Расширенный пример

Рекомендации по использованию

Обработка ошибок

Расширяемость

Безопасность

Класс `Logger`