 |
VOOZH | about |
|
VOOZH | about |
This document explains the fundamental architectural concepts that underpin the Hypervel Filesystem package. It covers disks, drivers, the Factory pattern implementation, contract-based abstractions, and configuration-driven behavior. Understanding these concepts is essential for working effectively with the package.
For implementation details of specific drivers, see Filesystem Drivers. For advanced usage patterns like pooling and custom drivers, see Advanced Features and Extending and Customization.
A disk represents a named, configured storage instance in your application. Each disk is defined in the filesystems.php configuration file and corresponds to a specific storage backend (local directory, S3 bucket, GCS bucket, etc.).
| Characteristic | Description |
|---|---|
| Name | A unique identifier (e.g., 'local', 's3', 'backup') used to retrieve the disk instance |
| Driver | The storage backend type ('local', 's3', 'gcs', 'ftp', 'sftp') |
| Configuration | Driver-specific settings like paths, credentials, visibility, pooling options |
| Lifecycle | Created on first access and cached by FilesystemManager for reuse |
The FilesystemManager maintains a cache of resolved disk instances in its $disks property src/FilesystemManager.php46 When you call disk('s3'), the manager either returns the cached instance or creates a new one by resolving the configuration.
Sources:
A driver is the implementation adapter that handles storage operations for a specific backend technology. Each driver translates the unified Filesystem API into backend-specific operations.
| Driver | Class | Backend | Poolable | Cloud Interface |
|---|---|---|---|---|
local | LocalFilesystemAdapter | Local filesystem | No | Yes |
s3 | AwsS3V3Adapter | Amazon S3 | Yes | Yes |
gcs | GoogleCloudStorageAdapter | Google Cloud Storage | Yes | Yes |
ftp | FilesystemAdapter | FTP server | No | No |
sftp | FilesystemAdapter | SFTP server | No | No |
scoped | Dynamic | Prefixed sub-disk | Inherits | Inherits |
The FilesystemManager uses naming conventions to create drivers. For each driver type, there is a corresponding creator method:
createLocalDriver() src/FilesystemManager.php174-202createS3Driver() src/FilesystemManager.php242-264createGcsDriver() src/FilesystemManager.php287-314createFtpDriver() src/FilesystemManager.php207-217createSftpDriver() src/FilesystemManager.php222-237createScopedDriver() src/FilesystemManager.php356-375The manager constructs the method name dynamically: 'create' . ucfirst($driver) . 'Driver' src/FilesystemManager.php146
Sources:
The package implements the Factory pattern through the Factory contract and its concrete implementation, FilesystemManager. This pattern centralizes instance creation, configuration, and caching.
The Factory interface defines a single method:
public function disk(?string $name = null): Filesystem;
This contract is implemented by FilesystemManager src/FilesystemManager.php39
| Responsibility | Implementation |
|---|---|
| Configuration Resolution | getConfig() reads from filesystems.disks.{name} src/FilesystemManager.php417-421 |
| Driver Creation | Dynamic method dispatch to create{Driver}Driver() methods |
| Instance Caching | Stores created instances in $disks array src/FilesystemManager.php46 |
| Default Drivers | getDefaultDriver() and getDefaultCloudDriver() src/FilesystemManager.php426-439 |
| Custom Drivers | extend() method registers custom creators src/FilesystemManager.php470-479 |
| Pooling Management | $poolables array and createPoolProxy() method src/FilesystemManager.php61 |
Sources:
The package uses interface-based design to ensure all drivers implement a consistent API. This allows polymorphic usage - any driver can be swapped for another without changing application code.
Defines how to obtain filesystem instances. Implemented by FilesystemManager.
| Method | Return Type | Purpose |
|---|---|---|
disk(?string $name) | Filesystem | Get a named disk instance |
The base interface defining core storage operations. All drivers must implement this interface either directly or through FilesystemAdapter.
| Operation Category | Methods |
|---|---|
| File Operations | exists(), get(), put(), delete(), copy(), move() |
| Stream Operations | readStream(), readStreamRange(), writeStream() |
| Upload Operations | putFile(), putFileAs() |
| Metadata Operations | size(), lastModified(), getVisibility(), setVisibility() |
| Directory Operations | files(), allFiles(), directories(), allDirectories(), makeDirectory(), deleteDirectory() |
| Text Operations | prepend(), append() |
src/Contracts/Filesystem.php11-155
Extends Filesystem with URL generation capabilities for cloud storage. Implemented by cloud drivers (AwsS3V3Adapter, GoogleCloudStorageAdapter) and LocalFilesystemAdapter.
| Method | Return Type | Purpose |
|---|---|---|
url(string $path) | string | Get public URL for a file |
The Filesystem interface defines two visibility constants:
Filesystem::VISIBILITY_PUBLIC - 'public' src/Contracts/Filesystem.php18Filesystem::VISIBILITY_PRIVATE - 'private' src/Contracts/Filesystem.php25These constants are used throughout the system to control file access permissions.
Sources:
The entire system is driven by configuration arrays. Each disk's behavior is determined by its configuration, which is read from config/autoload/filesystems.php.
filesystems:
default: 'local' # Default disk name
cloud: 's3' # Default cloud disk name
disks:
disk_name:
driver: 'local|s3|gcs|...' # Driver type
...driver-specific options... # Credentials, paths, etc.
pool: [...] # Pooling config (optional)
prefix: '...' # Path prefix (optional)
read-only: true|false # Read-only mode (optional)
The manager resolves configuration in this order:
disk('name') → reads filesystems.disks.name src/FilesystemManager.php417-421disk() → reads filesystems.default src/FilesystemManager.php426-430cloud() → reads filesystems.cloud src/FilesystemManager.php435-439build($config) → uses provided config directly src/FilesystemManager.php103-109The manager determines which driver to create based on the driver key:
$customCreators src/FilesystemManager.php135-143'create' . ucfirst($driver) . 'Driver' src/FilesystemManager.php146Sources:
The system uses multiple abstraction layers to separate concerns and provide flexibility.
| Layer | Components | Responsibility |
|---|---|---|
| Contract Layer | Factory, Filesystem, Cloud | Define interface contracts |
| Manager Layer | FilesystemManager | Create, configure, cache instances |
| Adapter Layer | FilesystemAdapter, LocalFilesystemAdapter, etc. | Implement contracts, add features |
| Flysystem Layer | League\Flysystem\Filesystem, FlysystemAdapter | Low-level storage operations |
| SDK Layer | S3Client, StorageClient | Cloud provider APIs |
All drivers are built on top of League Flysystem src/FilesystemManager.php380-400 The createFlysystem() method:
ReadOnlyFilesystemAdapter if read-only is true src/FilesystemManager.php382-385PathPrefixedAdapter if prefix is set src/FilesystemManager.php387-390Flysystem instance with configuration src/FilesystemManager.php392-399This layering allows the package to leverage Flysystem's battle-tested implementations while adding framework-specific features like pooling, URL generation, and HTTP responses.
Sources:
The manager maintains a $poolables array containing drivers that support connection pooling src/FilesystemManager.php61 Currently, only cloud drivers ('s3' and 'gcs') are poolable.
When resolving a poolable driver, the manager:
$poolables src/FilesystemManager.php133FilesystemPoolProxy src/FilesystemManager.php136-141$config['pool'] src/FilesystemManager.php140Custom drivers can be registered using the extend() method src/FilesystemManager.php470-479:
Parameters:
- string $driver: Driver name
- Closure $callback: Creator function
- bool $poolable: Whether to enable pooling (default: false)
The callback receives ($app, $config) and must return a Filesystem instance src/FilesystemManager.php168
The build() method creates temporary disk instances without caching src/FilesystemManager.php103-109:
Sources:
Refresh this wiki