webalternatif/flysystem-dsn

A set of factories to build Flysystem adapters from DSN (Data Source Name)

v0.5.0 2023-01-16 14:59 UTC

Requires

• php: 8.0.* || 8.1.* || 8.2.*
• league/flysystem: ^3.0
• nyholm/dsn: ^2.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.0
• infection/infection: ^0.24.0
• league/flysystem-aws-s3-v3: ^3.0
• league/flysystem-ftp: ^3.0
• league/flysystem-memory: ^3.0
• league/flysystem-sftp-v3: ^3.0
• php-opencloud/openstack: ^3.2
• phpunit/phpunit: ^9.5
• vimeo/psalm: ^4.9
• webalternatif/flysystem-failover-bundle: ^0.4.0
• webalternatif/flysystem-openstack-swift: ^0.3.0

Suggests

• league/flysystem-aws-s3-v3: To use AwsS3AdapterFactory
• league/flysystem-ftp: To use FtpAdapterFactory
• league/flysystem-memory: To use InMemoryAdapterFactory
• league/flysystem-sftp-v3: To use SftpAdapterFactory
• webalternatif/flysystem-failover-bundle: To use FailoverAdapterFactory
• webalternatif/flysystem-openstack-swift: To use OpenStackSwiftAdapterFactory

MIT

• Web|Alternatif

• filesystem
• storage
• adapter
• dsn
• Flysystem

README

A set of factories to build Flysystem adapters from DSN.

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\AwsS3AdapterFactory;
use Webf\Flysystem\Dsn\FlysystemAdapterFactory;
use Webf\Flysystem\Dsn\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\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://.

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\FailoverAdapterFactory
DSN	failover(inner1:// inner2:// ...)?name=name

• There must be at least 2 DSN arguments for the failover DSN function.
• The name parameter is used for the failover adapter's name in 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\FtpAdapterFactory
DSN	ftp://username:password@host:port/absolute/path

• Port is optional and defaults to 21
• If 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 subsequent 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 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\InMemoryAdapterFactory
DSN	in-memory://

Optional DSN parameters

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

Local

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

• If 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\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.

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

Sftp

Inner adapter	league/flysystem-sftp-v3
Install	composer require league/flysystem-sftp-v3
Factory class	Webf\Flysystem\Dsn\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 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