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

• 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

• 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

• 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

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.

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

Local

• 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

• 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

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

ReadOnly

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

Sftp

• 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