RUEN
Package · sdk-s5w

Installation & requirements

The SDK is a library with no configuration of its own: one command installs it, there are no settings files. To work it needs two values from the S5W server — its address and a bucket key.

Requirements

What Version Why
PHP ≥ 8.4 readonly classes, promoted properties, enums
ext-curl any all traffic goes through cURL; files are sent as CURLFile
flytachi/winter-cast ^1.3 HTTP client on top of cURL
psr/log ^3.0 the logger interface, if you pass your own
Composer 2.x the SDK version for the User-Agent header comes from Composer

Composer installs every dependency except PHP itself and the curl extension.

Optional: flytachi/winter-logger or any other PSR-3 logger — to see requests and upload events in your logs. The SDK works without a logger.

Image processing

The SDK does not need the gd extension: images are resized and re-encoded by the S5W server. The SDK only passes the processing options.

Installing

bash
composer require flytachi/winter-sdk-s5w

What to get from the server

Value Where Example
Server address from whoever runs S5W; the API port (9090) or its domain https://s5.example.com
Bucket key S5W admin panel → bucket → tokens → issue s5w_9f3c…

The address goes with the scheme, without a path and without a trailing / (the SDK strips an extra one itself). More on deployment and domains — in the S5W documentation.

There are two kinds of keys, and they decide what the SDK can do:

Key What it opens in the SDK
FULL everything: check(), folders(), files(), uploads()
BASIC only check() and /p/{id} delivery; calls to folders(), files(), uploads() get ForbiddenException

A server application that uploads and organises files needs a FULL key. More about keys — in the API documentation.

A key is shown once

The server keeps only the key’s hash: a lost key cannot be recovered, only replaced. Keep it in environment variables, not in code.

Plain PHP

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

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

$key = $s5w->check();
echo "Connected to bucket {$key->bucket->name}\n";

The client keeps no state between calls, so create it once and use it everywhere. Fine tuning — timeouts, retries, the chunked-upload threshold — goes through S5wConfig, see the reference.

Winter

In a Winter application, declare the client as a bean: the container builds it once per worker and injects it wherever it is needed.

main/Configuration/S5wConfiguration.php
<?php

declare(strict_types=1);

namespace Main\Configuration;

use Flytachi\Winter\Kernel\App\Attribute\Bean;
use Flytachi\Winter\Kernel\App\Attribute\Configuration;
use Flytachi\Winter\Kernel\App\Attribute\Value;
use Flytachi\Winter\Logger\LoggerFactory;
use Flytachi\Winter\SDK\S5w\S5w;
use Flytachi\Winter\SDK\S5w\S5wConfig;

#[Configuration]
final class S5wConfiguration
{
  #[Bean]
  public function s5w(
      #[Value('S5W_URL')] string $url,
      #[Value('S5W_KEY')] string $key,
  ): S5w {
      return new S5w(
          new S5wConfig($url, $key),
          logger: LoggerFactory::getLogger('S5W'),
      );
  }
}
.env
S5W_URL=https://s5.example.com
S5W_KEY=s5w_9f3c…

From then on the client is injected into any service or controller:

php
#[Autowired]
private S5w $s5w;

Several buckets, logging and other options — in the Winter integration guide.

Verify

The shortest check that the address and the key are right is check():

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

$key->bucket->name;       // "media"
$key->access->name;       // "FULL"
$key->storage->free;      // 467587072 — bytes free
What happened What it means
a KeyInfo came back all good
UnauthorizedException the server does not know the key — check its value
ForbiddenException the key is disabled or expired — a new one is needed
TransportException the server is unreachable — check the address and the network
ResponseException something other than S5W answers at that address (e.g. a proxy error page)

Next