Пакет · sdk-s5w

Установка и требования

SDK — библиотека без собственной конфигурации: одна команда устанавливает её, файлов настроек нет. Для работы нужны два значения от сервера S5W — его адрес и ключ бакета.

Требования

Что	Версия	Зачем
PHP	≥ 8.4	`readonly`-классы, свойства в конструкторе, перечисления
`ext-curl`	любая	весь обмен с сервером идёт через cURL, файлы отправляются через `CURLFile`
`flytachi/winter-cast`	^1.3	HTTP-клиент поверх cURL
`psr/log`	^3.0	интерфейс логгера, если вы передаёте свой
Composer	2.x	версия SDK для заголовка `User-Agent` берётся из Composer

Все зависимости, кроме самого PHP и расширения curl, Composer установит сам.

Необязательно: flytachi/winter-logger или любой другой логгер PSR-3 — если хотите видеть запросы и события загрузки в логах. SDK работает и без логгера.

Обработка картинок

Расширение gd для SDK не нужно: картинки уменьшает и перекодирует сервер S5W. SDK только передаёт параметры обработки.

Установка

bash

composer require flytachi/winter-sdk-s5w

Что получить у сервера

Значение	Где взять	Пример
Адрес сервера	у того, кто развернул S5W; это порт API (`9090`) или его домен	`https://s5.example.com`
Ключ бакета	админ-панель S5W → бакет → токены → выпустить	`s5w_9f3c…`

Адрес — со схемой, без пути и без завершающего / (лишний / SDK уберёт сам). Подробнее о развёртывании и доменах — в документации S5W.

Ключи бывают двух видов, и это определяет, что сможет SDK:

Ключ	Что открывает в SDK
FULL	всё: `check()`, `folders()`, `files()`, `uploads()`
BASIC	только `check()` и раздачу `/p/{id}`; вызовы `folders()`, `files()`, `uploads()` получат `ForbiddenException`

Для серверного приложения, которое загружает и упорядочивает файлы, нужен ключ FULL. Подробнее о ключах — в документации API.

Ключ показывается один раз

Сервер хранит только хеш ключа: потерянный ключ не восстановить, только выпустить новый. Храните его в переменных окружения, а не в коде.

Подключение в обычном PHP

php

use Flytachi\Winter\SDK\S5w\S5w;

$s5w = S5w::connect(getenv('S5W_URL'), getenv('S5W_KEY'));

$key = $s5w->check();
echo "Подключено к бакету {$key->bucket->name}\n";

Клиент не хранит состояния между вызовами, поэтому создайте его один раз и используйте везде. Тонкая настройка — таймауты, повторы, порог загрузки частями — задаётся через S5wConfig, см. справочник.

Подключение в Winter

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

main/Configuration/S5wConfiguration.php

<?php

declare(strict_types=1);

namespace Main\Configuration;

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;
use Flytachi\Winter\SDK\S5w\S5w;
use Flytachi\Winter\SDK\S5w\S5wConfig;

#[Configuration]
final class S5wConfiguration
{
  #[Bean]
  public function s5w(
      #[Value('S5W_URL')] string $url,
      #[Value('S5W_KEY')] string $key,
  ): S5w {
      return new S5w(
          new S5wConfig($url, $key),
          logger: LoggerFactory::getLogger('S5W'),
      );
  }
}

.env

S5W_URL=https://s5.example.com
S5W_KEY=s5w_9f3c…

После этого клиент внедряется в любой сервис или контроллер:

php

#[Autowired]
private S5w $s5w;

Несколько бакетов, логирование и другие варианты — в руководстве Интеграция с Winter.

Проверка

Самая короткая проверка, что адрес и ключ верны, — вызвать check():

php

$key = $s5w->check();

$key->bucket->name;       // "media"
$key->access->name;       // "FULL"
$key->storage->free;      // 467587072 — байт свободно

Что произошло	Что это значит
вернулся `KeyInfo`	всё в порядке
`UnauthorizedException`	ключ неизвестен серверу — проверьте значение
`ForbiddenException`	ключ отключён или истёк — нужен новый
`TransportException`	сервер недоступен — проверьте адрес и сеть
`ResponseException`	по адресу отвечает не S5W (например, страница ошибки прокси)

Дальше

Быстрый старт — первый сквозной сценарий
Модель работы — как устроен SDK