Download the PHP package elazar/flystream without Composer

Flystream

Flysystem v2/3 + PHP stream wrappers = 🔥

Flystream enables you to use core PHP filesystem functions to interact with Flysystem filesystems by registering them as custom protocols.

Released under the MIT License.

Supported Use Cases

• Using Flysystem with another library that interacts with the filesystem using PHP filesystem functions instead of Flysystem.
• Intercepting filesystem operations for verification in tests.
• Improving the speed of tests where the code under test would otherwise require access to the local filesystem.

Unsupported Use Cases

• Flystream doesn't and won't support Flysystem v1. If you want a similar library for v1, see twistor/flysystem-stream-wrapper.

Known Issues

• If a file or directory handle is not explicitly closed after use (i.e. using fclose() or closedir() as appropriate), PHP will implicitly attempt to close it during shutdown. This situation may trigger a segmentation fault in some environments. This issue has been resolved and is available in PHP 7.4.23, 8.0.10, and 8.1.0. In older versions, the easiest work-around is to ensure that file and directory handles are explicitly closed.

Requirements

• PHP 8.1+
• Flysystem 2 or 3

Installation

Use Composer.

Note: This will automatically install the latest version of the Flysystem core library that is available for your environment. However, you must handle installing adapters yourself. See the Flysystem documentation for a list of official adapters.

Usage

If you want to run the examples below, you will need to install league/flysystem-memory.

These examples below aren't comprehensive, but should provide a basic understanding of the capabilities of Flystream.

Configuration

For its most basic use, Flystream requires two parameters:

1. a string containing a name for a custom protocol used by PHP filesystem functions; and
2. an object that implements the Flysystem FilesystemOperator interface (e.g. an instance of the Filesystem class).

Path Normalization

The Flysystem Filesystem class supports normalization of supplied paths before they're passed to the underlying adapter. The Flysystem PathNormalizer interface represents this normalization process.

The implementation of this interface that Flysystem uses by default is WhitespacePathNormalizer, which handles normalizing the directory separator (i.e. converting \ to /), removing abnormal whitespace characters, and resolving relative paths.

If you're using a third-party adapter, you'll probably need path normalization to include removing the custom protocol used to register the Flysystem filesystem with Flystream. As such, by default, Flystream registers a custom path normalizer that it defines, StripProtocolPathNormalizer. You can configure your Filesystem instance to use this normalizer like so.

If you would prefer to limit protocols removed by StripProtocolPathNormalizer to a specified list, you can do so by specifying a custom instance that sets a value for its first parameter.

StripProtocolPathNormalizer also supports applying a second path normalizer after it performs its own normalization. By default, it uses Flysystem's WhitespacePathNormalizer as this secondary normalizer. If you'd rather that StripProtocolPathNormalizer not use a secondary normalizer, you can override this behavior like so.

If you'd rather not apply any path normalization, you can use the PassThruPathNormalizer normalizer class provided by Flystream to do this.

Buffering

Flysystem doesn't support append operations, in part because some of its drivers don't (e.g. AWS S3).

The default size of the PHP stream write buffer differs between PHP 7.4 and 8.0, which may result in more than one write operation if the size of the data written exceeds the buffer size.

Because of these circumstances, Flystream buffers written data and then writes or "flushes" it out to the destination.

Flystream offers native support for these buffer strategies:

• Memory: Buffers strictly in memory. This has the best performance, but also the highest memory usage.
• File: Buffers strictly in a temporary file. This has the worst performance, but also the least memory usage.
• Overflow: Buffers in memory up to a configurable limit, then switches to using a temporary file. Its performance and memory usage generally lies between the two strategies above.

By default, Flystream uses the Memory strategy for optimal performance. Below are examples of overriding this setting to use a different strategy.

You may want to check the value of your memory_limit PHP INI setting and use either a profiler or functions like memory_get_usage() and memory_get_peak_usage() to get an idea of which strategy is best for your use case.

Another option is using your own buffer strategy implementation, by creating a class that implements BufferInterface and then configuring Flystream to use it in the same fashion as the above examples.

Visibility

Flysystem implements an abstraction layer for visibility and an implementation for handling Unix-style visibility.

By default, Flystream uses this Unix-style visibility implementation with its default configuration. If you want to override its settings, you can override it with a configured instance.

You can also configure Flystream to use a custom visibility implementation.

Locking

By default, the Flysystem Local adapter uses file locks during writes and updates, but allows overriding this behavior.

Flystream follows suit. It defines an interface, LockRegistryInterface, and two implementations of this interface, LocalLockRegistry and PermissiveLockRegistry. By default, Flystream uses the former, which is a naïve implementation that prevents the current PHP process from reading a file already open for writing or writing to a file already open for reading.

If you'd rather disable locking entirely, you can configure Flystream to use the latter implementation, which grants all requested lock acquisitions and releases.

Another option is to create your own lock registry implementation, such as a distributed one that handles locking between PHP processes using a library such as php-lock/lock.

Then, configure Flystream to use it.

Logging

Flystream supports any PSR-3 logger and logs all calls to its stream wrapper methods.

By default, it uses the NullLogger implementation included with psr/log, which discards the log entries. You can override this to use a different logger, such as Monolog.

Core buffer implementations do not implement logging. However, as of Flystream 0.4.0, a buffer instance can be wrapped in an instance of the LoggingCompositeBuffer class to log calls to its methods. An example of doing this with the default MemoryBuffer buffer implementation is shown below.

Design

Service Locator

Flystream uses a singleton service locator rather than a more commonly accepted dependency injection configuration due to how PHP uses its stream wrapper classes. Specifically, PHP implicitly creates an instance of the stream wrapper class each time you use the associated custom protocol, and doesn't allow for dependency injection.

This requires use of a service locator for the stream wrapper to have access to dependencies, a singleton in particular so that the stream wrapper uses the same container that the end user configures to override default dependency implementations. The stream wrapper class limits its use of the service locator to a single method that fetches a dependency from the container of the singleton instance. It also supports injecting a custom singleton instance, in particular for testing. These measures limit the impact of the disadvantages of using the service locator pattern.