Filesystem Drivers

Filesystem drivers provide the abstraction layer between the Hypervel filesystem API and various storage backends. Each driver implements a consistent interface for file operations while handling the specifics of different storage systems including local disks, cloud storage (AWS S3, Google Cloud Storage), and network filesystems (FTP, SFTP).

The package includes five built-in driver types and supports custom driver registration. All drivers are built on League Flysystem adapters, with Hypervel adding framework-specific features such as HTTP response integration, connection pooling for cloud drivers, and temporary URL generation.

This page provides an overview of available drivers, their capabilities, and guidance on choosing the appropriate driver for your use case. For detailed driver architecture information, see page 3.1. For driver-specific configuration and implementation details, see pages 3.2 (Local), 3.3.1 (AWS S3), and 3.3.2 (Google Cloud Storage).

Sources: src/FilesystemAdapter.php1-92 src/FilesystemManager.php1-61

Available Drivers

The package includes six driver types, each targeting different storage backends:

Driver	Driver Name	Adapter Class	Package Required	Use Case
Local	local	LocalFilesystemAdapter	league/flysystem	Self-hosted storage, development, direct filesystem access
AWS S3	s3	AwsS3V3Adapter	league/flysystem-aws-s3-v3	Scalable cloud storage, S3-compatible services
Google Cloud Storage	gcs	GoogleCloudStorageAdapter	league/flysystem-google-cloud-storage	GCP-hosted applications, Google Cloud ecosystem
FTP	ftp	FilesystemAdapter	league/flysystem-ftp, ext-ftp	Legacy FTP servers
SFTP	sftp	FilesystemAdapter	league/flysystem-sftp-v3	Secure file transfer over SSH
Scoped	scoped	Wraps parent disk	N/A	Path-restricted access to existing disk

Sources: src/LocalFilesystemAdapter.php1-92 src/AwsS3V3Adapter.php1-125 src/GoogleCloudStorageAdapter.php1-141 src/FilesystemManager.php174-375 composer.json43-49

Driver Categories

Drivers are organized into four functional categories:

Local Storage:

• Local Driver: Direct filesystem access with configurable permissions and optional signed URL support. Created via FilesystemManager::createLocalDriver().

Cloud Storage (Poolable):

• AWS S3 Driver: AWS S3 integration using S3Client. Supports presigned URLs, streaming, and ACL-based visibility. Created via FilesystemManager::createS3Driver().
• Google Cloud Storage Driver: GCS integration using StorageClient. Supports signed URLs, streaming, and range requests. Created via FilesystemManager::createGcsDriver().

Cloud drivers are poolable, meaning the FilesystemManager automatically wraps them in FilesystemPoolProxy for connection reuse in long-running processes.

Network Protocols:

• FTP Driver: Connects to FTP servers using ext-ftp. Created via FilesystemManager::createFtpDriver().
• SFTP Driver: Connects to SFTP servers using phpseclib. Created via FilesystemManager::createSftpDriver().

Virtual:

• Scoped Driver: Creates a path-prefixed view of an existing disk using Flysystem's PathPrefixing adapter. Created via FilesystemManager::createScopedDriver().

Sources: src/FilesystemManager.php61 src/FilesystemManager.php174-202 src/FilesystemManager.php242-264 src/FilesystemManager.php287-314 src/FilesystemManager.php207-217 src/FilesystemManager.php222-237 src/FilesystemManager.php356-375

Driver Instantiation Flow

The FilesystemManager handles driver instantiation through a resolution process that determines which driver to create based on disk configuration.

Diagram: Driver Resolution and Instantiation

Sources: src/FilesystemManager.php82-87 src/FilesystemManager.php124-161 src/FilesystemManager.php61 src/FilesystemManager.php470-479

Resolution Process

The FilesystemManager::resolve() method follows this process:

1. Configuration Lookup: Retrieves disk configuration from filesystems.disks.{name} via getConfig().
2. Driver Validation: Checks that config['driver'] is set, throws InvalidArgumentException if missing.
3. Custom Driver Check: Looks for driver in $customCreators array registered via extend().
4. Built-in Driver Check: Looks for method create{Driver}Driver() on the manager (e.g., createLocalDriver()).
5. Pooling Decision: Checks if driver name is in $poolables array (currently ['s3', 'gcs']).
6. Instantiation: Creates driver via custom creator or built-in method, optionally wrapping in FilesystemPoolProxy.

Sources: src/FilesystemManager.php124-161 src/FilesystemManager.php417-421 src/FilesystemManager.php470-479

Driver Factory Methods

The FilesystemManager provides factory methods for each built-in driver:

Method	Driver	Returns	Flysystem Adapter
createLocalDriver()	local	LocalFilesystemAdapter	LocalAdapter
createS3Driver()	s3	AwsS3V3Adapter	S3Adapter
createGcsDriver()	gcs	GoogleCloudStorageAdapter	GcsAdapter
createFtpDriver()	ftp	FilesystemAdapter	FtpAdapter
createSftpDriver()	sftp	FilesystemAdapter	SftpAdapter
createScopedDriver()	scoped	Recursive	PathPrefixedAdapter

Each factory method:

1. Formats driver-specific configuration (e.g., formatS3Config() for S3)
2. Creates the Flysystem adapter with appropriate options
3. Wraps adapter in FilesystemOperator via createFlysystem()
4. Returns driver instance (specialized adapter or base FilesystemAdapter)

Sources: src/FilesystemManager.php174-202 src/FilesystemManager.php242-264 src/FilesystemManager.php287-314 src/FilesystemManager.php207-217 src/FilesystemManager.php222-237 src/FilesystemManager.php356-375 src/FilesystemManager.php380-400

Contract Implementation

All drivers implement the Filesystem contract, which defines the core file operation interface. Drivers that support URL generation also implement the Cloud contract, which extends Filesystem with URL-related methods.

Diagram: Contract and Class Hierarchy

Sources: src/Contracts/Filesystem.php7 src/Contracts/Cloud.php7 src/FilesystemAdapter.php50 src/LocalFilesystemAdapter.php12 src/AwsS3V3Adapter.php12 src/GoogleCloudStorageAdapter.php13

Filesystem Contract

The Filesystem contract defines core operations:

• Existence checks: exists(), fileExists(), directoryExists()
• Read operations: get(), readStream(), json()
• Write operations: put(), writeStream(), putFile(), putFileAs()
• File operations: copy(), move(), delete(), append(), prepend()
• Metadata: size(), mimeType(), lastModified(), checksum()
• Directory operations: files(), directories(), allFiles(), allDirectories(), makeDirectory(), deleteDirectory()
• Visibility: getVisibility(), setVisibility()

Sources: src/Contracts/Filesystem.php7-66

Cloud Contract

The Cloud contract extends Filesystem with URL generation capabilities:

• url(string $path): string - Generate public URL for file
• temporaryUrl(string $path, DateTimeInterface $expiration, array $options = []): string - Generate temporary/signed URL
• temporaryUploadUrl(string $path, DateTimeInterface $expiration, array $options = []): array|string - Generate URL for direct uploads

Only drivers with URL generation support implement this contract. The base FilesystemAdapter provides default implementations that delegate to the underlying Flysystem adapter or throw RuntimeException if unsupported.

Sources: src/Contracts/Cloud.php7-13 src/FilesystemAdapter.php591-612 src/FilesystemAdapter.php661-676

Flysystem Integration

The driver architecture leverages League Flysystem as the underlying abstraction layer, with Hypervel drivers adding framework-specific features and conveniences:

Sources: src/FilesystemAdapter.php75-92 src/FilesystemAdapter.php859-866 src/FilesystemAdapter.php23-24