 |
VOOZH | about |
|
VOOZH | about |
This document explains how to create custom filesystem drivers and register them with the FilesystemManager. It covers implementing the required contracts, integrating with League Flysystem adapters, and optionally enabling connection pooling for custom drivers.
For general driver architecture and the base FilesystemAdapter implementation, see Driver Architecture and FilesystemAdapter. For connection pooling configuration details, see Object Pooling for Cloud Drivers. For comprehensive configuration options, see Configuration Reference.
Custom drivers integrate into the system by implementing contracts and registering with the FilesystemManager through the extend() method. The architecture supports two approaches: extending the base FilesystemAdapter class or implementing contracts directly.
Sources:
All drivers must implement the Filesystem interface, which defines the core storage operations. The interface requires implementation of CRUD operations, metadata retrieval, directory management, and streaming capabilities.
| Method Category | Required Methods | Purpose |
|---|---|---|
| Existence Checks | exists(), path() | Verify file presence and resolve paths |
| Read Operations | get(), readStream(), readStreamRange() | Retrieve file contents and streams |
| Write Operations | put(), putFile(), putFileAs(), writeStream() | Store files and streams |
| Metadata | size(), lastModified(), getVisibility(), setVisibility() | File attributes and permissions |
| Manipulation | copy(), move(), delete(), prepend(), append() | File operations |
| Directories | files(), allFiles(), directories(), allDirectories(), makeDirectory(), deleteDirectory() | Directory operations |
Sources:
Drivers that provide cloud storage features should implement the Cloud interface, which extends Filesystem with URL generation capabilities:
| Method | Purpose | When Required |
|---|---|---|
url() | Generate public URL for file | Always for Cloud drivers |
temporaryUrl() | Generate time-limited signed URL | For pre-signed download URLs |
providesTemporaryUrls() | Indicate temporary URL support | Implementation detail |
Sources:
Custom drivers are registered with FilesystemManager::extend(), which accepts three parameters:
The creator closure receives two parameters:
ContainerInterface $app - The Hyperf DI containerarray $config - Configuration array from filesystems.disks.{name}Sources:
Registration occurs during application bootstrap, typically in a service provider or ConfigProvider. The extend() method stores the creator closure in the customCreators array and optionally adds the driver to the poolables array.
Key Code Locations:
Sources:
The recommended approach for most custom drivers is to extend FilesystemAdapter, which provides complete implementations of the Filesystem and Cloud contracts. This approach requires only implementing driver-specific functionality.
Custom adapters extending FilesystemAdapter must call the parent constructor with three parameters:
| Parameter | Type | Description |
|---|---|---|
$driver | FilesystemOperator | League Flysystem filesystem instance |
$adapter | FlysystemAdapter | Underlying Flysystem adapter |
$config | array | Configuration array |
Sources:
Custom drivers can override specific methods to provide specialized functionality:
| Method | Default Behavior | Common Overrides |
|---|---|---|
url() | Attempts multiple URL strategies | Custom domain logic |
temporaryUrl() | Delegates to adapter or callback | Cloud-specific signed URLs |
temporaryUploadUrl() | Delegates to adapter | Pre-signed upload endpoints |
readStreamRange() | Throws RuntimeException | Partial content support |
Example: LocalFilesystemAdapter
The LocalFilesystemAdapter extends FilesystemAdapter and adds disk name tracking and signed URL serving for local files:
Example: AwsS3V3Adapter
The AwsS3V3Adapter extends FilesystemAdapter with S3 client access and specialized URL generation:
Sources:
Custom drivers must integrate with League Flysystem by creating appropriate adapter instances. The FilesystemManager provides the createFlysystem() method to wrap Flysystem adapters with additional functionality.
The createFlysystem() method automatically applies decorators based on configuration:
ReadOnlyFilesystemAdapter when read-only is truePathPrefixedAdapter when prefix is setSources:
The built-in drivers demonstrate integration patterns:
Local Driver:
1. Create PortableVisibilityConverter with permissions
2. Create LocalAdapter with root path and visibility
3. Call createFlysystem() with adapter and config
4. Wrap in LocalFilesystemAdapter
S3 Driver:
1. Create S3Client with credentials and configuration
2. Create AwsS3PortableVisibilityConverter
3. Create S3Adapter with client, bucket, and options
4. Call createFlysystem() with adapter and config
5. Wrap in AwsS3V3Adapter with client reference
Sources:
Drivers that maintain persistent connections to remote services (databases, cloud APIs, network filesystems) benefit from connection pooling in long-running processes like Swoole/Hyperf applications.
Sources:
When the poolable flag is set to true during registration, the FilesystemManager wraps driver instances in FilesystemPoolProxy. The proxy uses configuration from the disk's pool array:
| Configuration Key | Default | Purpose |
|---|---|---|
min_objects | 1 | Minimum pool size |
max_objects | 10 | Maximum pool size |
wait_timeout | 3.0 | Seconds to wait for available connection |
max_idle_time | 60.0 | Seconds before idle connection is closed |
Key Implementation Details:
HasPoolProxy trait method createPoolProxy()Sources:
This example demonstrates creating a custom driver that stores files in Redis, implements the Cloud contract, and supports connection pooling.
Sources:
Create a Flysystem adapter implementing League\Flysystem\FilesystemAdapter:
Similar to how the S3 driver uses League\Flysystem\AwsS3V3\AwsS3V3Adapter at src/FilesystemManager.php256
Create your driver class that extends FilesystemAdapter and adds driver-specific functionality:
Pattern matches src/AwsS3V3Adapter.php18-31 and src/GoogleCloudStorageAdapter.php21-34
In your ConfigProvider::__invoke() or a service provider:
Registration pattern follows src/FilesystemManager.php466-479
Add disk configuration to config/autoload/filesystems.php:
Configuration structure matches src/FilesystemManager.php417-421 and uses pool config at src/FilesystemManager.php136-141
Sources:
Drivers can implement custom temporary URL logic without extending FilesystemAdapter by implementing the temporaryUrl() method directly, or by using the buildTemporaryUrlsUsing() method to set a callback.
The callback approach allows runtime customization:
Sources:
Override the path() method to customize how relative paths are resolved to absolute paths. The base implementation uses PathPrefixer:
Sources:
For drivers with unique requirements that don't fit the FilesystemAdapter pattern, implement the Filesystem and optionally Cloud contracts directly. This approach provides maximum flexibility but requires implementing all contract methods.
Contract Definitions:
Sources:
The FilesystemAdapter base class provides assertion methods for testing, inherited by custom drivers:
| Method | Purpose |
|---|---|
assertExists() | Verify file/directory exists, optionally check content |
assertMissing() | Verify file/directory does not exist |
assertDirectoryEmpty() | Verify directory has no files |
These methods use PHPUnit assertions internally and are useful for integration testing custom drivers.
Sources:
The build() method on FilesystemManager creates on-demand disk instances useful for testing:
Sources:
Custom driver creation involves four main steps:
FilesystemAdapterFilesystemManager::extend() with driver name, creator closure, and optional poolable flagdriver key matching your registered namedisk('name') like any built-in driverThe system automatically handles:
For drivers that maintain network connections, enabling pooling significantly improves performance in long-running Hyperf applications by reusing connections across requests.
Sources:
Refresh this wiki