magdv/mt-forwarder-registry-api

PHP 8.3 клиент к MT Forwarder Registry API (контракт 2.0.0).

Покрывает только публичные read-эндпоинты system + registry (/health, /ready, /v1/meta, /v1/forwarders*). QA-эндпоинты (/qa/v1/*) в пакет не входят.

Сгенерированный код в src/ закоммичен — для установки потребителю не нужны Docker/Java.

Установка

composer require magdv/mt-forwarder-registry-api:^2.0

Репозиторий: github.com/magdv/mt-forwarder-registry-api-php-wrapper.

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

use MagDV\MtForwarderRegistry\Configuration;
use MagDV\MtForwarderRegistry\Api\RegistryApi;
use MagDV\MtForwarderRegistry\Api\SystemApi;
use MagDV\MtForwarderRegistry\ApiException;
use MagDV\MtForwarderRegistry\Model\Health;

$config = Configuration::getDefaultConfiguration()
    ->setHost('https://forwarder-registry.log.magdv.com');
    // defaults: timeout=1.0s, connect_timeout=0.5s
    // ->setTimeout(2.0)->setConnectTimeout(1.0);

$system = new SystemApi(null, $config);
$health = $system->getHealth(); // liveness: обычно 200

// getReady(): при неготовности сервис отвечает 503 —
// клиент бросает ApiException; тело Health в getResponseObject().
try {
    $ready = $system->getReady();
} catch (ApiException $e) {
    if ($e->getCode() === 503) {
        /** @var Health|null $body */
        $body = $e->getResponseObject();
        // $body?->getReady() === false
    }
    throw $e;
}

$api = new RegistryApi(null, $config);
$meta = $api->getMeta();
$list = $api->listForwarders(inn: '7707083893', deleted: 'false', limit: 50);
$byInn = $api->getForwardersByINN('7707083893');
$one = $api->getForwarderByRegistryNumber('GL-B044-00112-00/00000051');

Auth не требуется (публичный read API).

Таймауты HTTP

По умолчанию (через Configuration):

Опция Guzzle	Метод	Default
timeout	setTimeout() / getTimeout()	1.0 сек
connect_timeout	setConnectTimeout() / getConnectTimeout()	0.5 сек

Значения применяются на каждый запрос (SystemApi / RegistryApi). Пример:

$config = Configuration::getDefaultConfiguration()
    ->setHost('https://forwarder-registry.log.magdv.com')
    ->setTimeout(3.0)
    ->setConnectTimeout(1.0);

Ошибки registry (400 / 404 / 503) тоже приходят как ApiException; типизированное тело Error — в getResponseObject().

Не используйте *Async / *AsyncWithHttpInfo. Они приходят из шаблона OpenAPI Generator as-is: при сетевых сбоях (ConnectException) rejection-handler может упасть с PHP Error вместо ApiException, а typed getResponseObject() на ошибках может отсутствовать. Поддерживаемый контракт пакета — синхронные методы (getMeta, listForwarders, …).

Номера реестра со /

Номер вида GL-B044-00112-00/00000051 валиден. Клиент кодирует / как %2F в path — сервис это поддерживает. Альтернатива: listForwarders(registry_number: '...').

Основные классы

Класс	Роль
MagDV\MtForwarderRegistry\Configuration	setHost(), setTimeout() / setConnectTimeout()
MagDV\MtForwarderRegistry\Api\SystemApi	getHealth, getReady
MagDV\MtForwarderRegistry\Api\RegistryApi	getMeta, listForwarders, getForwarderByRegistryNumber, getForwardersByINN
MagDV\MtForwarderRegistry\Model\*	Health, Meta, Forwarder, ForwarderList, Error

Синхронизация с upstream

При смене контракта API:

1. Скопировать/diff mt-forwarder-registry/api/openapi.yaml → openapi/openapi.yaml, без QA-путей, схемы QAApplyResult и тега qa. Версия info.version должна совпадать с upstream.
2. Запустить bin/generate (нужен Docker; CLI pinned: openapitools/openapi-generator-cli:v7.14.0).
3. Прогнать тесты: composer update && vendor/bin/phpunit. При bump info.version обновится artifactVersion в генерации.

Генерация пишет только в build/generated/, затем копирует src/, накладывает bin/patch-timeouts (таймауты в Configuration / API) и мержит runtime-зависимости в composer.json (php: ^8.3). README, tests/, CI не затираются.

Разработка

composer update
vendor/bin/phpunit