Entities

The objects the SDK turns server answers into. They are all immutable (readonly) and describe the state at the moment of the answer; to see the new state, use what the changing method returned, or read the object again.

General

Dates are DateTimeImmutable with the server’s time zone.

Enums are PHP enum objects (Retention::WEEK), not numbers. See Options & enums.

JSON. Every entity implements JsonSerializable and a toArray() method, so it can go straight into a response: ResponseEntity::ok($file). In JSON, dates are ISO 8601 strings (2026-11-07T14:54:51+00:00), enums are names ("WEEK"), nested objects are arrays.

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"}

Answer checks. If the server’s answer lacks a field or has the wrong type in it, the SDK throws ResponseException with the path to the field — e.g. S5W v1/check: bytes.quota must be int, got string.

File

A file in the bucket.

The addresses are built from the server’s PUBLIC_BASE_URL — see S5W configuration.

File::ID_PATTERN, File::isValidId()

The id format: /^[A-Za-z0-9_-]{16}$/. The method checks only the shape, not whether the file exists — handy to drop junk from a page address before any request.

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

The file’s bytes. Two files with the same content point at the same bytes.

Processing

What the server did with an image at upload.

Methods

saved(): int — bytes saved: source->size - result->size. Negative if the result is heavier; 0 if nothing was done.

ImageInfo

Folder

A folder. One level, no nesting; the name is unique within the bucket.

Folder::ROOT

The bucket root, wherever a folder is expected.

public const string ROOT = '/';

/ can never be a real folder’s name, so there is no confusion. Where it applies:

CachePolicy

A cache override at the folder level. Every null field is inherited from the bucket.

Methods

isInherited(): bool — true if both fields are null: the folder overrides nothing.

Page

One page of a list. Mirrors the server’s { meta, data } format.

Methods

hasNext(): bool — whether there is a next page.

isEmpty(): bool — whether this page is empty.

count($page) — how many items are on this page (Countable). Not to be confused with total.

foreach ($page as $item) — walks this page’s items (IteratorAggregate).

map(callable $fn): Page — a new page where every item went through $fn; the meta is kept. Handy to turn entities into your own DTOs.

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

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

count($page);       // 10 — on this page
$page->total;       // 134 — in total
$page->hasNext();   // true

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

UploadSession

The state of a chunked upload. Every uploads() call returns a new session carrying the server’s current offset.

Methods

isDeduplicated(): bool — the content was in the bucket, the file is ready, nothing to send.

isComplete(): bool — every byte is on the server (offset >= size), ready to assemble.

remaining(): int — how many bytes are left to send.

KeyInfo

The answer of check(): what is behind the key.

Methods

expiresBefore(DateTimeInterface $at = now): bool — whether the key will have expired by $at.

if ($s5w->check()->expiresBefore(new DateTimeImmutable('+7 days'))) {
  $logger->warning('The S5W key expires within a week');
}

BucketRef

Storage

Space in the bucket, in bytes.

Methods

fits(int $bytes): bool — whether $bytes more would fit.

usage(): float — the used share, from 0.0 to 1.0.