omnisense/omnidrive API reference

Omnidrive

Config class

final class Config extends ArrayObject Config.php:14

A drive's configuration while its factory builds it: the options given, the factory's defaults under them, and the keys that must be filled. Options come as configuration and environment variables give them: strings too.

Config::defaults()

public function defaults(array $defaults): self

Sets each key not set yet.

Config::validateNotEmpty()

public function validateNotEmpty(array $keys): void

Config::get()

public function get(string $key, mixed $default = null): mixed

Config::string()

public function string(string $key): ?string

A string option; null when it is empty.

Config::int()

public function int(string $key, int $default = 0): int

Config::octal()

public function octal(string $key, int $default): int

An octal permission, as an integer (0644) or a string ("0644", "644").

Config::bool()

public function bool(string $key, bool $default = false): bool

A boolean option, as an environment variable gives it too: "1", "true", "yes", "on".

Config::list()

public function list(string $key): array

A list given as one environment variable arrives as a single comma-separated string: split here.

Drive interface

interface Drive Drive.php:24

One storage, by the name the application gives it ("uploads", "s3.private"...): files read and written by their path in it, wherever it is - a directory of this machine, a bucket, an SFTP or FTP server.

A path is relative to the drive's root, "/" separated ("avatars/1.png"); a leading "/" is the same path. Nothing here names how the drive is reached: an application type-hints Drive (and Drives), never the engine behind it.

What fails is a DriveException (FileNotFoundException when the file is not there), what the drive cannot do a NotSupportedException - its Capabilities say so beforehand.

Drive::name()

public function name(): string

The name the drive is configured with.

Drive::capabilities()

public function capabilities(): Capabilities

What the drive can do besides reading and writing: a local file, public and temporary URLs.

Drive::read()

public function read(string $path): string

Throws

FileNotFoundException|\DriveException

Drive::readStream()

public function readStream(string $path)

The file as a stream, for large files: the caller closes it.

Throws

FileNotFoundException|\DriveException

Drive::write()

public function write(string $path, string $contents, array $options = []): void

Writes the file, replacing it when it is there; missing directories are made.

$options

"visibility" (Visibility or "public"/"private"), "directory_visibility", and whatever the drive's engine takes

Throws

DriveException

Drive::writeStream()

public function writeStream(string $path, $stream, array $options = []): void

$options

as write()

Throws

DriveException

Drive::exists()

public function exists(string $path): bool

Whether a file is there (a directory is not a file).

Drive::directoryExists()

public function directoryExists(string $path): bool

Drive::delete()

public function delete(string $path): void

Deletes the file; a file that is not there is no error.

Drive::deleteDirectory()

public function deleteDirectory(string $path): void

Deletes the directory and everything under it; a directory that is not there is no error.

Drive::createDirectory()

public function createDirectory(string $path, array $options = []): void

$options

"directory_visibility"

Drive::list()

public function list(string $path = '', bool $deep = false): iterable

What a directory holds, files and directories, lazily; $deep goes down every directory under it.

Throws

DriveException

Drive::move()

public function move(string $from, string $to): void

Throws

FileNotFoundException|\DriveException

Drive::copy()

public function copy(string $from, string $to): void

Throws

FileNotFoundException|\DriveException

Drive::metadata()

public function metadata(string $path): Entry

The file's size, type, last change and visibility, as one Entry (several calls to a remote drive: ask size() or mimeType() alone when that is all you need).

Throws

FileNotFoundException|\DriveException

Drive::size()

public function size(string $path): int

In bytes.

@throws FileNotFoundException|DriveException

Drive::mimeType()

public function mimeType(string $path): string

Throws

FileNotFoundException|\DriveException

Drive::lastModified()

public function lastModified(string $path): \DateTimeImmutable

Throws

FileNotFoundException|\DriveException

Drive::checksum()

public function checksum(string $path, string $algorithm = 'md5'): string

Throws

FileNotFoundException|\DriveException

Drive::visibility()

public function visibility(string $path): Visibility

Throws

FileNotFoundException|\DriveException

Drive::setVisibility()

public function setVisibility(string $path, Visibility $visibility): void

Throws

FileNotFoundException|\DriveException

Drive::publicUrl()

public function publicUrl(string $path): string

Where anyone fetches the file from: the drive's public address (its "public_url" option, or a bucket's own), whether the file is there or not.

Throws

NotSupportedException when the drive has none (Capabilities::$publicUrls)

Drive::temporaryUrl()

public function temporaryUrl(string $path, \DateTimeInterface $expiresAt): string

A signed address that serves the file until $expiresAt, to whoever holds it.

Throws

NotSupportedException when the drive cannot sign one (Capabilities::$temporaryUrls)

Drive::localPath()

public function localPath(string $path): ?string

The file's path on this machine, whether it is there or not; null for a drive with no local file behind its paths (a bucket, a server).

DriveFactory class

abstract class DriveFactory implements DriveFactoryInterface DriveFactory.php:13

The family's way, at its simplest: a drive's factory fills a Config - its name ("omnidrive.factory_name"), its title ("omnidrive.factory_title"), the options it needs ("omnidrive.required_options") and the defaults of the others - then builds the drive from it.

Nothing here connects: a drive reaches its server on its first operation.

DriveFactory::getName()

public function getName(): string

DriveFactory::create()

public function create(array $options = [], ?string $name = null): Drive

DriveFactory::createConfig()

public function createConfig(array $options = []): Config

DriveFactoryInterface interface

interface DriveFactoryInterface DriveFactoryInterface.php:6

Builds a drive from its options (a root, a bucket and its keys, a server...).

DriveFactoryInterface::getName()

public function getName(): string

The name drives are configured with: "local", "s3", "sftp", "ftp".

..

DriveFactoryInterface::create()

public function create(array $options = [], ?string $name = null): Drive

$name

the drive's name (Drive::name()); the factory's when null

Drives interface

interface Drives Drives.php:12

The application's drives by name. Registry builds them from factories and options; a host gives them from its own storages (Flysystem\OperatorDrives: Symfony's flysystem-bundle storages, Laravel's disks).

Drives::get()

public function get(string $name): Drive

Throws

InvalidConfigException when no drive has that name

Drives::has()

public function has(string $name): bool

Drives::names()

public function names(): array

Returns

the drives' names, as far as they are known

Registry class

final class Registry implements Drives Registry.php:18

The application's drives by name, each built once from its factory and options:

new Registry([new LocalDriveFactory(), new S3DriveFactory()], [ 'uploads' => ['factory' => 'local', 'options' => ['root' => __DIR__.'/var/uploads', 'public_url' => '/uploads']], 'archive' => ['factory' => 's3', 'options' => ['bucket' => 'archive', 'region' => 'eu-west-3', 'key' => '...', 'secret' => '...']], ]);

$registry->get('uploads')->write('avatars/1.png', $bytes);

Registry::__construct()

public function __construct(iterable $factories, readonly array $config)

Registry::get()

public function get(string $name): Drive

Registry::has()

public function has(string $name): bool

Registry::names()

public function names(): array

Registry::options()

public function options(string $name): array

Returns

the options a drive is configured with

Registry::create()

public function create(string $name, array $overrides = []): Drive

A drive built afresh, its configured options with $overrides over them. Not kept: get() still gives the configured one.

Registry::all()

public function all(): array

Registry::factories()

public function factories(): array

Returns

the factories installed: what factory: may name

Visibility enum

enum Visibility Visibility.php:9

Who may read a file: anyone (a public bucket's object, a file the web server serves, 0644) or the drive's own user (0600, a private object).

case Public = 'public'

case Private = 'private'

Visibility::of()

public static function of(self|string $visibility): self

A Visibility, or its name as configuration gives it ("public", "private").

Omnidrive\Exception

DriveException class

class DriveException extends RuntimeException implements OmnidriveException DriveException.php:10

A drive could not do what it was asked: the operation (one of OPERATIONS), the drive and the path are kept; the engine's own exception is the previous one.

const OPERATIONS = ['read' => 'read', 'write' => 'write', 'delete' => 'delete', 'move' => 'move', 'copy' => 'copy', 'list' => 'list', 'exists' => 'check whether there is', 'dir…

public readonly string $operation

public readonly string $drive

public readonly string $path

DriveException::__construct()

final public function __construct(public readonly string $operation, public readonly string $drive, public readonly string $path, string $reason = '', ?\Throwable $previous = null)

DriveException::of()

public static function of(string $operation, string $drive, string $path, ?\Throwable $previous = null): static

FileNotFoundException class

final class FileNotFoundException extends DriveException FileNotFoundException.php:6

The file asked for is not on the drive.

InvalidConfigException class

final class InvalidConfigException extends InvalidArgumentException implements OmnidriveException InvalidConfigException.php:6

A drive that is not configured, a factory that is not installed, an option missing.

NotSupportedException class

final class NotSupportedException extends LogicException implements OmnidriveException NotSupportedException.php:9

The drive does not do that: a public address for a drive that has none, a signed one for a drive that cannot sign. Its Capabilities say so beforehand.

NotSupportedException::operation()

public static function operation(string $drive, string $operation, string $why = ''): self

OmnidriveException interface

interface OmnidriveException extends Throwable OmnidriveException.php:6

Every exception Omnidrive throws.

Omnidrive\Flysystem

FlysystemDrive class

final class FlysystemDrive implements Drive FlysystemDrive.php:32

A Drive over a Flysystem operator: Flysystem is the engine, this class the only place that speaks to it. Its exceptions become the contract's (the engine's kept as the previous one), its attributes Entry, its visibility strings Visibility.

Built by a provider's factory (which knows its root and what it can do), or by a host over the storages it already has (of(): the root of a local adapter and the generators of public and temporary URLs read from the operator).

FlysystemDrive::__construct()

public function __construct(readonly string $name, readonly FilesystemOperator $operator, readonly ?string $localRoot = null, ?Capabilities $capabilities = null)

$localRoot

the directory of this machine behind the drive's paths; null for a remote drive

FlysystemDrive::of()

public static function of(string $name, FilesystemOperator $operator): self

A drive over an operator a host gives: its local root, if any, read from its adapter.

FlysystemDrive::operator()

public function operator(): FilesystemOperator

The engine, for a host that hands it to a library that speaks Flysystem itself. An application keeps to Drive.

FlysystemDrive::name()

public function name(): string

FlysystemDrive::capabilities()

public function capabilities(): Capabilities

FlysystemDrive::read()

public function read(string $path): string

FlysystemDrive::readStream()

public function readStream(string $path)

FlysystemDrive::write()

public function write(string $path, string $contents, array $options = []): void

FlysystemDrive::writeStream()

public function writeStream(string $path, $stream, array $options = []): void

FlysystemDrive::exists()

public function exists(string $path): bool

FlysystemDrive::directoryExists()

public function directoryExists(string $path): bool

FlysystemDrive::delete()

public function delete(string $path): void

FlysystemDrive::deleteDirectory()

public function deleteDirectory(string $path): void

FlysystemDrive::createDirectory()

public function createDirectory(string $path, array $options = []): void

FlysystemDrive::list()

public function list(string $path = '', bool $deep = false): iterable

FlysystemDrive::move()

public function move(string $from, string $to): void

FlysystemDrive::copy()

public function copy(string $from, string $to): void

FlysystemDrive::metadata()

public function metadata(string $path): Entry

FlysystemDrive::size()

public function size(string $path): int

FlysystemDrive::mimeType()

public function mimeType(string $path): string

FlysystemDrive::lastModified()

public function lastModified(string $path): \DateTimeImmutable

FlysystemDrive::checksum()

public function checksum(string $path, string $algorithm = 'md5'): string

FlysystemDrive::visibility()

public function visibility(string $path): Visibility

FlysystemDrive::setVisibility()

public function setVisibility(string $path, Visibility $visibility): void

FlysystemDrive::publicUrl()

public function publicUrl(string $path): string

FlysystemDrive::temporaryUrl()

public function temporaryUrl(string $path, \DateTimeInterface $expiresAt): string

FlysystemDrive::localPath()

public function localPath(string $path): ?string

FlysystemDriveFactory class

abstract class FlysystemDriveFactory extends DriveFactory FlysystemDriveFactory.php:30

A provider's factory: it builds the league adapter from its options, this class the drive around it. The options every drive takes:

• public_url: where its files are served from, a prefix ("https://cdn.example.org/uploads", "/uploads") or a list of them (sharded); else the adapter's own (a bucket's);
• visibility, directory_visibility: what a file or a directory is written with by default ("public", "private");
• retain_visibility: whether a copy keeps the visibility of its source (true, Flysystem's); false copies with the drive's default visibility, for a server that cannot report a file's;
• permissions (a drive of Unix files: local, SFTP, FTP): the modes each visibility is, {file: {public: 0644, private: 0600}, dir: {public: 0755, private: 0700}}.

OperatorDrives class

final class OperatorDrives implements Drives OperatorDrives.php:20

The drives a host already has, as Flysystem operators in a PSR-11 container by name: Symfony's flysystem-bundle storages (a service locator of the services tagged flysystem.storage), Laravel's disks. Each becomes a FlysystemDrive the first time it is asked for.

Its names are those given, else those a service locator provides (getProvidedServices()); a plain container cannot list its own.

OperatorDrives::__construct()

public function __construct(readonly ContainerInterface $operators, readonly ?array $names = null)

OperatorDrives::get()

public function get(string $name): Drive

OperatorDrives::has()

public function has(string $name): bool

OperatorDrives::names()

public function names(): array

Omnidrive\Model

Capabilities class

final readonly class Capabilities Capabilities.php:11

What a drive can do besides reading and writing, said before it is asked: whether its files are files of this machine (Drive::localPath()), whether it has a public address (Drive::publicUrl()), whether it signs temporary ones (Drive::temporaryUrl()).

public bool $local

public bool $publicUrls

public bool $temporaryUrls

Capabilities::__construct()

public function __construct(public bool $local = false, public bool $publicUrls = false, public bool $temporaryUrls = false)

Capabilities::toArray()

public function toArray(): array

Entry class

final readonly class Entry Entry.php:12

A file or a directory of a drive, as a listing or metadata() gives it: what the drive told, null where it told nothing (a listing gives no type, a bucket no directory's date).

public string $path

public bool $directory

public ?int $size

public ?\DateTimeImmutable $lastModified

public ?Visibility $visibility

public ?string $mimeType

Entry::__construct()

public function __construct(public string $path, public bool $directory = false, public ?int $size = null, public ?\DateTimeImmutable $lastModified = null, public ?Visibility $visibility = null, public ?string $mimeType = null)

Entry::isFile()

public function isFile(): bool

Entry::basename()

public function basename(): string

The last segment of the path.

Entry::toArray()

public function toArray(): array

Omnidrive\Testing

DriveContractTests trait

trait DriveContractTests DriveContractTests.php:27

What every Drive does, as PHPUnit tests: a provider's test case (or an application's, for a drive of its own) uses this trait and gives the drive.

Each test works under a directory of its own, removed afterwards, so a shared bucket or server is left as it was.

final class LocalDriveTest extends TestCase { use DriveContractTests;

    protected function drive(): Drive { return (new LocalDriveFactory())->create(['root' => sys_get_temp_dir().'/drive']); }
}

Requires phpunit/phpunit (the application's, in require-dev).

DriveContractTests::testAFileIsWrittenReadAndDeleted()

public function testAFileIsWrittenReadAndDeleted(): void

DriveContractTests::testStreamsAreWrittenAndRead()

public function testStreamsAreWrittenAndRead(): void

DriveContractTests::testAFileThatIsNotThereIsNotFound()

public function testAFileThatIsNotThereIsNotFound(): void

DriveContractTests::testADirectoryIsListedShallowAndDeep()

public function testADirectoryIsListedShallowAndDeep(): void

DriveContractTests::testAFileIsMovedAndCopied()

public function testAFileIsMovedAndCopied(): void

DriveContractTests::testDirectoriesAreMadeAndDeleted()

public function testDirectoriesAreMadeAndDeleted(): void

DriveContractTests::testMetadataAndChecksumAreTheFile()

public function testMetadataAndChecksumAreTheFile(): void

DriveContractTests::testVisibilityIsWrittenAndChanged()

public function testVisibilityIsWrittenAndChanged(): void

DriveContractTests::testAddressesAndLocalPathsAreWhatTheCapabilitiesSay()

public function testAddressesAndLocalPathsAreWhatTheCapabilitiesSay(): void

InMemoryDriveFactory class

final class InMemoryDriveFactory extends FlysystemDriveFactory InMemoryDriveFactory.php:18

A drive in this process's memory, for an application's tests: what is written is read back until the process ends, nothing touches a disk or a network.

Requires league/flysystem-memory (suggested).

new Registry([new InMemoryDriveFactory()], ['uploads' => ['factory' => 'memory', 'options' => ['public_url' => '/uploads']]]);