PHPTime

PHPUnit, Composer и клиент к Reporting API: практика от тестов до упаковки

Клиент к внешнему Reporting API почти всегда получается тестируемым, если не смешивать HTTP, преобразование данных и бизнес-логику в одном классе. Ниже — сборка такого клиента на современном PHP: Composer, строгие типы, PHPUnit с подменой транспорта и понятная граница с SDK вендора.

Что строим и почему TDD здесь уместен

Речь о типичной задаче: приложению нужны данные из внешней системы аналитики для внутренних отчётов. У вендора есть HTTP-интерфейс, ответ приходит в виде JSON, часть параметров — из конфигурации, часть — динамическая. Соблазн написать «один класс, который всё делает» велик, но именно такой класс невозможно нормально покрыть тестами: внутри него живут сеть, разбор ответа и правила отчёта.

Рабочая схема — три слоя:

  • транспорт — минимальная обёртка над HTTP-клиентом, единственное место, где реально ходят запросы;
  • клиент API — формирует запрос, проверяет ответ, отдаёт нормализованный результат;
  • сервис отчёта — превращает ответ в доменные структуры.

Тесты бьют по первому и второму слою без сети, а третий тестируется вообще без HTTP. Закон Деметры тут не философия, а практическое правило: класс не должен копаться во внутренностях чужих объектов, иначе моки становятся хрупкими.

Каркас проекта: Composer и строгие типы

Начните с composer.json. Минимум зависимостей, аккуратные автозагрузка и скрипты — этого достаточно для библиотеки на пару сотен строк.

JSON
{
  "name": "acme/analytics-client",
  "description": "Клиент к Reporting API",
  "type": "library",
  "license": "MIT",
  "require": {
    "php": "^8.3",
    "ext-json": "*",
    "psr/http-client": "^1.0",
    "psr/http-factory": "^1.0"
  },
  "require-dev": {
    "phpunit/phpunit": "^11.0"
  },
  "autoload": {
    "psr-4": { "Acme\\Analytics\\": "src/" }
  },
  "autoload-dev": {
    "psr-4": { "Acme\\Analytics\\Tests\\": "tests/" }
  },
  "scripts": {
    "test": "phpunit --colors=always"
  }
}

В каждом PHP-файле — declare(strict_types=1);. Без него PHP 8.x всё ещё молча приводит строки к числам, а на границе с внешним API это редко заканчивается добром. Композер сам по себе не проверяет типы, поэтому не забывайте регулярно гонять статический анализатор (в require-dev его можно добавить отдельно).

Транспорт, который легко подменить

Самый частый источник боли в тестах — жёстко зашитый в код HTTP-клиент. Вместо этого объявите тонкий интерфейс, соответствующий PSR-18, и работайте против него.

PHP
<?php
declare(strict_types=1);

namespace Acme\Analytics;

use Psr\Http\Client\ClientInterface;
use Psr\Http\Message\RequestFactoryInterface;
Use Psr\Http\Message\StreamFactoryInterface;

final class HttpTransport
{
    public function __construct(
        private ClientInterface $client,
        private RequestFactoryInterface $requests,
        private StreamFactoryInterface $streams,
        private string $baseUrl,
    ) {}

    /** @return array<string, mixed> */
    public function postJson(string $path, array $payload): array
    {
        $body = $this->streams->createStream(json_encode(
            $payload,
            JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE,
        ));

        $request = $this->requests->createRequest('POST', $this->baseUrl . $path)
            ->withHeader('Content-Type', 'application/json')
            ->withBody($body);

        $response = $this->client->sendRequest($request);

        if ($response->getStatusCode() >= 400) {
            throw new ApiException('HTTP ' . $response->getStatusCode());
        }

        return json_decode(
            (string) $response->getBody(),
            associative: true,
            flags: JSON_THROW_ON_ERROR,
        );
    }
}

В тестах подставляется фейковый ClientInterface, который возвращает заранее подготовленный ResponseInterface. Объекты PSR-17 удобно брать из nyholm/psr7 или guzzlehttp/psr7 — это dev-зависимости, прод их не тянет.

Клиент API: параметры запроса и валидация ответа

Второй слой знает про вендорскую семантику: какие поля идут в теле, какие — в заголовках, что означает код ошибки. Публичный метод возвращает уже проверенный массив, а не сырой ответ.

PHP
<?php
declare(strict_types=1);

namespace Acme\Analytics;

final class ReportingClient
{
    public function __construct(private HttpTransport $transport) {}

    /**
     * @param list<string> $metrics
     * @return list<array{element: string, value: int|float}>
     */
    public function fetchDaily(string $reportSuite, array $metrics, string $date): array
    {
        $raw = $this->transport->postJson('/v2/reports', [
            'rsid'    => $reportSuite,
            'date'    => $date,
            'metrics' => $metrics,
        ]);

        $rows = $raw['report']['data'] ?? null;
        if (!is_array($rows)) {
            throw new ApiException('Неожиданная структура ответа');
        }

        return array_map(
            static fn(array $row): array => [
                'element' => (string) $row['name'],
                'value'   => is_int($row['count']) ? $row['count'] : (float) $row['count'],
            ],
            $rows,
        );
    }
}

Именно здесь удобно ловить регрессии: вендор поменял формат — падает один узкий тест, а не весь отчёт ночью в проде.

Тесты на PHPUnit: фейки вместо сети

PHPUnit 10/11 по умолчанию строже: тестовые методы — атрибуты, assertion-методы статичиваются. Ниже — тест на успешный путь и на ошибку HTTP.

PHP
<?php
declare(strict_types=1);

namespace Acme\Analytics\Tests;

use Acme\Analytics\ApiException;
use Acme\Analytics\HttpTransport;
use Acme\Analytics\ReportingClient;
use Nyholm\Psr7\HttpFactory;
use Nyholm\Psr7\Response;
use PHPUnit\Framework\Attributes\Test;
use PHPUnit\Framework\TestCase;
use Psr\Http\Client\ClientInterface;

final class ReportingClientTest extends TestCase
{
    #[Test]
    public function it_maps_rows(): void
    {
        $factory = new HttpFactory();
        $http = $this->createMock(ClientInterface::class);
        $http->method('sendRequest')->willReturn(new Response(200, [], json_encode([
            'report' => ['data' => [['name' => 'home', 'count' => '42']]],
        ])));

        $client = new ReportingClient(new HttpTransport(
            $http, $factory, $factory, 'https://example.test'
        ));

        $rows = $client->fetchDaily('shop', ['pageviews'], '2026-01-01');

        self::assertSame([['element' => 'home', 'value' => 42]], $rows);
    }

    #[Test]
    public function it_fails_on_http_error(): void
    {
        $factory = new HttpFactory();
        $http = $this->createMock(ClientInterface::class);
        $http->method('sendRequest')->willReturn(new Response(503));

        $client = new ReportingClient(new HttpTransport(
            $http, $factory, $factory, 'https://example.test'
        ));

        $this->expectException(ApiException::class);
        $client->fetchDaily('shop', ['pageviews'], '2026-01-01');
    }
}

Обратите внимание: тест не знает, что внутри PSR-18, и не пытается дотянуться до приватных методов. Это и есть тот самый «слабо связанный код», ради которого обычно и берутся за TDD.

Таблица: где что тестировать

СлойЧто проверяемЧем подменяемТип теста
HttpTransportзаголовки, тело, кодыPSR-18 клиент + PSR-17 фабрикиюнит
ReportingClientмаппинг полей, ошибки APIфейковый транспортюнит
Сервис отчётаагрегация, форматыфейковый ReportingClientюнит
Контракт с вендоромреальный формат ответазаписанный JSON-фикстуринтеграционный

Живые запросы к внешнему API держите отдельным набором, запускаемым по требованию, а не в каждом прогоне CI. Записанные ответы ловят дрейф формата без флаки-тестов.

Что осталось «так было раньше»

  • mysql_* и ereg — давно удалены; для БД берите PDO с prepared statements, для регулярок — preg_match.
  • create_function заменяется замыканием: static fn(string $x): int => strlen($x).
  • expectException в PHPUnit переехал с аннотаций на атрибуты; старые докблоки всё ещё читаются, но новые тесты так не пишут.
  • Автозагрузка через самописный spl_autoload_register в библиотеке почти всегда уступает PSR-4 через Composer: предсказуемее, кэшируется, работает с composer dump-autoload -o.

Практический итог: чек-лист перед первым коммитом

  1. composer.json с корректным PSR-4 и require.php: ^8.3, в каждом файле declare(strict_types=1).
  2. HTTP вынесен за интерфейс PSR-18, фабрики запросов/потоков — PSR-17, базовый URL — в конструкторе.
  3. Клиент API возвращает нормализованную структуру и кидает своё исключение на неожиданный формат.
  4. Юнит-тесты не трогают сеть; в CI гоняется composer test, фикстуры реальных ответов лежат в tests/fixtures.
  5. Ошибки вендора, таймауты и пустые ответы покрыты отдельными тестами.
  6. README с минимальным примером использования — библиотеку, которую нельзя показать в десяти строках, никто не возьмёт.

Смысл TDD здесь не в ритуале «сначала красный тест». Он в том, что границы между слоями приходится проводить осознанно. Как только транспорт подменяется одной строкой в тесте, рефакторинг перестаёт пугать, а внешнее API — остаётся внешним, а не размазанным по всему приложению.

Частые вопросы

Нужен ли TDD, чтобы написать клиент к внешнему API?

Не обязателен, но он заставляет сразу разделить транспорт, клиент API и бизнес-логику. Даже без строгого цикла «тест-код-рефакторинг» эти три слоя дают тестируемый код и уменьшают число хрупких моков.

Как тестировать запросы к API без сети?

Работать через PSR-18 ClientInterface и подменять его фейком, возвращающим подготовленный ResponseInterface. Для сборки запросов и потоков использовать PSR-17 фабрики. Реальные ответы вендора храните как JSON-фикстуры в отдельных интеграционных тестах.

Какие версии PHP и PHPUnit актуальны сейчас?

Ориентируйтесь на поддерживаемые ветки PHP 8.3–8.5 и PHPUnit 10/11. В PHPUnit новых версий тестовые методы помечаются атрибутами, а не аннотациями в докблоках, а assertion-методы статичиваются.

Справка по теме

Ещё в разделе «Архитектура и практика»

Инверсия управления в PHP: Голливудский принцип

Разбираем принцип инверсии управления (IoC) в современном PHP: отличие от DI, события и наблюдатели, примеры на PHP 8.3–8.5, антипаттерны и чек-лист внедрения.

8 мин

Эффективный рефакторинг PHP-кода

Практическое руководство по рефакторингу в PHP 8.3–8.5. Как зафиксировать поведение тестами, усилить типизацию, разделить обязанности и удалить мёртвый код.

7 мин

Декаплинг и фреймворки в PHP: как перестать зависеть от чужих обновлений

Как отделить бизнес-логику от фреймворка в современных PHP-проектах. Интерфейсы, DTO, адаптеры, DI-контейнеры и стратегии миграции без остановки разработки.

7 мин

Как задать вопрос по PHP, чтобы получить ответ

Как задать вопрос по PHP: соберите минимальный воспроизводимый пример, укажите версии и условия запуска, приложите текст ошибки и выберите площадку.

7 мин