khovanskiy/yii2-request-id

There is no license information available for the latest version (1.0.2) of this package.

Yii2 component for handling and propagating request IDs

1.0.2 2024-12-20 09:06 UTC

This package is auto-updated.

Last update: 2025-05-20 10:02:21 UTC


README

Yii2 PHP License

Yii2 Request ID — это удобный компонент для фреймворка Yii2, который автоматически генерирует и обрабатывает уникальные идентификаторы запросов (Request ID). Эти идентификаторы помогают отслеживать и логировать запросы как в веб-приложениях, так и в консольных командах, обеспечивая лучшую трассировку и отладку.

Содержание

  1. Особенности
  2. Установка
  3. Настройка
  4. Использование
  5. Примеры
  6. Пользовательские генераторы Request ID
  7. Требования
  8. Лицензия
  9. Авторы
  10. Поддержка

Особенности

  • Автоматическая генерация уникального идентификатора для каждого HTTP-запроса и консольной команды.
  • Передача идентификатора через заголовок X-Request-ID в HTTP-ответах.
  • Доступ к идентификатору через сервис RequestIdService в любом месте приложения.
  • Поддержка консольных команд с выводом идентификатора в консоль и логах.
  • Возможность расширения и использования собственных генераторов идентификаторов.

Установка

Требования

  • PHP: >= 7.4
  • Yii2: >= 2.0.45

Шаг 1: Установка через Composer

Для установки пакета выполните следующую команду в корневой директории вашего проекта Yii2 Advanced:

composer require khovanskiy/yii2-request-id

Установка локального пакета (опционально)

Если вы разрабатываете пакет локально и хотите подключить его без публикации, выполните следующие шаги:

  1. Добавьте репозиторий в composer.json основного проекта:
{
  "repositories": [
    {
      "type": "composer",
      "url": "https://asset-packagist.org"
    },
    {
      "type": "path",
      "url": "../yii2-request-id",
      "options": {
        "symlink": true
      }
    }
  ]
}

Примечание: Убедитесь, что путь "../yii2-request-id" указывает на директорию вашего локального пакета.

  1. Установите пакет с указанием ветки разработки:
composer require khovanskiy/yii2-request-id:dev-main

Важно: Если в вашем пакете используется нестабильная версия (dev-main), убедитесь, что в composer.json основного проекта установлено "prefer-stable": true.

Настройка

После установки необходимо настроить компонент в вашем приложении Yii2.

Шаг 1: Конфигурация Yii2

Откройте конфигурационный файл вашего приложения (common/config/main.php, backend/config/main.php или frontend/config/main.php в зависимости от структуры вашего проекта) и добавьте следующие настройки:

<?php

use khovanskiy\yii2requestid\NginxRequestIdGenerator;
use khovanskiy\yii2requestid\RequestIdGenerator;
use khovanskiy\yii2requestid\RequestIdBootstrap;
use khovanskiy\yii2requestid\RequestIdLogFormatter;

return [
    // Другие настройки...
    'container' => [
        'singletons' => [
            RequestIdGenerator::class => NginxRequestIdGenerator::class,
        ],
    ],
    // Другие настройки...
];

Пояснения:

  • bootstrap: Добавляет класс RequestIdBootstrap в процесс загрузки приложения, что обеспечивает инициализацию компонента.
  • container.singletons: Определяет реализацию интерфейса RequestIdGenerator. В данном случае используется стандартный генератор NginxRequestIdGenerator, который генерирует 32-символьные шестнадцатеричные строки.

Шаг 2: Настройка composer.json (для локальной установки)

Если вы используете локальную установку пакета, убедитесь, что в composer.json вашего основного проекта прописаны правильные настройки автозагрузки и репозитория:

{
    "repositories": [
        {
            "type": "composer",
            "url": "https://asset-packagist.org"
        },
        {
            "type": "path",
            "url": "../yii2-request-id",
            "options": {
                "symlink": true,
                "replace": {
                    "khovanskiy/yii2-request-id": "1.0.0"
                }
            }
        }
    ],
    "require": {
        // Другие зависимости...
        "khovanskiy/yii2-request-id": "1.0.0"
    },
    "config": {
        "prefer-stable": true,
        "allow-plugins": {
            "yiisoft/yii2-composer": true
        },
        "process-timeout": 1800,
        "fxp-asset": {
            "enabled": false
        }
    }
}

Примечание: Если вы изменили minimum-stability, убедитесь, что она соответствует вашим требованиям.

Использование

После настройки компонент автоматически начнёт генерировать Request ID для каждого запроса и консольной команды. Вы можете получить доступ к текущему Request ID через сервис RequestIdService.

Доступ к Request ID

<?php

use khovanskiy\yii2requestid\RequestIdService;

// Получение сервиса через DI-контейнер
$requestIdService = Yii::$app->get(RequestIdService::class);

// Устанавливает или возвращает текущий Request ID.
// Если ID ещё не задан, будет сгенерирован новый.
// При необходимости можно передать собственный Request ID.
$requestIdService->setRequestId(); 
$requestIdService->setRequestId('Test_request_id'); 
$currentRequestId = $requestIdService->getRequestId();

echo "Текущий Request ID: " . $currentRequestId;

Получение Request ID в консольных командах

При выполнении консольных команд Request ID будет автоматически сгенерирован и выведен в консоль, а также записан в логи.

Примеры

Веб-приложение

При каждом HTTP-запросе:

  1. Компонент проверяет наличие заголовка X-Request-ID.
  2. Если заголовок отсутствует, генерируется новый Request ID.
  3. Request ID сохраняется в Yii::$app->params['request_id'].
  4. В ответ добавляется заголовок X-Request-ID с текущим Request ID.
  5. В логах записываются входящий запрос и его Request ID.

Консольная команда

При запуске команды:

  1. Генерируется новый Request ID.
  2. Request ID выводится в консоль и сохраняется в Yii::$app->params['request_id'].
  3. В логах фиксируется начало и завершение выполнения команды с соответствующим Request ID.

Пользовательские генераторы Request ID

Вы можете использовать собственные генераторы Request ID, реализовав интерфейс RequestIdGenerator.

Шаг 1: Создайте класс генератора

<?php

namespace app\components\RequestId;

use khovanskiy\yii2requestid\RequestIdGenerator;

class CustomRequestIdGenerator implements RequestIdGenerator
{
    public function generateRequestId(): string
    {
        // Ваш собственный алгоритм генерации Request ID
        return uniqid('req_', true);
    }
}

Шаг 2: Зарегистрируйте генератор в контейнере

В конфигурационном файле (main.php) замените стандартный генератор на ваш собственный:

<?php
use khovanskiy\yii2requestid\RequestIdGenerator;
use app\components\RequestId\CustomRequestIdGenerator;
return [
    // Другие настройки...
    'container' => [
        'singletons' => [
            RequestIdGenerator::class => CustomRequestIdGenerator::class,
        ],
    ],
    // Другие настройки...
];

Требования

  • PHP: >= 7.4
  • Yii2: >= 2.0.45

Лицензия

Этот проект распространяется под лицензией BSD-3-Clause.

Авторы

Поддержка

Если у вас возникли вопросы или вы хотите предложить улучшения, пожалуйста, создайте issue на GitHub: https://github.com/khovanskiy5/Yii2-Request-Id/issues

Спасибо за использование Yii2 Request ID! Надеемся, что этот компонент поможет вам в улучшении трассировки и логирования ваших приложений на Yii2.