PHPUnit, Composer и клиент к Reporting API: практика от тестов до упаковки
Клиент к внешнему Reporting API почти всегда получается тестируемым, если не смешивать HTTP, преобразование данных и бизнес-логику в одном классе. Ниже — сборка такого клиента на современном PHP: Composer, строгие типы, PHPUnit с подменой транспорта и понятная граница с SDK вендора.
Что строим и почему TDD здесь уместен
Речь о типичной задаче: приложению нужны данные из внешней системы аналитики для внутренних отчётов. У вендора есть HTTP-интерфейс, ответ приходит в виде JSON, часть параметров — из конфигурации, часть — динамическая. Соблазн написать «один класс, который всё делает» велик, но именно такой класс невозможно нормально покрыть тестами: внутри него живут сеть, разбор ответа и правила отчёта.
Рабочая схема — три слоя:
- транспорт — минимальная обёртка над HTTP-клиентом, единственное место, где реально ходят запросы;
- клиент API — формирует запрос, проверяет ответ, отдаёт нормализованный результат;
- сервис отчёта — превращает ответ в доменные структуры.
Тесты бьют по первому и второму слою без сети, а третий тестируется вообще без HTTP. Закон Деметры тут не философия, а практическое правило: класс не должен копаться во внутренностях чужих объектов, иначе моки становятся хрупкими.
Каркас проекта: Composer и строгие типы
Начните с composer.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
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
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
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.
Практический итог: чек-лист перед первым коммитом
composer.jsonс корректным PSR-4 иrequire.php: ^8.3, в каждом файлеdeclare(strict_types=1).- HTTP вынесен за интерфейс PSR-18, фабрики запросов/потоков — PSR-17, базовый URL — в конструкторе.
- Клиент API возвращает нормализованную структуру и кидает своё исключение на неожиданный формат.
- Юнит-тесты не трогают сеть; в CI гоняется
composer test, фикстуры реальных ответов лежат вtests/fixtures. - Ошибки вендора, таймауты и пустые ответы покрыты отдельными тестами.
- 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-методы статичиваются.