Пакет · cast

Интеграция с Winter

В приложении Winter клиент удобнее всего держать бином: контейнер создаст его один раз на воркер, а соединения пула будут жить, пока жив воркер.

Клиент как бин

main/Configuration/HttpConfiguration.php
<?php

declare(strict_types=1);

namespace Main\Configuration;

use Flytachi\Winter\Cast\Client\CastClient;
use Flytachi\Winter\Cast\Client\RetryPolicy;
use Flytachi\Winter\Kernel\App\Attribute\Bean;
use Flytachi\Winter\Kernel\App\Attribute\Configuration;
use Flytachi\Winter\Kernel\App\Attribute\Value;
use Flytachi\Winter\Logger\LoggerFactory;

#[Configuration]
final class HttpConfiguration
{
  #[Bean]
  public function github(#[Value('GITHUB_TOKEN')] string $token): CastClient
  {
      return CastClient::create()
          ->withBaseUrl('https://api.github.com')
          ->withBearerToken($token)
          ->withAccept('application/vnd.github+json')
          ->withUserAgent('my-app/1.0')
          ->withRetry(RetryPolicy::exponential()->withStatuses(502, 503, 504))
          ->withLogger(LoggerFactory::getLogger('github'));
  }
}
main/Services/RepoService.php
use Flytachi\Winter\Cast\Client\CastClient;
use Flytachi\Winter\DI\Attribute\Autowired;

final class RepoService
{
  #[Autowired]
  private CastClient $github;

  public function stars(string $repo): int
  {
      return $this->github->get("repos/{$repo}")->send()->throw()->json()['stargazers_count'];
  }
}

Один экземпляр на воркер

Клиент неизменяем и не хранит состояния между запросами, кроме пула соединений, а пул выдаёт каждому запросу своё соединение. Поэтому бин-«одиночка» безопасен и для многих корутин одного воркера Swoole.

Несколько клиентов

Для нескольких API объявите несколько бинов с именами и внедряйте по имени:

php
#[Configuration]
final class HttpConfiguration
{
  #[Bean(name: 'http.github')]
  public function github(#[Value('GITHUB_TOKEN')] string $token): CastClient
  {
      return CastClient::create()->withBaseUrl('https://api.github.com')->withBearerToken($token);
  }

  #[Bean(name: 'http.stripe')]
  public function stripe(#[Value('STRIPE_KEY')] string $key): CastClient
  {
      return CastClient::create()->withBaseUrl('https://api.stripe.com/v1')->withBasicAuth($key, '');
  }
}
php
use Flytachi\Winter\DI\Attribute\Inject;

final class BillingService
{
  #[Inject('http.stripe')]
  private CastClient $stripe;
}

Два бина одного типа

Когда бинов CastClient два и больше, внедрение по типу (#[Autowired]) становится ошибкой: контейнер не знает, какой выбрать. Указывайте имя через #[Inject('…')].

Свой API-клиент

Базовый класс для API-клиентов не нужен: клиент с адресом и ключом уже и есть настроенный API-клиент. Свой SDK — обычный класс, который получает CastClient:

php
final class WeatherApi
{
  public function __construct(private CastClient $http) {}

  public static function create(string $key): self
  {
      return new self(CastClient::create()
          ->withBaseUrl('https://api.weather.example/v2')
          ->withHeader('X-Api-Key', $key));
  }

  /** @return array<string, mixed> */
  public function today(string $city): array
  {
      return $this->http->get('today', ['city' => $city])->send()->throw()->jsonOrFail();
  }
}

Так получается сколько угодно экземпляров с разными ключами, клиент подменяется в тестах через withTransport(), и нет общего родителя, изменения которого ломали бы все SDK.

Логи

php
$client->withLogger(LoggerFactory::getLogger('github'));
text
[DEBUG] (github): GET https://api.github.com/repos/flytachi/winter-cast → 200 (184 ms)
[WARNING] (github): GET https://api.github.com/search/code attempt 1 failed (HTTP 503), retrying in 512 ms
[DEBUG] (github): GET https://api.github.com/search/code → 200 (1204 ms, 2 attempts)
[ERROR] (github): GET https://api.github.com/user failed after 3 attempt(s): … Could not connect to server
Уровень Когда
debug одна строка на запрос: метод, адрес, статус, время, попытки, редиректы
warning каждый повтор: номер попытки, причина, пауза
error отказ после всех попыток

В лог не попадают заголовки, тела и query: ключи из адреса не утекают. Подстановки в строке выполняет сам клиент, поэтому строки полные с любым PSR-3 логгером. Если нужен свой формат — см. Свой лог.

Фасад в приложении

Если в коде используется фасад Cast, задайте ему клиент один раз при старте приложения:

php
Cast::setClient(CastClient::create()->withUserAgent('my-app/1.0')->withTimeout(10));

Предпочтительнее всё же внедрять CastClient бином: настройки видны там, где клиент создан, и подменяются в тестах.