README

PHP 8.5+ пакет для интеграции с API Контур.Фокус.

Возможности

• standalone режим (чистый PHP, без фреймворка)
• Laravel интеграция (ServiceProvider, Facade, публикация конфига)
• fluent API для запросов (inn(), ogrn(), param(), asDto(), asArray())
• строгий маппинг ответа в readonly DTO через Reflection
• retry middleware (сетевые ошибки, 5xx, 429)
• cache middleware с кешированием только успешных 2xx ответов
• logging middleware с маскированием API ключа в query-параметре key
• готовые DTO для endpoint-ов из схем docs/endpoints/*/schema.json

Требования

• PHP ^8.5
• расширение ext-json

Установка

composer require ex3mm/kontur-focus

Быстрый старт (standalone)

<?php

declare(strict_types=1);

use Ex3mm\KonturFocus\Config\KonturFocusConfig;
use Ex3mm\KonturFocus\KonturFocusManager;

$config = KonturFocusConfig::fromArray(
    require __DIR__ . '/config/kontur-focus.standalone.php'
);

$focus = new KonturFocusManager($config);

$result = $focus->req()
    ->inn('7707083893')
    ->asDto()
    ->get();

Быстрый старт (Laravel)

Provider и Facade подключаются через auto-discovery.

// Вариант 1: Использование глобального алиаса (рекомендуется)
$result = \KonturFocus::req()
    ->inn('7707083893')
    ->asArray()
    ->get();

// Вариант 2: С полным импортом фасада
use Ex3mm\KonturFocus\Laravel\Facades\KonturFocus;

$result = KonturFocus::req()
    ->inn('7707083893')
    ->asArray()
    ->get();

Публикация конфига:

php artisan vendor:publish --tag=kontur-focus-config

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

Файл: config/kontur-focus.php

Пример полного конфига:

return [
    'key' => env('KONTUR_FOCUS_API_KEY', ''),
    'base_url' => env('KONTUR_FOCUS_BASE_URL', 'https://focus-api.kontur.ru'),

    'http' => [
        'timeout' => (float) env('KONTUR_FOCUS_TIMEOUT', 30),
        'connect_timeout' => (float) env('KONTUR_FOCUS_CONNECT_TIMEOUT', 10),
        'verify_ssl' => (bool) env('KONTUR_FOCUS_VERIFY_SSL', true),
    ],

    'retry' => [
        'enabled' => (bool) env('KONTUR_FOCUS_RETRY_ENABLED', true),
        'max_attempts' => (int) env('KONTUR_FOCUS_RETRY_ATTEMPTS', 3),
        'delay_ms' => (int) env('KONTUR_FOCUS_RETRY_DELAY', 500),
        'multiplier' => (float) env('KONTUR_FOCUS_RETRY_MULTIPLIER', 2),
        'max_delay_ms' => (int) env('KONTUR_FOCUS_RETRY_MAX_DELAY', 30000),
    ],

    'cache' => [
        'enabled' => (bool) env('KONTUR_FOCUS_CACHE_ENABLED', true),
        'ttl' => (int) env('KONTUR_FOCUS_CACHE_TTL', 3600),
        'store' => env('KONTUR_FOCUS_CACHE_STORE', 'default'),
        'namespace' => env('KONTUR_FOCUS_CACHE_NAMESPACE', 'kontur-focus'),
    ],

    'logging' => [
        'enabled' => (bool) env('KONTUR_FOCUS_LOG_ENABLED', true),
        'level' => env('KONTUR_FOCUS_LOG_LEVEL', 'basic'),
        'channel' => env('KONTUR_FOCUS_LOG_CHANNEL', 'default'),
        'max_body_size' => (int) env('KONTUR_FOCUS_LOG_MAX_BODY_SIZE', 10000),
    ],
];

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

Endpoint-ы

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

Режим asArray()

$data = $focus->req()
    ->inn('7707083893')
    ->asArray()
    ->get();

Режим asDto()

$result = $focus->req()
    ->inn('7707083893')
    ->asDto()
    ->get();

// $result - это CollectionResponse с полями:
// - items: array<DTO> - массив DTO объектов
// - raw: string - сырой JSON ответ
// - total: int - количество элементов

// Получить первый элемент
$dto = $result->first();

// Проверить пустоту
if ($result->isEmpty()) {
    // нет данных
}

// Получить массив DTO
$items = $result->toArray();

Выброс исключения при пустом результате

use Ex3mm\KonturFocus\Exceptions\EmptyResponseException;

try {
    $result = $focus->req()
        ->inn('7707083893')
        ->asDto()
        ->throwOnEmpty() // выбросит EmptyResponseException если total === 0
        ->get();
} catch (EmptyResponseException $e) {
    // обработка пустого результата
}

Кастомный endpoint

$result = $focus->custom('/api3/someEndpoint')
    ->param('foo', 'bar')
    ->param('limit', 10)
    ->asArray()
    ->get();

Валидация параметров

Для стандартных endpoint-ов запрос должен содержать хотя бы один параметр: inn или ogrn. Если оба пустые, выбрасывается RequestValidationException.

DTO и маппинг

ResponseMapper строит DTO через Reflection-конструктор и имена параметров.

• скалярные поля валидируются по типу
• вложенные DTO создаются рекурсивно
• массивы DTO/скаляров требуют #[ArrayOf(...)]
• все DTO-ответы оборачиваются в CollectionResponse с полями items, raw, total

CollectionResponse

Все запросы в режиме asDto() возвращают CollectionResponse:

$result = $focus->req()->inn('7707083893')->asDto()->get();

// Доступные методы:
$result->items;      // array<DTO> - массив DTO объектов
$result->raw;        // string - сырой JSON ответ
$result->total;      // int - количество элементов
$result->first();    // DTO|null - первый элемент или null
$result->toArray();  // array<DTO> - массив DTO
$result->count();    // int - количество элементов
$result->isEmpty();  // bool - проверка на пустоту
$result->isNotEmpty(); // bool - проверка на наличие данных

Пример DTO с массивом вложенных объектов:

use Ex3mm\KonturFocus\DTOs\Attributes\ArrayOf;

final readonly class ParentDto
{
    /**
     * @param array<ChildDto> $children
     */
    public function __construct(
        #[ArrayOf(ChildDto::class)]
        public array $children,
    ) {
    }
}

Ошибки и исключения

HTTP ошибки

Прочие ошибки

• NetworkException — сетевые/транспортные проблемы Guzzle
• InvalidResponseException — пустой 2xx body, не-JSON Content-Type, невалидный JSON
• DtoMappingException — mismatch типов/структуры при маппинге
• ConfigurationException — неверная конфигурация (key, base_url, logging.level, и т.д.)
• RequestValidationException — не переданы обязательные query-параметры (inn/ogrn)

Retry / Cache / Logging

Retry middleware

Повтор выполняется если:

• есть transport-исключение
• ответ 429
• ответ >= 500

Задержка рассчитывается из retry.delay_ms + retry.multiplier, с ограничением retry.max_delay_ms. Для 429 при наличии Retry-After используется значение заголовка.

Cache middleware

• кешируются только ответы со статусом 2xx
• ключ кеша нормализует query-параметры
• значение query-параметра key хешируется (sha256) и не попадает в кеш-ключ в открытом виде

Logging middleware

Поддерживаемые уровни: none, error, basic, headers, body, debug.

• в лог всегда пишется краткая строка запроса (METHOD URL)
• API ключ в query-параметре key маскируется (***)
• в зависимости от уровня добавляются заголовки и body

Где лежат схемы ответа

Схемы и описания полей лежат в директории:

• docs/endpoints/*/schema.json
• docs/endpoints/*/fields.json

DTO генерируются скриптом:

python3 scripts/generate_dtos.py

Целевая директория DTO:

• src/DTOs/Response/*

Разработка

Локальные команды:

composer test
composer phpstan
composer cs:check