Сущности

Объекты, в которые SDK превращает ответы сервера. Все они неизменяемы (readonly) и описывают состояние на момент ответа; чтобы увидеть новое состояние, используйте то, что вернул метод изменения, или перечитайте объект.

Общее

Даты — DateTimeImmutable с часовым поясом сервера.

Перечисления — объекты PHP-перечислений (Retention::WEEK), а не числа. См. Опции и перечисления.

JSON. Каждая сущность реализует JsonSerializable и метод toArray(), поэтому её можно сразу отдать в ответ: ResponseEntity::ok($file). В JSON даты — строки ISO 8601 (2026-11-07T14:54:51+00:00), перечисления — имена ("WEEK"), вложенные объекты — массивы.

json_encode($folder);
// {"name":"avatars","public":true,"retention":"NONE",
//  "cache":{"maxAge":null,"visibility":null},
//  "createdAt":"2026-11-07T14:54:51+00:00","updatedAt":"2026-11-07T14:54:51+00:00"}

Проверка ответа. Если в ответе сервера нет нужного поля или у него не тот тип, SDK бросает ResponseException с путём к полю — например, S5W v1/check: bytes.quota must be int, got string.

File

Файл в бакете.

Адреса строятся от PUBLIC_BASE_URL сервера — см. настройку S5W.

File::ID_PATTERN, File::isValidId()

Формат id: /^[A-Za-z0-9_-]{16}$/. Метод проверяет только форму, а не существование файла — удобно, чтобы отсеять мусор из адреса страницы до запроса.

public const string ID_PATTERN = '/^[A-Za-z0-9_-]{16}$/';
public static function isValidId(string $id): bool

File::isValidId('FXOkqegbdrNRWQgc');   // true
File::isValidId('../etc/passwd');      // false

FileContent

Байты файла. Два файла с одинаковым содержимым ссылаются на одни и те же байты.

Processing

Что сервер сделал с картинкой при загрузке.

Методы

saved(): int — сколько байт сэкономлено: source->size - result->size. Отрицательное, если результат тяжелее; 0, если обработки не было.

ImageInfo

Folder

Папка. Один уровень, без вложенности; имя уникально в бакете.

Folder::ROOT

Корень бакета там, где ожидается папка.

public const string ROOT = '/';

Значение / не может быть именем настоящей папки, поэтому путаницы нет. Где действует:

CachePolicy

Переопределение кэша на уровне папки. Каждое поле со значением null наследуется от бакета.

Методы

isInherited(): bool — true, если оба поля null: папка ничего не переопределяет.

Page

Одна страница списка. Повторяет формат сервера { meta, data }.

Методы

hasNext(): bool — есть ли следующая страница.

isEmpty(): bool — пуста ли эта страница.

count($page) — сколько элементов на этой странице (Countable). Не путать с total.

foreach ($page as $item) — обход элементов этой страницы (IteratorAggregate).

map(callable $fn): Page — новая страница, где каждый элемент прошёл через $fn; мета сохраняется. Удобно, чтобы превратить сущности в свои DTO.

toArray() / jsonSerialize() — { meta: { current, size, total, pages, previous, next }, data: [...] }.

$page = $s5w->files()->list(limit: 10);

count($page);       // 10 — на этой странице
$page->total;       // 134 — всего
$page->hasNext();   // true

$names = $page->map(fn(File $f) => $f->name);
json_encode($names);   // {"meta":{…},"data":["a.txt","b.txt",…]}

UploadSession

Состояние загрузки частями. Каждый вызов uploads() возвращает новую сессию с текущим смещением сервера.

Методы

isDeduplicated(): bool — содержимое было в бакете, файл готов, передавать нечего.

isComplete(): bool — все байты на сервере (offset >= size), можно собирать.

remaining(): int — сколько байт осталось отправить.

KeyInfo

Ответ check(): что стоит за ключом.

Методы

expiresBefore(DateTimeInterface $at = now): bool — истечёт ли ключ к моменту $at.

if ($s5w->check()->expiresBefore(new DateTimeImmutable('+7 days'))) {
  $logger->warning('Ключ S5W истекает в течение недели');
}

BucketRef

Storage

Место в бакете, в байтах.

Методы

fits(int $bytes): bool — поместится ли ещё $bytes байт.

usage(): float — доля занятого, от 0.0 до 1.0.