RUEN
Пакет · sdk-s5w

S5W SDK

S5W SDK — PHP-клиент для S5W, файлового хранилища и CDN в одном контейнере. Он превращает HTTP API сервиса в обычные вызовы методов: вы передаёте путь к файлу и получаете объект File, а SDK сам решает, отправить его одним запросом или частями, повторяет оборванные куски и сообщает о проблемах исключениями с понятным типом.

Пакет flytachi/winter-sdk-s5wPHP ≥ 8.4Сервер S5W, API v1

Скоро в SDK

Скачивание файлов — files()->download() (потоком на диск) и files()->contents() (строкой в память) — и временные ссылки — links(): выдача со сроком и лимитом скачиваний, список, отзыв по одной и всех сразу.

Пока их можно получить напрямую через API: раздача и временные ссылки. У каждого объекта File уже есть готовые адреса privateUrl и publicUrl.

Зачем нужен SDK

С API S5W можно работать и напрямую — это обычный JSON по HTTP, он описан в разделе Клиентский API. Но у каждого проекта, который так делает, рано или поздно появляется одна и та же обвязка:

  • ключ и заголовки в каждом запросе, разбор { code, message, errors } в ошибку;
  • выбор способа загрузки: до 32 МиБ — одним multipart-запросом, больше — частями через /v1/uploads, с правилами размера частей, порядком и проверкой смещения;
  • обрывы связи: понять, дошла ли часть, спросить сервер, сколько он получил, продолжить с нужного места и не загрузить файл дважды;
  • разбор ответов в объекты, даты в DateTimeImmutable, числа перечислений в имена.

SDK делает это один раз и одинаково для всех. В вашем коде остаётся то, ради чего вы обратились к хранилищу.

Как это выглядит

php
use Flytachi\Winter\SDK\S5w\S5w;

$s5w = S5w::connect('https://s5.example.com', 's5w_9f3c…');

$file = $s5w->files()->upload('/tmp/report.pdf', folder: 'docs');

$file->id;           // "FXOkqegbdrNRWQgc" — по нему файл адресуется везде
$file->privateUrl;   // https://s5.example.com/p/FXOkqegbdrNRWQgc

Тот же вызов upload() справится и с файлом в несколько гигабайт: SDK отправит его частями, переживёт обрыв связи и не станет передавать содержимое, которое в бакете уже есть. Полный сценарий — в быстром старте.

Что умеет

Возможность Где описано
Проверка ключа и свободного места: check(), isValid() Справочник API
Папки: создание, видимость, срок хранения, политика кэша Работа с папками и файлами
Загрузка с диска и из памяти, обработка картинок Загрузка файлов
Большие файлы: части, прогресс, продолжение после обрыва Большие файлы
Ручное управление загрузкой по шагам Загрузка по шагам
Список файлов: поиск, фильтр по папке, сортировка, перебор всех страниц Работа с папками и файлами
Переименование, перенос, удаление Работа с папками и файлами
Типизированные ошибки по статусу ответа Обработка ошибок
Подключение как бина Winter, несколько бакетов, логи Интеграция с Winter

Принципы

Один клиент — один бакет. Бакет определяется ключом на стороне сервера, поэтому в SDK его нигде не нужно указывать и нельзя указать неверно. Нужно несколько бакетов — создайте несколько клиентов. Подробнее — в модели работы.

Объекты вместо массивов. Каждый ответ сервера проверяется и превращается в неизменяемый объект с типизированными полями. Если сервер прислал не то, что ожидалось, вы получите одну понятную ошибку с именем поля, а не TypeError где-то глубже.

Тип исключения вместо разбора текста. Отказ сервера превращается в исключение по статусу: NotFoundException, ConflictException, ValidationException и другие. Ветвитесь по классу, а сообщение оставьте для логов.

Ключ не утекает. Ключ не попадает ни в логи, ни в var_dump() конфигурации.

Требования

PHP 8.4 и расширение curl. Подробности и подключение в Winter — на странице Установка.

Ссылки