README

A set of factories to build Flysystem adapters from DSN strings, like:

s3://user:pass@endpoint?region=region&bucket=bucket ↓
local://some/path ↓
sftp://user@host:port/absolute/path?private_key=secret.pem ↓
and more...

Installation

$ composer require webalternatif/flysystem-dsn

Because this package does not explicitely require inner adapters, you will have to composer require them yourself in your project.
See the adapters section to know how to install them.

Usage

use Webf\Flysystem\Dsn\AdapterFactory\AwsS3AdapterFactory;
use Webf\Flysystem\Dsn\AdapterFactory\FlysystemAdapterFactory;
use Webf\Flysystem\Dsn\AdapterFactory\OpenStackSwiftAdapterFactory;

$factory = new FlysystemAdapterFactory([
    new AwsS3AdapterFactory(),
    new OpenStackSwiftAdapterFactory(),
]);

$adapter = $factory->createAdapter($dsn);

Adapters

AWS S3


Inner adapter	`league/flysystem-aws-s3-v3`
Install	`composer require league/flysystem-aws-s3-v3`
Factory class	`Webf\Flysystem\Dsn\AdapterFactory\AwsS3AdapterFactory`
DSN	`s3://username:password@endpoint?region=region&bucket=bucket`

Use s3+http:// if the endpoint does not support https.
s3:// is equivalent to s3+https://.
username is the access key id.
password is the secret access key.

Optional DSN parameters

version (default: latest)

Failover


Inner adapter	`webalternatif/flysystem-failover-bundle`
Install	`composer require webalternatif/flysystem-failover-bundle`
Factory class	`Webf\Flysystem\Dsn\AdapterFactory\FailoverAdapterFactory`
DSN	`failover(inner1:// inner2:// ...)?name=name`

There must be at least two DSN arguments for the failover DSN function.
The name parameter is used for the failover adapter's name in the failover bundle (used to identify adapters in Symfony commands).
For each inner DSN, you can specify a time_shift parameter (see configuration section of the failover bundle for more info). This parameter is removed from the inner DSN when it's built.

Ftp


Inner adapter	`league/flysystem-ftp`
Install	`composer require league/flysystem-ftp`
Factory class	`Webf\Flysystem\Dsn\AdapterFactory\FtpAdapterFactory`
DSN	`ftp://username:password@host:port/absolute/path`

Port is optional and defaults to 21
If the path contains spaces, replace each one by %20.

Optional DSN parameters

ssl: whether to use ftp_ssl_connect instead of ftp_connect (default: false)
timeout: timeout for all network operations (default: 90)
utf8: whether to enable the UTF-8 mode or not (default: false)
passive: whether to enable the passive mode or not (default: true)
transfer_mode: transfer mode used for ftp_fget and ftp_fput calls (must be ascii or binary, default: binary)
system_type: system type of the ftp server (must be unix or windows)
ignore_passive_address: whether to set the FTP_USEPASVADDRESS option to the opposite
timestamps_on_unix_listings: whether to set last modified in metadata or not for unix systems (default: false)
recurse_manually: whether to recurse directories "manually" instead of using the FTP option when the $deep parameter of listContents() is set to true (default: false)
public_file_permission: unix permission for public files (default: 0644)
private_file_permission: unix permission for public files (default: 0600)
public_dir_permission: unix permission for public files (default: 0755)
private_dir_permission: unix permission for public files (default: 0700)
default_dir_visibility: default visibility for automatically created directories (must be public or private, default: private)

In memory


Inner adapter	`league/flysystem-memory`
Install	`composer require league/flysystem-memory`
Factory class	`Webf\Flysystem\Dsn\AdapterFactory\InMemoryAdapterFactory`
DSN	`in-memory://`

Optional DSN parameters

default_visibility: default visibility of created files and directories (must be public or private, default: public)

Lazy

This adapter allows deferring the creation of the inner adapter until it is actually used (i.e., when Flysystem's methods are called). This is useful when you don't want an adapter to be created, but you need to have it somewhere (e.g., in a service container), and the creation of the adapter is expensive (e.g., it makes a network request).

The drawback is that you have to make sure the DSN of the inner adapter is valid, otherwise an exception will be thrown at "usage" time.


Inner adapter	`Webf\Flysystem\Dsn\Adapter\LazyAdapter`
Factory class	`Webf\Flysystem\Dsn\AdapterFactory\LazyAdapterFactory`
DSN	`lazy(inner://)`

There must be exactly one DSN argument for the lazy DSN function.

Local


Inner adapter	Built-in with `league/flysystem`
Factory class	`Webf\Flysystem\Dsn\AdapterFactory\LocalAdapterFactory`
DSN	`local://absolute_or_relative_path`

If the path contains spaces, replace each one by %20.

Optional DSN parameters

public_file_permission: unix permission for public files (default: 0644)
private_file_permission: unix permission for public files (default: 0600)
public_dir_permission: unix permission for public files (default: 0755)
private_dir_permission: unix permission for public files (default: 0700)
default_dir_visibility: default visibility for automatically created directories (must be public or private, default: private)

OpenStack Swift


Inner adapter	`webalternatif/flysystem-openstack-swift`
Install	`composer require webalternatif/flysystem-openstack-swift`
Factory class	`Webf\Flysystem\Dsn\AdapterFactory\OpenStackSwiftAdapterFactory`
DSN	`swift://username:password@endpoint?region=region&container=container`

Use swift+http:// if the endpoint does not support https.
swift:// is equivalent to swift+https://.
username is optional if parameter user_id is present.
temp_url_key (see below) is required to be able to generate temporary URLs.

Optional DSN parameters

user_id: auth.identity.password.user.id value sent to Keystone v3 API
user_domain_id: auth.identity.password.user.domain.id value sent to Keystone v3 API (default: default if user_id and user_domain_name are not defined)
user_domain_name: auth.identity.password.user.domain.name value sent to Keystone v3 API
domain_id: auth.scope.domain.id value sent to Keystone v3 API
domain_name: auth.scope.domain.name value sent to Keystone v3 API
project_id: auth.scope.project.id value sent to Keystone v3 API
project_name: auth.scope.project.name value sent to Keystone v3 API
project_domain_id: auth.scope.project.domain.id value sent to Keystone v3 API
project_domain_name: auth.scope.project.domain.name value sent to Keystone v3 API
temp_url_key: secret key used to generate temporary URLs (more information here)

Prefix


Inner adapter	`league/flysystem-path-prefixing`
Install	`composer require league/flysystem-path-prefixing`
Factory class	`Webf\Flysystem\Dsn\AdapterFactory\PrefixAdapterFactory`
DSN	`prefix(inner://)?path=some/prefix/path`

There must be exactly one DSN argument for the prefix DSN function.
If the path contains spaces, replace each one by %20.

ReadOnly


Inner adapter	`league/flysystem-read-only`
Install	`composer require league/flysystem-read-only`
Factory class	`Webf\Flysystem\Dsn\AdapterFactory\ReadOnlyAdapterFactory`
DSN	`readonly(inner://)`

There must be exactly one DSN argument for the readonly DSN function.

Sftp


Inner adapter	`league/flysystem-sftp-v3`
Install	`composer require league/flysystem-sftp-v3`
Factory class	`Webf\Flysystem\Dsn\AdapterFactory\SftpAdapterFactory`
DSN	`sftp://username:password@host:port/absolute/path`

The password can be empty if the private_key parameter is defined.
Port is optional and defaults to 22
If the path contains spaces, replace each one by %20.

Optional DSN parameters

private_key: absolute path of a private key file, can be used instead of password
passphrase: passphrase of the private key
use_agent: whether to use ssh agent or not (default: false)
timeout: request timeout in seconds (default: 10)
max_retries: number of connection retries before triggering an error (default: 4)
host_fingerprint: the host fingerprint to check
public_file_permission: unix permission for public files (default: 0644)
private_file_permission: unix permission for public files (default: 0600)
public_dir_permission: unix permission for public files (default: 0755)
private_dir_permission: unix permission for public files (default: 0700)
default_dir_visibility: default visibility for automatically created directories (must be public or private, default: private)

Tests

To run all tests, execute the command:

composer test

This will run Psalm, PHPUnit, Infection and a PHP-CS-Fixer check, but you can run them individually like this:

composer psalm
composer phpunit
composer infection
composer cs-check

webalternatif / flysystem-dsn

Maintainers

Details

README

Installation

Usage

Adapters

AWS S3

Optional DSN parameters

Failover

Ftp

Optional DSN parameters

In memory

Optional DSN parameters

Lazy

Local

Optional DSN parameters

OpenStack Swift

Optional DSN parameters

Prefix

ReadOnly

Sftp

Optional DSN parameters

Tests