Пакет · sdk-s5w

Справочник API

Все публичные классы и методы SDK: сигнатуры, параметры, возвращаемые значения и исключения. Поля возвращаемых объектов описаны на странице Сущности, перечисления и ImageOptions — на странице Опции и перечисления, классы ошибок — в разделе Исключения.

Пространство имён Flytachi\Winter\SDK\S5wПакет flytachi/winter-sdk-s5w

Общие правила

Все методы, которые ходят на сервер, могут бросить TransportException (сервер не ответил) и ResponseException (ответ не похож на ответ S5W), а также UnauthorizedException и ForbiddenException, если ключ не подходит. В разделах «Ошибки» ниже перечислено только то, что характерно для конкретного метода.

`S5w`

Клиент одного бакета и точка входа в SDK. Финальный класс; один экземпляр соответствует одному ключу и одному бакету. Не хранит состояния между вызовами, поэтому один объект можно использовать во всём приложении.

`S5w::__construct()`

Создаёт клиент по готовой конфигурации.

Используйте конструктор, когда нужно задать что-то кроме адреса и ключа: таймауты, повторы, свой HTTP-клиент. Для простого случая короче S5w::connect().

Синтаксис

php

public function __construct(
  S5wConfig $config,
  ?CastClient $client = null,
  ?LoggerInterface $logger = null,
)

Параметры

$config — адрес сервера, ключ и параметры передачи. См. S5wConfig.

$client — свой HTTP-клиент Flytachi\Winter\Cast\Common\CastClient, если нужны свои middleware, прокси или опции cURL. По умолчанию SDK создаёт клиент сам с таймаутами из $config.

$logger — логгер PSR-3. Получает по строке на каждый запрос (уровень debug) и события загрузки частями. По умолчанию не пишется ничего. Ключ в лог не попадает. См. HTTP и логирование.

Пример

php

use Flytachi\Winter\SDK\S5w\S5w;
use Flytachi\Winter\SDK\S5w\S5wConfig;

$s5w = new S5w(
  new S5wConfig('https://s5.example.com', 's5w_9f3c…', timeout: 30, retries: 3),
  logger: $logger,
);

`S5w::connect()`

Создаёт клиент по адресу и ключу с настройками по умолчанию.

Синтаксис

php

public static function connect(
  string $baseUrl,
  string $apiKey,
  ?LoggerInterface $logger = null,
): S5w

Параметры

$baseUrl — адрес сервера со схемой: https://s5.example.com. Завершающий / убирается.

$apiKey — ключ бакета, s5w_….

$logger — необязательный логгер, как в конструкторе.

Возвращает

Новый S5w.

Ошибки

S5wException — адрес без http:// или https://, пустой ключ.

Пример

php

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

`S5w::check()`

Проверяет ключ и сообщает, что за ним стоит: бакет, уровень доступа, срок ключа и место.

Единственный метод, доступный и ключу BASIC. Вызывайте его при старте приложения и из проверки здоровья: он отличает «ключ не работает» (исключение ApiException) от «сервер недоступен» (TransportException).

Синтаксис

php

public function check(): KeyInfo

Возвращает

KeyInfo — бакет, доступ, срок ключа, место.

Ошибки

UnauthorizedException — ключ неизвестен серверу.

ForbiddenException — ключ отключён или истёк.

Пример

php

$key = $s5w->check();

$key->bucket->id;          // "3f9a1c62-58ad-4b7e-9c31-0f2d5a6b7c81"
$key->bucket->name;        // "media"
$key->access;              // TokenAccess::FULL
$key->expiresAt;           // DateTimeImmutable или null — ключ бессрочный
$key->storage->free;       // 467587072

`S5w::isValid()`

Проверяет ключ без исключения: true, если ключ рабочий.

Возвращает false только если сервер отказал ключу (401 или 403). Если сервер недоступен, исключение TransportException всё равно бросается: «не удалось узнать» — не то же, что «нет».

Синтаксис

php

public function isValid(): bool

Пример

php

if (!$s5w->isValid()) {
  $logger->critical('Ключ S5W отклонён — нужен новый');
}

`S5w::folders()`, `S5w::files()`, `S5w::uploads()`

Возвращают ресурсы для работы с папками, файлами и загрузкой частями.

Ресурс создаётся при первом вызове и дальше переиспользуется; вызывать метод можно сколько угодно раз. Всем трём нужен ключ FULL — с ключом BASIC их методы получат ForbiddenException.

Синтаксис

php

public function folders(): Folders
public function files(): Files
public function uploads(): Uploads

`S5w->config()`

Возвращает конфигурацию клиента.

Синтаксис

php

public function config(): S5wConfig

`S5wConfig`

Адрес сервера, ключ и параметры передачи. Неизменяемый объект: методы with*() возвращают копию. Бакет здесь не задаётся — его определяет ключ.

`S5wConfig::__construct()`

Создаёт конфигурацию и проверяет значения.

Синтаксис

php

public function __construct(
  string $baseUrl,
  string $apiKey,
  int $timeout = 15,
  int $connectTimeout = 5,
  int $retries = 1,
  int $transferTimeout = 300,
  int $chunkThreshold = 16 * 1024 * 1024,
  ?string $userAgent = null,
)

Параметры

Параметр	Тип	По умолчанию	Описание
`$baseUrl`	`string`	—	адрес сервера со схемой; пробелы и завершающий `/` убираются
`$apiKey`	`string`	—	ключ бакета; пробелы по краям убираются
`$timeout`	`int`	`15`	секунд на обычный запрос к API
`$connectTimeout`	`int`	`5`	секунд на установку соединения
`$retries`	`int`	`1`	попыток при сетевом сбое (отказ соединения, таймаут); `1` — без повторов
`$transferTimeout`	`int`	`300`	секунд на запрос, который передаёт байты файла: загрузка одним запросом, одна часть, сборка файла
`$chunkThreshold`	`int`	`16777216` (16 МиБ)	файлы больше этого размера `files()->upload()` отправляет частями
`$userAgent`	`?string`	`null`	заменяет заголовок `User-Agent` по умолчанию `WinterSDK/{версия}`

$retries действует на обычные вызовы API. На загрузку одним запросом он не действует никогда: если первая попытка на самом деле дошла, повтор сохранил бы файл дважды. Открытие сессии загрузки частями тоже не повторяется. У отправки частей свои повторы — до Uploads::ATTEMPTS раз на часть.

$chunkThreshold можно задать от 1 байта до Files::SINGLE_REQUEST_LIMIT — больше сервер не примет одним запросом.

Ошибки

S5wException — адрес без http:// или https://, пустой ключ, таймаут или число попыток меньше 1, chunkThreshold вне допустимых границ.

Пример

php

$config = new S5wConfig(
  'https://s5.example.com',
  's5w_9f3c…',
  timeout: 30,
  retries: 3,
  transferTimeout: 900,
);

`S5wConfig::with*()`

Возвращают копию конфигурации с изменённым значением; исходный объект не меняется.

Синтаксис

php

public function withTimeout(int $seconds, ?int $connectSeconds = null): S5wConfig
public function withTransferTimeout(int $seconds): S5wConfig
public function withChunkThreshold(int $bytes): S5wConfig
public function withRetries(int $attempts): S5wConfig
public function withUserAgent(string $userAgent): S5wConfig

Параметры

withTimeout() меняет timeout и, если передан второй аргумент, connectTimeout. Остальные методы меняют одноимённый параметр. Значения проверяются так же, как в конструкторе.

Пример

php

$config = (new S5wConfig($url, $key))
  ->withTimeout(30, 10)
  ->withRetries(3)
  ->withUserAgent('bravo-mobile/2.3');

Свойства и отладочный вывод

Все параметры доступны как публичные свойства только для чтения: $config->baseUrl, $config->timeout и т.д.

var_dump() и print_r() показывают ключ сокращённым — s5w_…aaaa, — чтобы он не попал в отладочный вывод и логи целиком.

`Folders`

Папки бакета, /v1/folders. Получается через $s5w->folders(). Нужен ключ FULL.

Папка адресуется по имени. Имя — 1–100 символов: буквы, цифры, пробел, ., _, -, первый символ — буква или цифра; уникально в бакете. В адресе запроса SDK кодирует имя сам.

`Folders::list()`

Возвращает одну страницу папок.

Синтаксис

php

public function list(int $page = 1, int $limit = 25, ?string $search = null): Page

Параметры

$page — номер страницы, с 1.

$limit — размер страницы, от 1 до 100.

$search — часть имени для поиска; null — без фильтра.

Возвращает

Page<Folder>.

Ошибки

ValidationException — $limit или $page вне границ.

Пример

php

$page = $s5w->folders()->list(limit: 10, search: 'user');

foreach ($page as $folder) {
  echo $folder->name, "\n";
}
echo "Всего: {$page->total}\n";

`Folders::all()`

Перебирает все папки, запрашивая страницы по мере обхода.

Синтаксис

php

public function all(?string $search = null, int $pageSize = 100): \Generator

Параметры

$search — часть имени, как в list().

$pageSize — сколько папок брать за один запрос, от 1 до 100.

Возвращает

Generator<int, Folder>. Следующая страница запрашивается, когда закончилась текущая.

Пример

php

foreach ($s5w->folders()->all() as $folder) {
  echo "{$folder->name}: {$folder->retention->name}\n";
}

`Folders::get()`

Возвращает папку по имени.

Синтаксис

php

public function get(string $name): Folder

Параметры

$name — имя папки.

Возвращает

Folder.

Ошибки

NotFoundException — папки с таким именем нет.

`Folders::find()`, `Folders::exists()`

То же, что get(), но без исключения при отсутствии папки.

Синтаксис

php

public function find(string $name): ?Folder
public function exists(string $name): bool

Возвращает

find() — Folder или null. exists() — true, если папка есть.

`Folders::create()`

Создаёт папку.

Синтаксис

php

public function create(
  string $name,
  bool $public = false,
  Retention $retention = Retention::NONE,
): Folder

Параметры

$name — имя новой папки.

$public — true: файлы внутри доступны по publicUrl без ключа. Файлы, загруженные в публичную папку, публичны с момента загрузки.

$retention — срок хранения файлов: через это время после создания файл удаляется сам. Очистка идёт раз в пять минут. См. Retention.

Возвращает

Созданную Folder.

Ошибки

ConflictException — имя занято.

ValidationException — имя не подходит под правила.

Пример

php

use Flytachi\Winter\SDK\S5w\Enum\Retention;

$s5w->folders()->create('avatars', public: true);
$s5w->folders()->create('tmp-exports', retention: Retention::WEEK);

`Folders::ensure()`

Возвращает папку, если она есть, или создаёт её.

Сначала ищет папку по имени. Если папка найдена, возвращает её без изменений — $public и $retention к ней не применяются. Если нет — создаёт с этими настройками. Если папку успел создать кто-то другой между поиском и созданием, читает её ещё раз и возвращает.

Синтаксис

php

public function ensure(
  string $name,
  bool $public = false,
  Retention $retention = Retention::NONE,
): Folder

Параметры

Те же, что у create(); $public и $retention используются только при создании.

Возвращает

Существующую или созданную Folder.

Пример

php

$avatars = $s5w->folders()->ensure('avatars', public: true);

`Folders::update()`

Изменяет папку; меняется только то, что передано.

Сервер принимает папку целиком, поэтому если $public или $retention не переданы, SDK сначала читает текущую папку и подставляет её значения — это два запроса. Если переданы оба, запрос один.

Изменения действуют на файлы внутри: смена $public переписывает флаг у каждого файла, смена $retention пересчитывает срок каждого файла от даты его создания — переход с YEAR на DAY может удалить файлы старше суток при ближайшей очистке.

Синтаксис

php

public function update(
  string $name,
  ?string $rename = null,
  ?bool $public = null,
  ?Retention $retention = null,
): Folder

Параметры

$name — текущее имя папки.

$rename — новое имя; null — оставить.

$public — новая видимость; null — оставить.

$retention — новый срок хранения; null — оставить.

Возвращает

Изменённую Folder.

Ошибки

NotFoundException — папки нет. ConflictException — новое имя занято другой папкой.

Пример

php

$s5w->folders()->update('avatars', public: false);
$s5w->folders()->update('tmp-exports', retention: Retention::DAY);

`Folders::rename()`

Переименовывает папку; видимость и срок хранения остаются.

Синтаксис

php

public function rename(string $name, string $newName): Folder

Ошибки

NotFoundException — папки нет. ConflictException — $newName занято.

`Folders::setCache()`

Задаёт заголовок Cache-Control, с которым сервер раздаёт файлы папки.

Изменение действует со следующего запроса файла; копии, которые уже лежат в CDN, сохраняют старый заголовок до истечения.

Синтаксис

php

public function setCache(string $name, ?int $maxAge, ?CacheVisibility $visibility): Folder

Параметры

$name — имя папки.

$maxAge — max-age в секундах, от 0 до 31536000 (год); null — взять у бакета.

$visibility — кто может кэшировать: см. CacheVisibility; null — взять у бакета.

Отправляются оба значения, поэтому чтобы изменить одно, второе передайте текущим.

Возвращает

Folder с новой политикой в поле cache.

Пример

php

use Flytachi\Winter\SDK\S5w\Enum\CacheVisibility;

$s5w->folders()->setCache('avatars', 86400, CacheVisibility::SHARED);

`Folders::resetCache()`

Убирает политику кэша папки — дальше действует политика бакета. То же, что setCache($name, null, null).

Синтаксис

php

public function resetCache(string $name): Folder

`Folders::delete()`

Удаляет папку вместе со всеми файлами внутри. Отменить нельзя.

Синтаксис

php

public function delete(string $name): void

Ошибки

NotFoundException — папки уже нет.

`Files`

Файлы бакета, /v1/files. Получается через $s5w->files(). Нужен ключ FULL.

Методы, которые работают с одним файлом, принимают его id (16 символов A-Za-z0-9_-) или сам объект File. Строку, которая не может быть id, SDK отклоняет без запроса — как будто файла нет. Параметр folder: принимает имя папки или объект Folder.

php

public const int SINGLE_REQUEST_LIMIT = 33488896;   // 32 МиБ − 64 КиБ

SINGLE_REQUEST_LIMIT — самый большой файл, который можно отправить одним запросом: сервер ограничивает тело запроса 32 МиБ, остаток уходит на служебную часть multipart.

`Files::get()`

Возвращает файл по id.

Объект тот же, что после загрузки, но поле processed равно null — отчёт об обработке картинки сервер не хранит.

Синтаксис

php

public function get(string|File $id): File

Параметры

$id — id файла или объект File (чтобы перечитать его).

Возвращает

File.

Ошибки

NotFoundException — файла нет в этом бакете. Файл из чужого бакета выглядит так же. Строка неверного формата — тот же ответ, без запроса к серверу.

Пример

php

$file = $s5w->files()->get('FXOkqegbdrNRWQgc');
$file = $s5w->files()->get($file);   // перечитать

`Files::find()`, `Files::exists()`

То же, что get(), но без исключения, если файла нет (в том числе при неверном формате id).

Синтаксис

php

public function find(string|File $id): ?File
public function exists(string|File $id): bool

Пример

php

$file = $s5w->files()->find($id);
if ($file === null) {
  return ResponseEntity::notFound();
}

`Files::list()`

Возвращает одну страницу файлов с фильтрами и сортировкой.

Синтаксис

php

public function list(
  int $page = 1,
  int $limit = 25,
  ?string $search = null,
  string|Folder|null $folder = null,
  FileSort $sort = FileSort::CREATED,
  SortDirection $direction = SortDirection::DESC,
): Page

Параметры

$page — номер страницы, с 1.

$limit — размер страницы, от 1 до 100.

$search — часть имени, без учёта регистра; null или '' — без фильтра.

$folder — где искать: null — во всём бакете; имя или Folder — в одной папке; Folder::ROOT — только файлы без папки.

$sort — поле сортировки, см. FileSort.

$direction — SortDirection::DESC (по умолчанию) или ASC.

Возвращает

Page<File>.

Ошибки

ValidationException — папки нет, $limit или $page вне границ.

Пример

php

use Flytachi\Winter\SDK\S5w\Enum\FileSort;

$page = $s5w->files()->list(folder: 'docs', search: 'invoice', sort: FileSort::SIZE);

`Files::all()`

Перебирает все файлы под фильтром, запрашивая страницы по мере обхода.

Синтаксис

php

public function all(
  ?string $search = null,
  string|Folder|null $folder = null,
  FileSort $sort = FileSort::CREATED,
  SortDirection $direction = SortDirection::DESC,
  int $pageSize = 100,
): \Generator

Параметры

Те же, что у list(), без номера страницы. $pageSize — файлов за один запрос, от 1 до 100.

Возвращает

Generator<int, File>.

Пример

php

foreach ($s5w->files()->all(folder: Folder::ROOT) as $file) {
  echo "{$file->name} публичный в корне\n";
}

`Files::upload()`

Загружает файл с диска.

Способ выбирается по размеру. До S5wConfig::$chunkThreshold (16 МиБ по умолчанию) включительно — одним запросом POST /v1/files. Больше — частями через Uploads::send(): с повтором оборванных частей и проверкой по хешу, нет ли такого содержимого в бакете. Результат одинаковый. Для прогресса и id сессии вызывайте uploads()->send() сами.

Синтаксис

php

public function upload(
  string|\SplFileInfo $file,
  string|Folder|null $folder = null,
  ?string $name = null,
  ?ImageOptions $imageOptions = null,
): File

Параметры

$file — путь к файлу или SplFileInfo. Файл должен существовать и читаться.

$folder — папка (имя или Folder); null — корень бакета. Файл в корне публичный.

$name — имя в хранилище; null — имя исходного файла. Если такое имя в папке уже есть, сервер сохранит файл как name (1).ext. Расширение сервер приводит к реальному типу содержимого. Загружаете временный файл (например, tmp_name из запроса) — передайте здесь исходное имя, иначе сохранится временное.

$imageOptions — уменьшить или перекодировать картинку, см. ImageOptions. Только для картинок.

Возвращает

File с заполненным полем processed.

Ошибки

S5wException — файл не найден или не читается (до запроса).

ValidationException — папки нет; неверные опции картинки; опции переданы для файла, который не картинка.

PayloadTooLargeException — квота бакета заполнена.

Для больших файлов — также исключения Uploads::send().

Пример

php

$file = $s5w->files()->upload(
  $upload['tmp_name'],
  folder: 'avatars',
  name: $upload['name'],
  imageOptions: ImageOptions::webp(80)->fit(512, 512),
);

Результат

php

$file->name;                    // "me.webp"
$file->content->mime;           // "image/webp"
$file->processed->operations;   // ["resize:512x384", "encode:webp@80"]

`Files::uploadContent()`

Загружает байты из памяти.

Для данных, которых нет на диске: сгенерированный документ, картинка из base64, экспорт. Способ выбирается по размеру так же, как в upload().

Синтаксис

php

public function uploadContent(
  string $content,
  string $name,
  string|Folder|null $folder = null,
  ?ImageOptions $imageOptions = null,
): File

Параметры

$content — байты файла.

$name — имя в хранилище, с расширением. Для текстовых форматов (.csv, .md, .yaml) сервер берёт тип из расширения, потому что по содержимому они неотличимы от текста.

$folder и $imageOptions — как в upload().

Возвращает

File.

Ошибки

Как у upload(), кроме ошибки чтения файла.

Пример

php

$file = $s5w->files()->uploadContent($pdf, "invoice-{$id}.pdf", folder: 'invoices');

`Files::rename()`

Переименовывает файл; папка остаётся прежней.

Id не меняется, поэтому все адреса и временные ссылки продолжают работать. Имя сохраняется как передано: расширение не проверяется и не добавляется. Сервер принимает имя и папку вместе, поэтому SDK сначала читает файл — это два запроса.

Синтаксис

php

public function rename(string|File $id, string $name): File

Параметры

$id — id файла или File.

$name — новое имя, 1–255 символов, уникальное в папке.

Возвращает

Изменённый File.

Ошибки

NotFoundException — файла нет. ConflictException — имя в папке занято. ValidationException — пустое или слишком длинное имя.

Пример

php

$file = $s5w->files()->rename($file, 'Q4 report.pdf');

`Files::move()`

Переносит файл в другую папку или в корень; имя остаётся прежним.

Папка назначения определяет новые правила файла: в публичной папке он станет публичным, в приватной — приватным, срок хранения папки применится от даты создания файла. Корень делает файл публичным. SDK сначала читает файл — это два запроса.

Синтаксис

php

public function move(string|File $id, string|Folder $folder): File

Параметры

$id — id файла или File.

$folder — папка назначения, обязательно: имя или Folder; Folder::ROOT или '' — корень. null не принимается, чтобы перенос в публичный корень нельзя было сделать случайно.

Возвращает

Перенесённый File.

Ошибки

NotFoundException — файла нет. ValidationException — папки нет. ConflictException — в папке назначения есть файл с таким именем.

Пример

php

$file = $s5w->files()->move($file, 'archive');
$file = $s5w->files()->move($file, Folder::ROOT);

`Files::update()`

Задаёт имя и папку одним запросом, ничего не читая заранее.

Итог — ровно то, что передано, поэтому изменение, сделанное кем-то другим между чтением и записью, не откатится. Используйте, когда известны оба значения или нужно сделать оба изменения сразу. Чтобы оставить папку прежней, используйте rename().

Синтаксис

php

public function update(string|File $id, string $name, string|Folder $folder): File

Параметры

$id — id файла или File.

$name — имя, 1–255 символов, уникальное в папке назначения.

$folder — папка назначения, обязательно; Folder::ROOT или '' — корень (файл станет публичным). null не принимается.

Возвращает

Изменённый File.

Ошибки

Как у move().

Пример

php

$file = $s5w->files()->update($file, 'Q4-final.pdf', 'archive');

`Files::delete()`

Удаляет файл.

Файл сразу пропадает из всех адресов раздачи, временные ссылки на него начинают отвечать 404. Если такое же содержимое есть у другого файла, тот не затрагивается.

Синтаксис

php

public function delete(string|File $id): void

Ошибки

NotFoundException — файла нет. Удаление не идемпотентно: при повторе после обрыва связи 404 означает «уже удалено».

`Uploads`

Загрузка частями, /v1/uploads. Получается через $s5w->uploads(). Нужен ключ FULL.

Части — от 4 до 16 МиБ (последняя может быть меньше), строго по порядку. Незавершённая сессия живёт 24 часа после последней части и не занимает места в квоте, пока не завершена.

php

public const int ATTEMPTS = 3;   // попыток на часть и на сборку при сетевом сбое

Методы start(), append(), status(), complete() и abort() — по одному запросу на каждый. send(), sendContent() и resume() выполняют всю загрузку. Методы, которые принимают сессию, принимают и её id строкой.

`Uploads::start()`

Открывает сессию загрузки.

Всё, что сервер может отклонить, он отклоняет здесь, до передачи байтов: нет папки, размер не помещается в квоту, на диске нет места. Если передан $sha256 содержимого, которое в бакете уже есть, сервер сразу создаёт файл: у ответа isDeduplicated() равно true, а поле file заполнено. Запрос не повторяется при сетевом сбое — с хешем он мог бы создать файл дважды.

Синтаксис

php

public function start(
  string $name,
  int $size,
  string|Folder|null $folder = null,
  ?string $sha256 = null,
  ?ImageOptions $imageOptions = null,
): UploadSession

Параметры

$name — имя в хранилище, 1–255 символов.

$size — точный размер в байтах. Обязателен для сервера: если переданных байтов окажется другое количество, файл не будет принят.

$folder — папка; null — корень.

$sha256 — SHA-256 содержимого, 64 шестнадцатеричных символа. Включает дедупликацию и проверяется при complete(). С $imageOptions передавать не стоит.

$imageOptions — обработка картинки, применяется при complete().

Возвращает

UploadSession.

Ошибки

ValidationException — папки нет, неверные опции картинки. PayloadTooLargeException — размер не помещается в квоту. ServerException (507) — на диске сервера нет места.

Пример

php

$session = $s5w->uploads()->start('video.mp4', filesize($path), folder: 'videos');

`Uploads::append()`

Отправляет следующую часть.

Если передана сессия, SDK добавляет заголовок Upload-Offset с её смещением: сервер сверит его со своим и при расхождении ответит 409 вместо того, чтобы приклеить часть не туда.

Синтаксис

php

public function append(
  string|UploadSession $session,
  string $chunk,
  ?int $offset = null,
): UploadSession

Параметры

$session — сессия или её id.

$chunk — байты части: 4–16 МиБ, меньше — только последняя.

$offset — с какого байта начинается часть. По умолчанию — offset переданной сессии; если передан id строкой и $offset не задан, проверки смещения нет — часть дописывается в конец.

Возвращает

Новую UploadSession с новым offset.

Ошибки

ConflictException — смещение не совпало с серверным; узнайте настоящее через status(). ApiException (400) — пустая часть или меньше 4 МиБ, но не последняя. PayloadTooLargeException — часть больше 16 МиБ или выходит за заявленный размер. NotFoundException — сессии нет.

`Uploads::status()`

Спрашивает сервер, сколько байт он уже получил.

Синтаксис

php

public function status(string|UploadSession $session): UploadSession

Возвращает

UploadSession с серверным offset.

Ошибки

NotFoundException — сессии нет: завершена, отменена или удалена через 24 часа.

`Uploads::complete()`

Превращает полученные байты в файл.

Сервер проверяет хеш (если он был передан), применяет обработку картинки и создаёт файл. Только после этого файл появляется в бакете; сессия перестаёт существовать.

Синтаксис

php

public function complete(string|UploadSession $session): File

Возвращает

File — такой же, как после обычной загрузки.

Ошибки

ConflictException — получены не все байты; сессия остаётся открытой. ValidationException — данные не совпали с заявленным sha256; сессия удаляется.

`Uploads::abort()`

Отменяет сессию и удаляет полученные байты. Необязательно: брошенная сессия удаляется сама через 24 часа.

Синтаксис

php

public function abort(string|UploadSession $session): void

Ошибки

NotFoundException — сессии уже нет.

`Uploads::send()`

Загружает файл с диска частями от начала до конца.

Сначала считает SHA-256 файла (если не отключено) — содержимое, которое в бакете уже есть, не передаётся вовсе. Потом открывает сессию и отправляет части размером, который просит сервер. Оборванная часть повторяется до ATTEMPTS раз с паузами 1 и 2 секунды; перед каждым повтором SDK спрашивает сервер, сколько тот получил, поэтому ничего не отправляется дважды и не теряется. В конце собирает файл. Устройство — в разделе Конвейер загрузки.

Синтаксис

php

public function send(
  string|\SplFileInfo $file,
  string|Folder|null $folder = null,
  ?string $name = null,
  ?ImageOptions $imageOptions = null,
  bool $deduplicate = true,
  ?callable $onStart = null,
  ?callable $onProgress = null,
): File

Параметры

$file — путь к файлу или SplFileInfo.

$folder — папка; null — корень.

$name — имя в хранилище; null — имя файла.

$imageOptions — обработка картинки при сборке.

$deduplicate — true: посчитать хеш и не передавать известное содержимое. С $imageOptions хеш не считается никогда.

$onStart — callable(UploadSession $session): void. Вызывается один раз сразу после открытия сессии, до первого байта. Здесь сохраняют $session->id, чтобы продолжить после перезапуска. При дедупликации не вызывается.

$onProgress — callable(int $sent, int $total): void. $sent — сколько байт уже на сервере, $total — размер файла. Вызывается в начале ($sent = 0), после каждой подтверждённой части и после восстановления, если часть дошла; при дедупликации — один раз с $sent === $total.

Возвращает

File.

Ошибки

UploadInterruptedException — попытки кончились; сессия сохранена, продолжите через resume().

UploadUnconfirmedException — сборка запрошена, но ответ потерялся, а сессии уже нет: файл, возможно, создан, id неизвестен.

ApiException и наследники — сервер отклонил данные (папка, квота, опции); сессия отменена.

S5wException — файл не читается или изменился во время загрузки.

Пример

php

$file = $s5w->uploads()->send(
  '/backups/db.sql',
  folder: 'backups',
  onStart: fn(UploadSession $s) => $job->saveUploadId($s->id),
  onProgress: fn(int $sent, int $total) => printf("%d%%\n", $sent * 100 / $total),
);

`Uploads::sendContent()`

То же, что send(), но для байтов в памяти.

Синтаксис

php

public function sendContent(
  string $content,
  string $name,
  string|Folder|null $folder = null,
  ?ImageOptions $imageOptions = null,
  bool $deduplicate = true,
  ?callable $onStart = null,
  ?callable $onProgress = null,
): File

Параметры

$content — байты. $name — имя в хранилище, обязательно. Остальные — как в send().

`Uploads::resume()`

Продолжает прерванную загрузку того же файла.

Спрашивает сервер, сколько байт уже получено, проверяет, что размер файла совпадает с заявленным при старте, и отправляет остаток — с теми же повторами, что send(). Если сервер уже получил всё, сразу собирает файл.

Синтаксис

php

public function resume(
  string|UploadSession $session,
  string|\SplFileInfo $file,
  ?callable $onProgress = null,
): File

Параметры

$session — сессия или её id: из UploadInterruptedException::sessionId() или сохранённый в onStart.

$file — тот же файл, с которым начиналась загрузка.

$onProgress — как в send(); первый вызов сообщает, с какого места продолжаем.

Возвращает

File.

Ошибки

NotFoundException — сессии нет (завершена, отменена или удалена через 24 часа): начните заново. S5wException — размер файла не совпадает с сессией. Плюс ошибки send().

Пример

php

try {
  $file = $s5w->uploads()->send($path);
} catch (UploadInterruptedException $e) {
  $file = $s5w->uploads()->resume($e->sessionId(), $path);
}

Справочник API

S5w

S5w::__construct()

S5w::connect()

S5w::check()

S5w::isValid()

S5w::folders(), S5w::files(), S5w::uploads()

S5w->config()

S5wConfig

S5wConfig::__construct()

S5wConfig::with*()

Свойства и отладочный вывод

Folders

Folders::list()

Folders::all()

Folders::get()

Folders::find(), Folders::exists()

Folders::create()

Folders::ensure()

Folders::update()

Folders::rename()

Folders::setCache()

Folders::resetCache()

Folders::delete()

Files

Files::get()

Files::find(), Files::exists()

Files::list()

Files::all()

Files::upload()

Files::uploadContent()

Files::rename()

Files::move()

Files::update()

Files::delete()

Uploads

Uploads::start()

Uploads::append()

Uploads::status()

Uploads::complete()

Uploads::abort()

Uploads::send()

Uploads::sendContent()

Uploads::resume()

`S5w`

`S5w::__construct()`

`S5w::connect()`

`S5w::check()`

`S5w::isValid()`

`S5w::folders()`, `S5w::files()`, `S5w::uploads()`

`S5w->config()`

`S5wConfig`

`S5wConfig::__construct()`

`S5wConfig::with*()`

`Folders`

`Folders::list()`

`Folders::all()`

`Folders::get()`

`Folders::find()`, `Folders::exists()`

`Folders::create()`

`Folders::ensure()`

`Folders::update()`

`Folders::rename()`

`Folders::setCache()`

`Folders::resetCache()`

`Folders::delete()`

`Files`

`Files::get()`

`Files::find()`, `Files::exists()`

`Files::list()`

`Files::all()`

`Files::upload()`

`Files::uploadContent()`

`Files::rename()`

`Files::move()`

`Files::update()`

`Files::delete()`

`Uploads`

`Uploads::start()`

`Uploads::append()`

`Uploads::status()`

`Uploads::complete()`

`Uploads::abort()`

`Uploads::send()`

`Uploads::sendContent()`

`Uploads::resume()`