Driver Architecture and FilesystemAdapter

Purpose and Scope

This page documents the base driver architecture and the FilesystemAdapter class, which serves as the foundation for all filesystem drivers in the package. It explains how the adapter pattern integrates with League Flysystem, the common functionality provided to all drivers, and how concrete driver implementations extend this base.

For information about specific driver implementations, see Local Filesystem Driver and Cloud Storage Drivers. For details on how the FilesystemManager orchestrates driver creation, see Factory Pattern and FilesystemManager.

The Adapter Pattern

The filesystem package uses the Adapter Pattern to wrap League Flysystem's functionality while providing additional features specific to the Hypervel/Hyperf ecosystem. This design allows the package to leverage Flysystem's mature storage abstractions while adding capabilities like connection pooling, signed URL generation, HTTP response streaming, and framework integration.

Layered Architecture

Sources: src/FilesystemAdapter.php1-92 composer.json31-51

The architecture consists of three layers:

1. Hypervel Abstraction Layer - Provides framework-specific features and a unified API
2. Flysystem Layer - Core storage abstraction from League Flysystem
3. Storage Backends - Actual storage systems (local disk, cloud services)

FilesystemAdapter Class Structure

Two-Level Wrapping

The FilesystemAdapter class maintains references to both a FilesystemOperator (Flysystem's operational interface) and a FlysystemAdapter (Flysystem's storage-specific implementation). This two-level wrapping enables the adapter to delegate operations efficiently while retaining access to adapter-specific features.

Sources: src/FilesystemAdapter.php50-92 src/Contracts/Cloud.php1-50

Core Components

The FilesystemAdapter constructor initializes four key components:

Component	Type	Purpose
$driver	FilesystemOperator	Primary interface for file operations, delegates to Flysystem
$adapter	FlysystemAdapter	Low-level storage adapter, provides driver-specific features
$config	array	Configuration array containing driver settings, credentials, and options
$prefixer	PathPrefixer	Handles path prefixing for root directories and custom prefixes

Constructor Implementation:

The constructor at src/FilesystemAdapter.php75-92 performs the following initialization:

1. Stores the FilesystemOperator driver reference
2. Stores the FlysystemAdapter adapter reference
3. Stores the configuration array
4. Creates a PathPrefixer from the root and directory_separator config values
5. If a prefix is specified in config, applies an additional prefix layer

Sources: src/FilesystemAdapter.php75-92

Common Functionality

The FilesystemAdapter provides a comprehensive set of methods that are available to all driver implementations. These methods are organized into functional categories.

Path Management

Sources: src/FilesystemAdapter.php84-213

The path() method at src/FilesystemAdapter.php210-213 uses the PathPrefixer to convert relative paths to absolute paths based on the configured root and prefix values. The prefixer is initialized in the constructor at src/FilesystemAdapter.php84-91

File Operations (CRUD)

Method	Line Range	Description
exists()	162-165	Checks if a file or directory exists via $driver->has()
fileExists()	178-181	Specifically checks file existence
directoryExists()	194-197	Specifically checks directory existence
get()	218-227	Reads file contents via $driver->read()
put()	307-337	Writes content with support for strings, resources, streams, and UploadedFile
delete()	444-461	Deletes one or multiple files
copy()	466-477	Copies a file to a new location
move()	483-493	Moves a file to a new location

Sources: src/FilesystemAdapter.php162-493

Multi-Type Content Handling

The put() method at src/FilesystemAdapter.php307-337 demonstrates the adapter's ability to handle multiple content types:

Sources: src/FilesystemAdapter.php307-337

Stream Operations

Method	Line Range	Description
readStream()	546-555	Returns a resource handle for reading file contents
readStreamRange()	563-566	Base implementation throws RuntimeException (overridden by cloud drivers)
writeStream()	573-584	Writes a file from a resource handle

Sources: src/FilesystemAdapter.php546-584

URL Generation

The adapter provides flexible URL generation with fallback mechanisms:

Sources: src/FilesystemAdapter.php591-646

The URL generation logic at src/FilesystemAdapter.php591-646 checks multiple sources in order:

1. Apply path prefix if configured
2. Check if adapter has getUrl() method
3. Check if driver has getUrl() method
4. Fall back to FTP-specific URL logic for FtpAdapter/SftpAdapter
5. Fall back to local URL logic for LocalAdapter
6. Throw RuntimeException if no URL generation method is available

Metadata Operations

Method	Line Range	Return Type	Description
size()	498-501	int	File size in bytes via $driver->fileSize()
mimeType()	522-531	string|false	MIME type detection
lastModified()	536-539	int	Unix timestamp of last modification
checksum()	508-517	string|false	File checksum/hash
getVisibility()	392-399	string	Returns public or private
setVisibility()	404-415	bool	Sets file visibility

Sources: src/FilesystemAdapter.php392-539

Directory Operations

Method	Line Range	Description
files()	716-727	Lists files in a directory (optionally recursive)
allFiles()	732-735	Lists all files recursively
directories()	740-750	Lists subdirectories (optionally recursive)
allDirectories()	755-758	Lists all subdirectories recursively
makeDirectory()	763-774	Creates a directory
deleteDirectory()	779-790	Recursively deletes a directory

Sources: src/FilesystemAdapter.php716-790

Exception Handling

All operations that can fail wrap Flysystem exceptions and respect the throw configuration option:

Sources: src/FilesystemAdapter.php845-848

The throwsExceptions() method at src/FilesystemAdapter.php845-848 checks the throw configuration option. When false, operations return false or null instead of throwing exceptions. This pattern appears throughout the adapter in methods like:

• get() at src/FilesystemAdapter.php218-227
• put() at src/FilesystemAdapter.php330-336
• delete() at src/FilesystemAdapter.php454-457
• And many others

HTTP Response Integration

The FilesystemAdapter provides seamless integration with HTTP responses for serving files:

Method	Line Range	Purpose
response()	242-284	Creates a streamed HTTP response with proper headers
download()	289-292	Creates a download response with Content-Disposition: attachment

Sources: src/FilesystemAdapter.php242-292

Response Flow

Sources: src/FilesystemAdapter.php242-284

The response generation at src/FilesystemAdapter.php242-284 includes:

1. Automatic MIME type detection via mimeType()
2. Content-Disposition header generation with filename encoding
3. Range request support for partial content delivery
4. Chunked streaming with configurable buffer size (64KB)

Method Delegation and Magic Methods

The FilesystemAdapter uses PHP's magic __call() method to delegate unknown method calls directly to the underlying Flysystem driver:

Sources: src/FilesystemAdapter.php859-866

The delegation at src/FilesystemAdapter.php859-866 enables:

1. Access to all Flysystem FilesystemOperator methods without explicit wrapper methods
2. Forward compatibility with future Flysystem versions
3. Support for custom methods via the Macroable trait

This means methods like listContents(), publicUrl(), and others from Flysystem are automatically available on any FilesystemAdapter instance.

Traits and Extensibility

Macroable Trait

The FilesystemAdapter uses the Macroable trait from src/FilesystemAdapter.php53-55 to allow runtime method additions:

Sources: src/FilesystemAdapter.php53-55

Conditionable Trait

The Conditionable trait at src/FilesystemAdapter.php52 enables fluent conditional execution:

Sources: src/FilesystemAdapter.php52

Driver Implementation Pattern

Concrete driver implementations extend FilesystemAdapter and override specific methods to provide driver-specific functionality:

Sources: src/FilesystemAdapter.php50 src/LocalFilesystemAdapter.php1-100 src/AwsS3V3Adapter.php1-100 src/GoogleCloudStorageAdapter.php1-100

Common Override Patterns

Concrete drivers typically override the following methods:

Method	Why Override	Drivers That Override
temporaryUrl()	Provide signed URL generation	LocalFilesystemAdapter, AwsS3V3Adapter, GoogleCloudStorageAdapter
url()	Provide driver-specific public URL logic	LocalFilesystemAdapter, AwsS3V3Adapter, GoogleCloudStorageAdapter
readStreamRange()	Enable partial content reading	GoogleCloudStorageAdapter
temporaryUploadUrl()	Generate pre-signed upload URLs	AwsS3V3Adapter

Method Call Resolution Order

When a method is called on a driver instance:

Sources: src/FilesystemAdapter.php859-866

This resolution order allows:

1. Driver-specific implementations to override base behavior
2. Base functionality to be shared across all drivers
3. Macros to extend functionality at runtime
4. Direct access to Flysystem features via delegation

Temporary URL Callback

The adapter supports custom temporary URL generation logic via the buildTemporaryUrlsUsing() method:

Sources: src/FilesystemAdapter.php70-840

The callback mechanism at src/FilesystemAdapter.php837-840 allows applications to override default temporary URL generation without subclassing. The callback is bound to the adapter instance, providing access to $this->driver, $this->adapter, and $this->config.

Configuration Integration

The FilesystemAdapter respects various configuration options from the $config array:

Config Key	Type	Purpose	Used In
root	string	Root directory path	Constructor84-87
prefix	string	Additional path prefix	Constructor89-91
directory_separator	string	Path separator (default: DIRECTORY_SEPARATOR)	Constructor86
throw	bool	Whether to throw exceptions on errors	throwsExceptions()847
url	string	Base URL for public file access	getLocalUrl()632-634 getFtpUrl()619-621

Sources: src/FilesystemAdapter.php60-848

The configuration array is accessible via getConfig() at src/FilesystemAdapter.php811-814 and is passed through to driver implementations for use in specialized functionality.

---

The FilesystemAdapter serves as the critical bridge between the Hypervel framework features and League Flysystem's storage abstractions. By providing a rich set of common functionality while maintaining flexibility for driver-specific implementations, it enables a consistent API across all storage backends while allowing specialized capabilities where needed.