RUEN
Package · sdk-s5w

API reference

Every public class and method of the SDK: signatures, parameters, return values and exceptions. The fields of returned objects are on the Entities page, enums and ImageOptions on Options & enums, error classes in Exceptions.

Namespace Flytachi\Winter\SDK\S5wPackage flytachi/winter-sdk-s5w

General rules

Every method that talks to the server may throw TransportException (the server did not answer) and ResponseException (the answer does not look like S5W’s), and UnauthorizedException or ForbiddenException if the key does not fit. The “Errors” sections below list only what is specific to each method.

S5w

The client of one bucket and the SDK’s entry point. A final class; one instance corresponds to one key and one bucket. It keeps no state between calls, so one object can serve the whole application.

S5w::__construct()

Creates a client from a ready configuration.

Use the constructor when you need more than an address and a key: timeouts, retries, your own HTTP client. For the simple case S5w::connect() is shorter.

Syntax

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

Parameters

$config — server address, key and transfer settings. See S5wConfig.

$client — your own HTTP client Flytachi\Winter\Cast\Common\CastClient, when you need your own middleware, a proxy or cURL options. By default the SDK builds one itself with the timeouts from $config.

$logger — a PSR-3 logger. Gets one line per request (debug) and the chunked-upload events. By default nothing is logged. The key never reaches the log. See HTTP and logging.

Example

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()

Creates a client from an address and a key with default settings.

Syntax

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

Parameters

$baseUrl — the server address with the scheme: https://s5.example.com. A trailing / is removed.

$apiKey — the bucket key, s5w_….

$logger — an optional logger, as in the constructor.

Returns

A new S5w.

Errors

S5wException — the address lacks http:// or https://, or the key is empty.

Example

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

S5w::check()

Checks the key and reports what is behind it: the bucket, the access level, the key’s expiry and the space.

The only method a BASIC key can call too. Call it at application start and from a health check: it tells “the key doesn’t work” (an ApiException) from “the server is down” (TransportException).

Syntax

php
public function check(): KeyInfo

Returns

KeyInfo — bucket, access, key expiry, space.

Errors

UnauthorizedException — the server does not know the key.

ForbiddenException — the key is disabled or expired.

Example

php
$key = $s5w->check();

$key->bucket->id;          // "3f9a1c62-58ad-4b7e-9c31-0f2d5a6b7c81"
$key->bucket->name;        // "media"
$key->access;              // TokenAccess::FULL
$key->expiresAt;           // DateTimeImmutable, or null — the key never expires
$key->storage->free;       // 467587072

S5w::isValid()

Checks the key without an exception: true if the key works.

Returns false only when the server refused the key (401 or 403). If the server is unreachable, TransportException is still thrown: “couldn’t find out” is not “no”.

Syntax

php
public function isValid(): bool

Example

php
if (!$s5w->isValid()) {
  $logger->critical('The S5W key was refused — a new one is needed');
}

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

Return the resources for folders, files and chunked uploads.

A resource is created on the first call and reused afterwards; call the method as often as you like. All three need a FULL key — with a BASIC key their methods get ForbiddenException.

Syntax

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

S5w->config()

Returns the client’s configuration.

Syntax

php
public function config(): S5wConfig

S5wConfig

Server address, key and transfer settings. An immutable object: the with*() methods return a copy. The bucket is not set here — the key decides it.

S5wConfig::__construct()

Creates a configuration and validates the values.

Syntax

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,
)

Parameters

Parameter Type Default Description
$baseUrl string — server address with the scheme; spaces and a trailing / are removed
$apiKey string — the bucket key; surrounding spaces are removed
$timeout int 15 seconds per ordinary API request
$connectTimeout int 5 seconds to establish the connection
$retries int 1 attempts on a network failure (refused connection, timeout); 1 — no retries
$transferTimeout int 300 seconds per request that carries file bytes: a single-request upload, one chunk, assembling the file
$chunkThreshold int 16777216 (16 MiB) files larger than this are sent in chunks by files()->upload()
$userAgent ?string null replaces the default User-Agent header, WinterSDK/{version}

$retries applies to ordinary API calls. It never applies to a single-request upload: if the first attempt actually landed, a retry would store the file twice. Opening a chunked-upload session is not retried either. Sending chunks has its own retries — up to Uploads::ATTEMPTS per chunk.

$chunkThreshold can be set from 1 byte up to Files::SINGLE_REQUEST_LIMIT — the server accepts no more in one request.

Errors

S5wException — the address lacks http:// or https://, the key is empty, a timeout or the number of attempts is below 1, chunkThreshold is out of bounds.

Example

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

S5wConfig::with*()

Return a copy of the configuration with one value changed; the original object stays as it is.

Syntax

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

Parameters

withTimeout() changes timeout and, if the second argument is given, connectTimeout. The other methods change the parameter of the same name. The values are validated as in the constructor.

Example

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

Properties and debug output

Every parameter is available as a public read-only property: $config->baseUrl, $config->timeout and so on.

var_dump() and print_r() show the key shortened — s5w_…aaaa — so it does not end up whole in debug output or logs.

Folders

The bucket’s folders, /v1/folders. Obtained through $s5w->folders(). Needs a FULL key.

A folder is addressed by name. A name is 1–100 characters: letters, digits, space, ., _, -, the first character a letter or a digit; unique within the bucket. The SDK encodes the name in the request address itself.

Folders::list()

Returns one page of folders.

Syntax

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

Parameters

$page — page number, from 1.

$limit — page size, 1 to 100.

$search — part of a name to search for; null — no filter.

Returns

Page<Folder>.

Errors

ValidationException — $limit or $page out of bounds.

Example

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

foreach ($page as $folder) {
  echo $folder->name, "\n";
}
echo "Total: {$page->total}\n";

Folders::all()

Walks every folder, fetching pages as it goes.

Syntax

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

Parameters

$search — part of a name, as in list().

$pageSize — how many folders per request, 1 to 100.

Returns

Generator<int, Folder>. The next page is fetched when the current one runs out.

Example

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

Folders::get()

Returns a folder by name.

Syntax

php
public function get(string $name): Folder

Parameters

$name — the folder’s name.

Returns

Folder.

Errors

NotFoundException — there is no folder by that name.

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

The same as get(), but without an exception when the folder is missing.

Syntax

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

Returns

find() — a Folder or null. exists() — true if the folder exists.

Folders::create()

Creates a folder.

Syntax

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

Parameters

$name — the new folder’s name.

$public — true: the files inside are served at publicUrl without a key. Files uploaded into a public folder are public from the moment they land.

$retention — how long the files live: that long after a file is created, it is deleted by itself. The sweep runs every five minutes. See Retention.

Returns

The created Folder.

Errors

ConflictException — the name is taken.

ValidationException — the name breaks the rules.

Example

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

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

Folders::ensure()

Returns the folder if it exists, or creates it.

Looks the folder up by name first. If found, returns it unchanged — $public and $retention are not applied to it. If not, creates it with these settings. If someone else created the folder between the lookup and the creation, reads it again and returns it.

Syntax

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

Parameters

The same as create(); $public and $retention are used only on creation.

Returns

The existing or the created Folder.

Example

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

Folders::update()

Changes a folder; only what you pass changes.

The server takes the folder as a whole, so if $public or $retention is not passed, the SDK reads the current folder first and fills in its values — two requests. With both passed, it is one request.

The changes reach the files inside: changing $public rewrites the flag on every file, changing $retention recomputes every file’s expiry from its creation date — going from YEAR to DAY can delete files older than a day on the next sweep.

Syntax

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

Parameters

$name — the folder’s current name.

$rename — a new name; null — keep.

$public — a new visibility; null — keep.

$retention — a new retention; null — keep.

Returns

The changed Folder.

Errors

NotFoundException — no such folder. ConflictException — the new name is taken by another folder.

Example

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

Folders::rename()

Renames a folder; the visibility and the retention stay.

Syntax

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

Errors

NotFoundException — no such folder. ConflictException — $newName is taken.

Folders::setCache()

Sets the Cache-Control header the server delivers the folder’s files with.

The change applies from the next request for a file; copies already in a CDN keep the old header until they expire.

Syntax

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

Parameters

$name — the folder’s name.

$maxAge — max-age in seconds, 0 to 31536000 (a year); null — take the bucket’s.

$visibility — who may cache: see CacheVisibility; null — take the bucket’s.

Both values are sent, so to change one, pass the other as it currently is.

Returns

The Folder with the new policy in its cache field.

Example

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

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

Folders::resetCache()

Removes the folder’s cache policy — the bucket’s applies from then on. The same as setCache($name, null, null).

Syntax

php
public function resetCache(string $name): Folder

Folders::delete()

Deletes the folder together with every file inside. There is no undo.

Syntax

php
public function delete(string $name): void

Errors

NotFoundException — the folder is already gone.

Files

The bucket’s files, /v1/files. Obtained through $s5w->files(). Needs a FULL key.

Methods that work on one file take its id (16 characters of A-Za-z0-9_-) or the File itself. A string that cannot be an id is rejected by the SDK with no request — as if the file did not exist. The folder: parameter takes a folder name or a Folder.

php
public const int SINGLE_REQUEST_LIMIT = 33488896;   // 32 MiB − 64 KiB

SINGLE_REQUEST_LIMIT is the largest file that can be sent in one request: the server caps the request body at 32 MiB, the rest goes to the multipart framing.

Files::get()

Returns a file by id.

The same object as after an upload, but the processed field is null — the server does not keep the image processing report.

Syntax

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

Parameters

$id — the file’s id, or a File (to read it again).

Returns

File.

Errors

NotFoundException — no such file in this bucket. A file from another bucket looks the same. A string of the wrong shape gives the same answer, with no request.

Example

php
$file = $s5w->files()->get('FXOkqegbdrNRWQgc');
$file = $s5w->files()->get($file);   // read again

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

The same as get(), but without an exception when the file is missing (a malformed id included).

Syntax

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

Example

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

Files::list()

Returns one page of files with filters and sorting.

Syntax

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

Parameters

$page — page number, from 1.

$limit — page size, 1 to 100.

$search — part of the name, case-insensitive; null or '' — no filter.

$folder — where to look: null — the whole bucket; a name or a Folder — one folder; Folder::ROOT — only files outside any folder.

$sort — the sort field, see FileSort.

$direction — SortDirection::DESC (default) or ASC.

Returns

Page<File>.

Errors

ValidationException — no such folder, $limit or $page out of bounds.

Example

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

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

Files::all()

Walks every file matching the filter, fetching pages as it goes.

Syntax

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

Parameters

The same as list(), without the page number. $pageSize — files per request, 1 to 100.

Returns

Generator<int, File>.

Example

php
foreach ($s5w->files()->all(folder: Folder::ROOT) as $file) {
  echo "{$file->name} is public in the root\n";
}

Files::upload()

Uploads a file from disk.

The way is picked by size. Up to and including S5wConfig::$chunkThreshold (16 MiB by default) — one POST /v1/files request. Larger — in chunks through Uploads::send(): broken chunks are retried and the hash is checked for content already in the bucket. The result is the same. For progress and the session id call uploads()->send() yourself.

Syntax

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

Parameters

$file — a path or an SplFileInfo. The file must exist and be readable.

$folder — a folder (a name or a Folder); null — the bucket root. A file in the root is public.

$name — the stored name; null — the source file’s name. If the folder already has that name, the server stores the file as name (1).ext. The server aligns the extension with the content’s real type. Uploading a temporary file (e.g. tmp_name from a request) — pass the original name here, or the temporary one is stored.

$imageOptions — resize or re-encode an image, see ImageOptions. Images only.

Returns

File with the processed field filled in.

Errors

S5wException — the file is missing or unreadable (before any request).

ValidationException — no such folder; invalid image options; options sent for a file that is not an image.

PayloadTooLargeException — the bucket’s quota is full.

For large files — also the exceptions of Uploads::send().

Example

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

Result

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

Files::uploadContent()

Uploads bytes from memory.

For data that is not on disk: a generated document, an image from base64, an export. The way is picked by size as in upload().

Syntax

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

Parameters

$content — the file’s bytes.

$name — the stored name, with the extension. For text formats (.csv, .md, .yaml) the server takes the type from the extension, since by content they look like plain text.

$folder and $imageOptions — as in upload().

Returns

File.

Errors

As for upload(), except the file-read error.

Example

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

Files::rename()

Renames a file; the folder stays.

The id does not change, so every address and temporary link keeps working. The name is stored as given: the extension is not checked or added. The server takes the name and the folder together, so the SDK reads the file first — two requests.

Syntax

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

Parameters

$id — the file’s id or a File.

$name — the new name, 1–255 characters, unique in the folder.

Returns

The changed File.

Errors

NotFoundException — no such file. ConflictException — the name is taken in the folder. ValidationException — an empty or too long name.

Example

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

Files::move()

Moves a file into another folder or the root; the name stays.

The destination decides the file’s new rules: in a public folder it becomes public, in a private one private, the folder’s retention applies from the file’s creation date. The root makes a file public. The SDK reads the file first — two requests.

Syntax

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

Parameters

$id — the file’s id or a File.

$folder — the destination, required: a name or a Folder; Folder::ROOT or '' — the root. null is not accepted, so a move into the public root cannot happen by accident.

Returns

The moved File.

Errors

NotFoundException — no such file. ValidationException — no such folder. ConflictException — the destination already has a file with that name.

Example

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

Files::update()

Sets the name and the folder in one request, reading nothing first.

The result is exactly what you pass, so a change someone made between a read and a write cannot be rolled back. Use it when both values are known or both changes must happen at once. To keep the folder, use rename().

Syntax

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

Parameters

$id — the file’s id or a File.

$name — the name, 1–255 characters, unique in the destination.

$folder — the destination, required; Folder::ROOT or '' — the root (the file becomes public). null is not accepted.

Returns

The changed File.

Errors

As for move().

Example

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

Files::delete()

Deletes a file.

The file disappears from every delivery address at once; temporary links to it start answering 404. If another file has the same content, that one is unaffected.

Syntax

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

Errors

NotFoundException — no such file. Deletion is not idempotent: on a retry after a broken connection 404 means “already deleted”.

Uploads

Chunked uploads, /v1/uploads. Obtained through $s5w->uploads(). Needs a FULL key.

Chunks are 4 to 16 MiB (the last may be smaller), strictly in order. An unfinished session lives 24 hours after its last chunk and takes no space in the quota until it is completed.

php
public const int ATTEMPTS = 3;   // attempts per chunk and for assembly on a network failure

start(), append(), status(), complete() and abort() are one request each. send(), sendContent() and resume() run the whole upload. Methods that take a session also take its id as a string.

Uploads::start()

Opens an upload session.

Everything the server can refuse, it refuses here, before any byte moves: no such folder, the size does not fit the quota, the disk has no room. If $sha256 of content the bucket already holds is passed, the server creates the file at once: the answer’s isDeduplicated() is true and its file is filled in. The request is not retried on a network failure — with a hash it could create the file twice.

Syntax

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

Parameters

$name — the stored name, 1–255 characters.

$size — the exact size in bytes. Binding for the server: if a different number of bytes arrives, the file is refused.

$folder — a folder; null — the root.

$sha256 — the content’s SHA-256, 64 hex characters. Enables deduplication and is checked on complete(). Better not passed with $imageOptions.

$imageOptions — image processing, applied on complete().

Returns

UploadSession.

Errors

ValidationException — no such folder, invalid image options. PayloadTooLargeException — the size does not fit the quota. ServerException (507) — the server’s disk has no room.

Example

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

Uploads::append()

Sends the next chunk.

When a session is passed, the SDK adds an Upload-Offset header with its offset: the server compares it with its own and answers 409 on a mismatch instead of gluing the chunk in the wrong place.

Syntax

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

Parameters

$session — the session or its id.

$chunk — the chunk’s bytes: 4–16 MiB, smaller only for the last one.

$offset — the byte the chunk starts at. By default — the passed session’s offset; if an id string is passed and $offset is not set, there is no offset check — the chunk is appended.

Returns

A new UploadSession with the new offset.

Errors

ConflictException — the offset does not match the server’s; learn the real one with status(). ApiException (400) — an empty chunk, or under 4 MiB while not the last. PayloadTooLargeException — the chunk is over 16 MiB or goes past the declared size. NotFoundException — no such session.

Uploads::status()

Asks the server how many bytes it has received.

Syntax

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

Returns

An UploadSession with the server’s offset.

Errors

NotFoundException — the session is gone: completed, aborted or removed after 24 hours.

Uploads::complete()

Turns the received bytes into a file.

The server checks the hash (if one was passed), applies image processing and creates the file. Only then does the file appear in the bucket; the session ceases to exist.

Syntax

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

Returns

File — the same as after an ordinary upload.

Errors

ConflictException — not every byte has arrived; the session stays open. ValidationException — the data does not match the declared sha256; the session is removed.

Uploads::abort()

Cancels the session and deletes the received bytes. Optional: an abandoned session is removed by itself after 24 hours.

Syntax

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

Errors

NotFoundException — the session is already gone.

Uploads::send()

Uploads a file from disk in chunks, start to finish.

First computes the file’s SHA-256 (unless switched off) — content the bucket already holds is not transferred at all. Then opens a session and sends chunks of the size the server asks for. A broken chunk is retried up to ATTEMPTS times with 1 and 2 second pauses; before each retry the SDK asks the server how much it got, so nothing is sent twice or lost. Finally assembles the file. How it works — in Upload pipeline.

Syntax

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

Parameters

$file — a path or an SplFileInfo.

$folder — a folder; null — the root.

$name — the stored name; null — the file’s name.

$imageOptions — image processing at assembly.

$deduplicate — true: compute the hash and don’t transfer known content. With $imageOptions the hash is never computed.

$onStart — callable(UploadSession $session): void. Called once right after the session opens, before the first byte. This is where you save $session->id to continue after a restart. Not called on deduplication.

$onProgress — callable(int $sent, int $total): void. $sent — bytes already on the server, $total — the file’s size. Called at the start ($sent = 0), after every confirmed chunk and after recovery if a chunk landed; on deduplication — once with $sent === $total.

Returns

File.

Errors

UploadInterruptedException — the attempts ran out; the session is kept, continue with resume().

UploadUnconfirmedException — assembly was requested but the answer was lost and the session is gone: the file may have been created, its id is unknown.

ApiException and subclasses — the server refused the data (folder, quota, options); the session was cancelled.

S5wException — the file is unreadable or changed during the upload.

Example

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()

The same as send(), for bytes in memory.

Syntax

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

Parameters

$content — the bytes. $name — the stored name, required. The rest — as in send().

Uploads::resume()

Continues an interrupted upload of the same file.

Asks the server how many bytes have arrived, checks that the file’s size matches the one declared at the start, and sends the rest — with the same retries as send(). If the server already has everything, assembles the file at once.

Syntax

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

Parameters

$session — the session or its id: from UploadInterruptedException::sessionId(), or the one saved in onStart.

$file — the same file the upload started with.

$onProgress — as in send(); the first call reports where the upload continues from.

Returns

File.

Errors

NotFoundException — the session is gone (completed, aborted or removed after 24 hours): start over. S5wException — the file’s size does not match the session. Plus the errors of send().

Example

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