Architecture

Purpose and Scope

This document provides a high-level overview of the Hypervel Filesystem package architecture, explaining how components are organized into layers, how they interact at runtime, and how the system integrates with the Hyperf framework. It covers the core architectural patterns, component responsibilities, and the flow of data through the system.

For detailed information about specific components, see:

• Driver implementations: Filesystem Drivers
• Contracts and their methods: Contracts and Interfaces
• Extension mechanisms: Extending and Customization

---

System Layers

The Hypervel Filesystem package is organized into five distinct architectural layers, each with specific responsibilities:

Sources: composer.json1-63 src/FilesystemManager.php1-501 src/ConfigProvider.php1-32

Layer Responsibilities

Layer	Components	Responsibility
Application Layer	User code, configuration files	Consumes filesystem services through contracts
Framework Integration	ConfigProvider, DI bindings	Registers services with Hyperf container and publishes configuration
Factory Layer	FilesystemManager, factory classes	Creates and caches filesystem instances based on configuration
Abstraction Layer	FilesystemAdapter, FilesystemPoolProxy	Provides base implementation and pooling wrapper for drivers
Driver Layer	Concrete adapter implementations	Implements storage-specific logic for different backends

Sources: src/ConfigProvider.php11-31 src/FilesystemManager.php35-69

---

Core Component Architecture

The following diagram shows the key classes and their relationships in code:

Sources: src/FilesystemManager.php39-70 src/ConfigProvider.php11-20

Component Descriptions

FilesystemManager

The FilesystemManager class src/FilesystemManager.php39-500 is the central orchestrator of the entire system. It implements the Factory contract and manages the lifecycle of all filesystem instances.

Key responsibilities:

• Driver Resolution: Maps configuration to concrete driver implementations src/FilesystemManager.php124-161
• Instance Caching: Maintains a $disks array to cache resolved instances src/FilesystemManager.php46-86
• Pooling Logic: Wraps cloud drivers (S3, GCS) in FilesystemPoolProxy based on $poolables array src/FilesystemManager.php61-158
• Custom Drivers: Supports registration of custom drivers via extend() method src/FilesystemManager.php470-479
• Configuration Access: Retrieves disk configuration from Hyperf's ConfigInterface src/FilesystemManager.php417-421

FilesystemAdapter

The FilesystemAdapter class provides the base implementation for all filesystem drivers. It wraps League Flysystem's FilesystemOperator and adds framework-specific functionality.

Key characteristics:

• Implements the Cloud contract (which extends Filesystem)
• Contains a FilesystemOperator $driver property for Flysystem integration
• Holds the underlying FlysystemAdapter $adapter for direct adapter access
• Stores configuration in array $config property

Sources: src/FilesystemManager.php39-90

FilesystemPoolProxy

The FilesystemPoolProxy class src/FilesystemManager.php56 implements connection pooling for cloud storage drivers. It uses the hypervel/object-pool library to manage a pool of reusable adapter instances, improving performance in coroutine environments like Swoole/Hyperf.

Key features:

• Wraps driver creation logic in a Closure
• Delegates method calls via __call() magic method
• Configured via the pool key in driver configuration
• Only applied to drivers listed in $poolables array src/FilesystemManager.php61

Sources: src/FilesystemManager.php54-61 composer.json37

---

Framework Integration Architecture

The system integrates deeply with the Hyperf framework through dependency injection:

Sources: src/ConfigProvider.php11-31 composer.json55-58

Dependency Injection Bindings

The ConfigProvider class src/ConfigProvider.php11-20 registers three key bindings:

Contract	Implementation	Type
Hypervel\Filesystem\Contracts\Factory	FilesystemManager	Singleton
Hypervel\Filesystem\Contracts\Filesystem	FilesystemFactory	Factory
Hypervel\Filesystem\Contracts\Cloud	CloudStorageFactory	Factory

The FilesystemManager is resolved as a singleton, ensuring consistent state. The factory classes are invokable wrappers that delegate to FilesystemManager to obtain disk instances.

Sources: src/ConfigProvider.php16-19

Configuration Publishing

The ConfigProvider also defines a publishable configuration file src/ConfigProvider.php21-28:

• Source: publish/filesystems.php in the package
• Destination: config/autoload/filesystems.php in the application
• Purpose: Allows users to define their disk configurations

Sources: src/ConfigProvider.php22-27

---

Driver Creation Flow

The following diagram illustrates how the system resolves and creates driver instances:

Sources: src/FilesystemManager.php82-161

Resolution Steps

1. Cache Check src/FilesystemManager.php114-117: The manager first checks if the disk is already cached in $disks array
2. Configuration Retrieval src/FilesystemManager.php126: Fetches configuration from filesystems.disks.{name}
3. Driver Type Extraction src/FilesystemManager.php128-132: Validates and extracts the driver key
4. Custom Driver Check src/FilesystemManager.php135-144: Checks if a custom creator is registered
5. Poolability Check src/FilesystemManager.php133: Determines if driver should be wrapped in FilesystemPoolProxy
6. Method Resolution src/FilesystemManager.php146-150: Constructs method name like createLocalDriver
7. Driver Creation src/FilesystemManager.php160: Invokes the appropriate creator method
8. Caching src/FilesystemManager.php86: Stores the result in $disks array
9. Return: Returns the filesystem instance

Sources: src/FilesystemManager.php124-161

---

Architectural Patterns

Factory Pattern

The system uses the Factory pattern extensively:

Benefits:

• Centralizes instantiation logic
• Allows runtime driver selection based on configuration
• Supports extensibility through custom creators
• Enables driver-specific configuration handling

Sources: src/FilesystemManager.php39 src/FilesystemManager.php174-375

Adapter Pattern

The FilesystemAdapter class adapts League Flysystem's interface to the framework's contracts:

Flysystem API	Framework API	Adapter Responsibility
FilesystemOperator	Filesystem contract	Wraps Flysystem and exposes framework methods
Low-level operations	High-level convenience methods	Adds helper methods like putFile(), download()
Generic storage	Cloud-specific features	Extended by cloud adapters for URLs, uploads

Sources: src/FilesystemManager.php192-263

Decorator Pattern (Pooling)

The FilesystemPoolProxy decorates filesystem instances with pooling capabilities:

Characteristics:

• Transparent to client code (implements same interface)
• Only applied to specific drivers (S3, GCS) src/FilesystemManager.php61
• Configuration controlled via pool key in disk config
• Uses __call() magic method to forward all method calls

Sources: src/FilesystemManager.php133-158

---

Configuration Architecture

The system's configuration flows from multiple sources:

Sources: src/FilesystemManager.php417-439 src/ConfigProvider.php21-28

Configuration Structure

Each disk configuration contains:

• driver (required): Driver type (local, s3, gcs, ftp, sftp, scoped)
• driver-specific keys: Credentials, endpoints, paths specific to the driver
• pool (optional): Pooling configuration for cloud drivers
• visibility (optional): Default visibility (public or private)
• read-only (optional): Enable read-only mode
• prefix (optional): Path prefix for scoped access

Sources: src/FilesystemManager.php124-400

---

Dependency Management

The package's dependencies are carefully organized:

Dependency Type	Packages	Purpose
Required	hyperf/collection, hyperf/macroable, hyperf/support, hyperf/conditionable	Core framework integration
Required	hypervel/object-pool	Connection pooling for cloud drivers
Suggested	league/flysystem* packages	Optional driver implementations
Extensions	ext-fileinfo, ext-hash	File operations support

The suggested dependencies follow a lazy-loading pattern: drivers are only required when actually configured, keeping the package lightweight.

Sources: composer.json31-51

---

Error Handling Strategy

The architecture employs defensive error handling:

1. Configuration Validation src/FilesystemManager.php128-130: Throws InvalidArgumentException if driver not configured
2. Driver Validation src/FilesystemManager.php148-150: Throws exception if unsupported driver
3. Scoped Driver Validation src/FilesystemManager.php358-363: Validates required configuration keys
4. Flysystem Integration: Delegates storage-level exceptions to Flysystem layer

Sources: src/FilesystemManager.php124-375

---

Summary

The Hypervel Filesystem architecture follows a layered design with clear separation of concerns:

• Framework Integration Layer: Deep integration with Hyperf via DI container
• Factory Layer: Central orchestration through FilesystemManager
• Abstraction Layer: Base implementation and pooling wrapper
• Driver Layer: Storage-specific implementations

Key architectural decisions include:

• Factory pattern for flexible driver creation
• Adapter pattern for Flysystem integration
• Decorator pattern for transparent connection pooling
• Lazy dependency loading for minimal footprint
• Contract-driven design for extensibility

Sources: composer.json1-63 src/FilesystemManager.php1-501 src/ConfigProvider.php1-32