 |
VOOZH | about |
|
VOOZH | about |
This page provides an overview of cloud storage driver support in the hypervel/filesystem package, covering features and capabilities shared across all cloud storage implementations. Cloud storage drivers enable applications to interact with remote object storage services through a unified interface.
For driver-specific configuration and features, see:
For details on the base driver architecture that all drivers inherit from, see Driver Architecture and FilesystemAdapter.
For information on connection pooling optimization specific to cloud drivers, see Object Pooling for Cloud Drivers.
The hypervel/filesystem package supports two major cloud storage providers:
| Provider | Driver Name | Flysystem Package | Cloud SDK |
|---|---|---|---|
| Amazon S3 | s3 | league/flysystem-aws-s3-v3 | aws/aws-sdk-php |
| Google Cloud Storage | gcs | league/flysystem-google-cloud-storage | google/cloud-storage |
Both drivers are optional dependencies listed in the suggest section of composer.json46-47 Applications only need to install the specific cloud storage packages they intend to use.
Sources: composer.json1-63
Cloud storage drivers differ from local and network filesystem drivers in several important ways:
All cloud storage drivers implement the Cloud interface src/Contracts/Cloud.php7-13 which extends the base Filesystem interface with URL generation capabilities:
Diagram: Cloud Interface Hierarchy
The url() method enables cloud drivers to generate publicly accessible URLs for stored files, a capability not available to local filesystem drivers.
Sources: src/Contracts/Cloud.php1-14
Cloud storage drivers utilize connection pooling via FilesystemPoolProxy to optimize performance. Cloud SDK clients (AWS S3Client, Google StorageClient) are expensive to instantiate, making connection reuse critical for high-throughput applications.
Local and network protocol drivers (FTP, SFTP) bypass pooling as their connection overhead is minimal.
Sources: High-level architecture diagrams (Diagram 3)
Cloud drivers require network connectivity to external services and appropriate credentials (API keys, service accounts). Configuration includes:
Local drivers have no external dependencies beyond filesystem permissions.
The CloudStorageFactory class provides a convenience mechanism for resolving cloud storage instances from the dependency injection container.
src/CloudStorageFactory.php11-18
class CloudStorageFactory
{
public function __invoke(ContainerInterface $container): CloudContract
{
return $container->get(FactoryContract::class)
->cloud(CloudContract::class);
}
}
The factory:
Factory contract (implemented by FilesystemManager)cloud() method to retrieve the cloud disk instanceCloud interfaceDiagram: CloudStorageFactory Resolution Flow
The cloud() method on FilesystemManager resolves to the disk specified in the Cloud::class configuration key, typically pointing to the default cloud disk.
Sources: src/CloudStorageFactory.php1-19
All cloud drivers implement URL generation methods for accessing stored files:
| Method | Purpose | Availability |
|---|---|---|
url($path) | Public permanent URL | S3, GCS |
temporaryUrl($path, $expiration) | Time-limited signed URL | S3, GCS |
temporaryUploadUrl($path, $expiration) | Pre-signed upload URL | S3 only |
For comprehensive documentation on URL generation, including configuration options and security considerations, see URL Generation.
Cloud drivers support efficient streaming operations:
readStream($path) returns a PSR-7 compatible streamwriteStream($path, $stream) uploads from a stream resourceFor detailed streaming documentation, see Streaming and Content Handling.
Cloud drivers automatically detect and set appropriate Content-Type headers:
Both S3 and GCS drivers support file visibility management:
Visibility is configured per-file or set as default for the disk.
Sources: High-level architecture diagrams, src/Contracts/Cloud.php1-14
Diagram: Cloud Driver Creation Process
The instantiation flow highlights the layering:
FilesystemManager reads disk configurationAwsS3V3Adapter/GoogleCloudStorageAdapter) wraps FlysystemFilesystemPoolProxy wraps the adapter for connection poolingSources: High-level architecture diagrams (Diagram 3)
Cloud storage drivers share common configuration structure:
| Key | Purpose | Example |
|---|---|---|
driver | Driver identifier | 's3' or 'gcs' |
key | Access key/credentials | AWS access key or GCS project ID |
secret | Secret key/credentials | AWS secret key or GCS service account |
region | Storage region | 'us-east-1' (S3) or 'us-central1' (GCS) |
bucket | Bucket/container name | 'my-app-files' |
| Key | Purpose | Default |
|---|---|---|
url | Custom base URL | Generated from region/bucket |
endpoint | Custom service endpoint | AWS/Google default endpoints |
visibility | Default file visibility | 'private' |
throw | Throw exceptions on errors | false |
root | Path prefix for all operations | '' (root) |
For comprehensive configuration reference, see Configuration Reference.
Sources: High-level architecture diagrams (Diagram 3)
Cloud drivers support connection pool configuration to optimize resource utilization:
'disks' => [
's3' => [
'driver' => 's3',
// ... S3 configuration
'pool' => [
'min_connections' => 1,
'max_connections' => 10,
'wait_timeout' => 3.0,
'max_idle_time' => 60.0,
],
],
],
Pool configuration keys:
| Key | Purpose | Default |
|---|---|---|
min_connections | Minimum connections maintained | 1 |
max_connections | Maximum concurrent connections | 10 |
wait_timeout | Seconds to wait for available connection | 3.0 |
max_idle_time | Seconds before idle connection is closed | 60.0 |
For detailed pooling documentation, see Object Pooling for Cloud Drivers.
Sources: High-level architecture diagrams
Choose S3 when:
S3 Advantages:
Choose GCS when:
GCS Advantages:
For provider-specific features and configuration, see:
Sources: composer.json46-47
Both packages automatically install their respective cloud SDKs as dependencies.
Sources: composer.json46-47
Cloud storage drivers in hypervel/filesystem provide:
Cloud contract extends Filesystem with URL generationFilesystemPoolProxy for performance optimizationThe CloudStorageFactory provides dependency injection integration, while individual driver implementations (AwsS3V3Adapter, GoogleCloudStorageAdapter) add provider-specific functionality.
Sources: src/CloudStorageFactory.php1-19 src/Contracts/Cloud.php1-14 composer.json1-63
Refresh this wiki