 |
VOOZH | about |
|
VOOZH | about |
This document provides an overview of the extensibility mechanisms available in the Hypervel Filesystem package. The system is designed to support custom drivers, behavior modifications, and flexible configuration to meet diverse storage requirements beyond the built-in drivers.
For detailed instructions on creating custom drivers, see Creating Custom Drivers. For a comprehensive reference of all configuration options, see Configuration Reference.
The Hypervel Filesystem package provides multiple extension points that allow developers to customize behavior without modifying the core library. These extension points follow standard design patterns to ensure compatibility and maintainability.
| Mechanism | Purpose | Implementation Location |
|---|---|---|
| Custom Drivers | Add support for new storage backends | FilesystemManager::extend() |
| Poolable Drivers | Enable connection pooling for custom drivers | FilesystemManager::addPoolable() |
| Temporary URL Callbacks | Customize URL generation logic | FilesystemAdapter::buildTemporaryUrlsUsing() |
| Macros | Add methods to adapter instances | Macroable trait |
| Configuration | Customize driver behavior and credentials | config/autoload/filesystems.php |
Sources:
The following diagram illustrates how custom extensions integrate with the core system architecture:
Diagram: Extension Registration and Resolution Flow
This diagram shows how extensions are registered via the extend(), macro(), and buildTemporaryUrlsUsing() methods, and how they are resolved at runtime. The FilesystemManager::resolve() method checks for custom creators in the customCreators array and optionally wraps them in a FilesystemPoolProxy if the driver is marked as poolable.
Sources:
The FilesystemManager class provides the extend() method to register custom filesystem drivers. This method accepts a driver name, a closure that creates the driver instance, and an optional flag to mark the driver as poolable.
The $callback closure receives two parameters:
ContainerInterface $app - The Hyperf DI containerarray $config - The configuration array for this diskDiagram: Custom Driver Registration and Resolution Sequence
This sequence diagram shows the two-phase lifecycle of custom drivers: registration via extend() and resolution via disk(). The customCreators array stores the callback, and if the driver is marked as poolable, it is added to the poolables array for automatic pool proxy wrapping.
Sources:
Custom drivers can opt into connection pooling by setting the $poolable parameter to true when calling extend(). This is particularly useful for drivers that maintain persistent connections or expensive client objects.
The built-in poolable drivers are defined in the $poolables array:
When a driver is marked as poolable:
FilesystemManager wraps the driver creator in createPoolProxy()FilesystemPoolProxy instance is created with pool configurationhypervel/object-pool$config['pool']The HasPoolProxy trait provides the addPoolable() method:
To mark an additional driver as poolable after initialization:
For more details on connection pooling behavior, see Object Pooling for Cloud Drivers.
Sources:
Beyond custom drivers, the system provides mechanisms to customize behavior of existing drivers.
The FilesystemAdapter supports custom temporary URL generation logic through the buildTemporaryUrlsUsing() method:
src/FilesystemAdapter.php837-840
The callback receives three parameters:
string $path - The file pathDateTimeInterface $expiration - The URL expiration timearray $options - Additional optionsWhen a custom callback is set, it takes precedence over the adapter's built-in getTemporaryUrl() method:
src/FilesystemAdapter.php661-676
The callback is bound to the adapter instance, allowing access to protected methods and properties.
The FilesystemAdapter uses the Macroable trait to support dynamic method addition:
src/FilesystemAdapter.php52-55
This allows adding custom methods to all adapter instances:
Macros are particularly useful for adding domain-specific helper methods without subclassing.
Sources:
All drivers support configuration-based customization through the config/autoload/filesystems.php file. The configuration array for each disk is passed to the driver creator and stored in the adapter.
Drivers receive configuration through the constructor:
src/FilesystemAdapter.php75-92
The configuration is accessible via:
getConfig() method src/FilesystemAdapter.php811-814$this->config property in subclasses| Configuration Key | Purpose | Example Value |
|---|---|---|
driver | Specifies which driver to use | 'local', 's3', 'custom' |
root | Base path for operations | '/var/storage' |
visibility | Default file visibility | 'public', 'private' |
throw | Whether to throw exceptions | true, false |
prefix | Path prefix for scoped access | 'uploads/' |
read-only | Enable read-only mode | true, false |
pool | Connection pool configuration | ['min' => 1, 'max' => 10] |
url | Base URL for public files | 'https://cdn.example.com' |
temporary_url | Temporary URL configuration | ['key' => '...'] |
Sources:
The following diagram shows all extensibility points and their relationships:
Diagram: Complete Extensibility Points Map
This diagram maps all extension mechanisms available in the system, organized by layer. Driver layer extensions affect which driver is instantiated, adapter layer extensions modify behavior of adapter instances, Flysystem layer extensions wrap the underlying adapter, pool layer extensions control connection pooling, and configuration extensions customize all aspects.
Sources:
Custom drivers are typically registered in a service provider or bootstrap file:
Extensions can be registered conditionally based on environment or configuration:
Sources:
Sources:
Refresh this wiki