m2mtech/flysystem-stream-wrapper

A stream wrapper for Flysystem V2 & V3.

v1.4.0 2023-12-18 16:01 UTC

README

Author Software License

This package provides a stream wrapper for Flysystem V2 & V3.

Flysystem V1

If you're looking for Flysystem 1.x support, check out the twistor/flysystem-stream-wrapper.

Installation

composer require m2mtech/flysystem-stream-wrapper

Usage

use League\Flysystem\Filesystem;
use League\Flysystem\Local\LocalFilesystemAdapter;
use M2MTech\FlysystemStreamWrapper\FlysystemStreamWrapper;

$filesystem = new Filesystem(new LocalFilesystemAdapter('/some/path'));
FlysystemStreamWrapper::register('fly', $filesystem);

file_put_contents('fly://filename.txt', $content);
mkdir('fly://happy_thoughts');

FlysystemStreamWrapper::unregister('fly');

The stream wrapper implements symfony/lock due to Flysystem V2 not supporting locking. By default, file locking using /tmp is used, but you can adjust this through configuration:

FlysystemStreamWrapper::register('fly', $filesystem, [
    FlysystemStreamWrapper::LOCK_STORE => 'flock:///tmp',
    FlysystemStreamWrapper::LOCK_TTL => 300,
]);

Handling Visibility Issues

Some adaptors might throw exceptions when dealing with visibility. If you encounter such issues, configure the stream wrapper to bypass them:

FlysystemStreamWrapper::register('fly', $filesystem, [
    FlysystemStreamWrapper::IGNORE_VISIBILITY_ERRORS => true,
]);

Addressing Directory Issues (file_exists / is_dir)

Some adaptors might not return dates for the last modified attribute for directories. In such cases, you can enable emulation to achieve the desired behavior:

FlysystemStreamWrapper::register('fly', $filesystem, [
    FlysystemStreamWrapper::EMULATE_DIRECTORY_LAST_MODIFIED => true,
]);

Dealing with is_readable / is_writable

Some filesystem functions depend on the uid and gid of the user executing PHP. Since a reliable cross-platform method to derive these values isn't available, the wrapper attempts to estimate them. If this fails, set them manually:

FlysystemStreamWrapper::register('fly', $filesystem, [
    FlysystemStreamWrapper::UID => 1000,
    FlysystemStreamWrapper::GID => 1000,
]);

Alternatively, access the parameters for PortableVisibilityConverter directly:

FlysystemStreamWrapper::register('fly', $filesystem, [
    FlysystemStreamWrapper::VISIBILITY_FILE_PUBLIC => 0644,
    FlysystemStreamWrapper::VISIBILITY_FILE_PRIVATE => 0600,
    FlysystemStreamWrapper::VISIBILITY_DIRECTORY_PUBLIC => 0755,
    FlysystemStreamWrapper::VISIBILITY_DIRECTORY_PRIVATE => 0700,
    FlysystemStreamWrapper::VISIBILITY_DEFAULT_FOR_DIRECTORIES => Visibility::PRIVATE,
]);

Testing

This package was developed using PHP 7.4 and has been tested for compatibility with PHP versions 7.2 through 8.3.

To test:

  • With PHP installed:
composer test
  • Inside a Docker environment for PHP 7.4:
docker compose run php74 composer test

Note: PHPUnit v10, used from PHP 8.1 onwards, requires a different config file:

docker compose run php81 composer test10

Changelog

For information on recent changes, refer to the CHANGELOG.

Contributing

For contribution guidelines, see CONTRIBUTING.

Security Vulnerabilities

If you discover any security vulnerabilities, please follow our security policy for reporting.

Credits

License

Licensed under the MIT License. See the License File for more details.