 |
VOOZH | about |
|
VOOZH | about |
This document provides an overview of the Hypervel Filesystem package, a unified storage abstraction layer for the Hyperf framework. It introduces the package's purpose, key features, main components, and integration points.
For detailed configuration and setup instructions, see Installation and Configuration. For in-depth architectural details, see Architecture. For driver-specific documentation, see Filesystem Drivers.
Sources: composer.json1-63
The hypervel/filesystem package provides a unified, driver-based abstraction layer for interacting with various storage backends including local filesystems, cloud storage (AWS S3, Google Cloud Storage), and remote protocols (FTP, SFTP). Built on top of League Flysystem, the package extends the base functionality with Hyperf-specific optimizations, including connection pooling for cloud drivers, file locking mechanisms, and HTTP response integration.
The package is designed for applications running on the Hyperf framework with Swoole, where long-lived processes require efficient connection management and coroutine-safe operations. It abstracts storage operations behind consistent interfaces, allowing applications to switch storage backends without code changes.
Sources: composer.json1-11 composer.json31-50
The Hypervel Filesystem package provides the following capabilities:
| Feature Category | Capabilities | Available Drivers |
|---|---|---|
| Basic Operations | Read, write, delete, copy, move files and directories | All drivers |
| Streaming | Read/write streams for memory-efficient large file handling | Local, S3, GCS |
| URL Generation | Public URLs, temporary signed URLs, temporary upload URLs | Local, S3, GCS |
| Connection Pooling | Object pooling for high-concurrency environments | S3, GCS |
| File Locking | Shared and exclusive locks for atomic operations | Local |
| HTTP Integration | Direct HTTP responses, downloads, range requests | Local, S3, GCS |
| Path Management | Prefixing, scoped drivers, read-only modes | All drivers (via Flysystem extensions) |
| Metadata | File size, last modified time, MIME type, visibility | All drivers |
The package requires PHP 8.2+ and integrates deeply with Hyperf's dependency injection container, making filesystem instances available throughout the application via type-hinted constructors or the Factory contract.
Sources: composer.json31-38 composer.json39-50
The following diagram maps the major system components to their corresponding code entities:
| Component | File | Role |
|---|---|---|
ConfigProvider | src/ConfigProvider.php | Registers DI bindings and publishes configuration to Hyperf |
FilesystemManager | src/FilesystemManager.php | Central orchestrator; creates, caches, and manages driver instances |
FilesystemAdapter | src/FilesystemAdapter.php | Base adapter wrapping Flysystem with additional functionality |
FilesystemPoolProxy | src/FilesystemPoolProxy.php | Decorator for cloud drivers providing connection pooling |
LocalFilesystemAdapter | src/LocalFilesystemAdapter.php | Local disk storage with signed URL support |
AwsS3V3Adapter | src/AwsS3V3Adapter.php | AWS S3 integration with pre-signed URLs |
GoogleCloudStorageAdapter | src/GoogleCloudStorageAdapter.php | Google Cloud Storage with signed URL generation |
LockableFile | src/LockableFile.php | File locking for atomic operations on local storage |
Filesystem | src/Filesystem.php | Utility class with static helpers like ensureDirectoryExists |
join_paths() | src/Functions.php | Global helper function for path manipulation |
For detailed information on component architecture, see System Design and Component Interaction. For the factory pattern implementation, see Factory Pattern and FilesystemManager.
Sources: composer.json23-29
The package supports multiple storage backends through a driver-based architecture. Drivers are loaded on-demand based on configuration, and optional Flysystem adapter packages must be installed separately.
| Driver | Configuration Key | Required Package | Pooling Support | Signed URLs | Use Case |
|---|---|---|---|---|---|
| Local | local | league/flysystem | No | Yes (with route) | Development, self-hosted |
| AWS S3 | s3 | league/flysystem-aws-s3-v3 | Yes | Yes | Production cloud storage |
| Google Cloud Storage | gcs | league/flysystem-google-cloud-storage | Yes | Yes | Google Cloud Platform apps |
| FTP | ftp | league/flysystem-ftp | No | No | Legacy systems |
| SFTP | sftp | league/flysystem-sftp-v3 | No | No | Secure remote servers |
| Scoped | scoped | league/flysystem-path-prefixing | Inherited | Inherited | Path isolation |
| Read-Only | N/A (modifier) | league/flysystem-read-only | Inherited | Inherited | Immutable storage |
For driver-specific configuration, see Local Filesystem Driver, AWS S3 Driver, and Google Cloud Storage Driver. For pooling details, see Object Pooling for Cloud Drivers.
Sources: composer.json39-50
The package integrates with Hyperf through the dependency injection container. The ConfigProvider class registers bindings during application bootstrap, making filesystem instances available throughout the application.
Applications access filesystem functionality through three primary contracts:
The FilesystemManager is registered as a singleton (src/ConfigProvider.php) to ensure consistent state across the application. Driver instances are cached within the manager to avoid redundant initialization.
For contract details, see Contracts and Interfaces. For configuration specifics, see Installation and Configuration.
Sources: composer.json55-58
The package follows a layered architecture with clear separation between framework integration, driver management, and storage implementations.
| Principle | Implementation | Benefit |
|---|---|---|
| Contract-Based Design | Factory, Filesystem, and Cloud interfaces define public APIs | Polymorphic driver usage; easy mocking for tests |
| Adapter Pattern | FilesystemAdapter wraps Flysystem's FilesystemOperator | Consistent API across drivers; extensibility |
| Decorator Pattern | FilesystemPoolProxy wraps cloud adapters | Connection pooling without modifying driver code |
| Factory Pattern | FilesystemManager creates and caches driver instances | Centralized configuration; lazy initialization |
| Dependency Injection | All components registered in Hyperf DI container | Testability; loose coupling |
| Modular Dependencies | Core package is lightweight; drivers installed separately | Reduced deployment size; pay-for-what-you-use |
The package uses League Flysystem as its foundation to leverage battle-tested storage abstractions. The FilesystemAdapter base class (src/FilesystemAdapter.php) wraps Flysystem's FilesystemOperator and adds Hyperf-specific functionality like HTTP response generation, Macroable trait support, and enhanced error handling.
For cloud drivers (S3 and GCS), the FilesystemPoolProxy (src/FilesystemPoolProxy.php) provides connection pooling via the hypervel/object-pool library. This is critical in Swoole/Hyperf environments where a single process handles many concurrent requests. Without pooling, each request would create new SDK client instances, leading to connection overhead and resource exhaustion.
The FilesystemManager (src/FilesystemManager.php) serves as the central orchestrator, implementing the Factory contract. It resolves driver configurations from config/autoload/filesystems.php, creates driver instances using registered creator callbacks, and caches instances to avoid redundant initialization. The manager also supports custom driver registration via the extend() method, allowing applications to add proprietary storage backends.
For detailed architecture documentation, see System Design and Component Interaction. For extension points, see Creating Custom Drivers.
Sources: composer.json31-50
To begin using the Hypervel Filesystem package:
config/autoload/filesystems.phpFactory, Filesystem, or Cloud) into application codeFor conceptual understanding of disks, drivers, and the factory pattern, see Core Concepts. For driver selection guidance, refer to the Supported Storage Backends section above.
Sources: composer.json1-63