System Design and Component Interaction

Purpose and Scope

This document details how components in the Hypervel Filesystem package interact at runtime, from system initialization through operation execution. It covers the ConfigProvider's role in Hyperf framework integration, dependency injection container bindings, caching strategies, and the complete flow from application code to storage backends.

For contract definitions and interface specifications, see Contracts and Interfaces. For detailed information about the FilesystemManager's internal mechanisms, see Factory Pattern and FilesystemManager.

---

System Bootstrap and Framework Integration

The system integrates with Hyperf through the ConfigProvider class, which is automatically discovered via Composer's package discovery mechanism.

ConfigProvider Registration

Diagram: Bootstrap Sequence

Sources: src/ConfigProvider.php1-31

The ConfigProvider class src/ConfigProvider.php11-31 performs two critical functions during bootstrap:

Function	Description	Code Reference
Dependency Registration	Binds interface contracts to concrete implementations in the DI container	src/ConfigProvider.php16-19
Configuration Publishing	Makes the default configuration file available for customization	src/ConfigProvider.php21-28

Dependency Injection Bindings

Diagram: DI Container Binding Resolution

Sources: src/ConfigProvider.php16-19 src/FilesystemFactory.php1-18 src/CloudStorageFactory.php1-18

Three primary bindings are registered:

1. FactoryContract → FilesystemManager: Direct singleton binding to the central manager src/ConfigProvider.php18
2. FilesystemContract → FilesystemFactory: Invokable factory that delegates to the manager's disk() method src/FilesystemFactory.php13-16
3. CloudContract → CloudStorageFactory: Invokable factory that delegates to the manager's cloud() method src/CloudStorageFactory.php13-16

The factory classes are invokable wrappers that resolve the FactoryContract from the container and call the appropriate method. This indirection allows interface-based dependency injection while maintaining a single source of truth in FilesystemManager.

Sources: src/FilesystemFactory.php1-18 src/CloudStorageFactory.php1-18

---

Core Component Architecture

Component Roles and Responsibilities

Diagram: Component Dependency Graph

Sources: src/FilesystemManager.php39-70 src/FilesystemManager.php417-421

The FilesystemManager src/FilesystemManager.php39-500 serves as the central orchestrator with these key responsibilities:

Responsibility	Implementation	Code Reference
Disk Resolution	Resolves disk names to configured instances	src/FilesystemManager.php82-87
Instance Caching	Maintains disks array to avoid redundant instantiation	src/FilesystemManager.php46
Driver Creation	Factory methods for each driver type (createLocalDriver, createS3Driver, etc.)	src/FilesystemManager.php174-314
Custom Driver Registration	extend() method for registering custom drivers	src/FilesystemManager.php470-479
Pooling Management	Wraps cloud drivers with FilesystemPoolProxy via HasPoolProxy trait	src/FilesystemManager.php41 src/FilesystemManager.php61
Configuration Access	Retrieves disk configuration via ConfigInterface	src/FilesystemManager.php417-421

Sources: src/FilesystemManager.php39-500

---

Runtime Request Flow

Disk Instance Resolution

Diagram: Disk Resolution Flow

Sources: src/FilesystemManager.php82-87 src/FilesystemManager.php114-117 src/FilesystemManager.php124-161

The resolution process follows this sequence:

1. Cache Check src/FilesystemManager.php82-87: The disk() method calls get() which checks the disks array cache
2. Configuration Retrieval src/FilesystemManager.php417-421: If not cached, retrieves configuration from ConfigInterface using the path filesystems.disks.{name}
3. Driver Validation src/FilesystemManager.php128-130: Validates that a driver key exists in configuration
4. Creator Selection src/FilesystemManager.php135-144: Checks for custom creators first, then falls back to built-in driver methods
5. Pooling Decision src/FilesystemManager.php133 src/FilesystemManager.php152-158: If driver is in the poolables array (['s3', 'gcs']), wraps creation in createPoolProxy()
6. Instance Creation src/FilesystemManager.php160: Calls the appropriate factory method (e.g., createS3Driver())
7. Caching src/FilesystemManager.php86: Stores the instance in the disks array for future requests

Sources: src/FilesystemManager.php82-161

Operation Execution Flow

Diagram: Operation Execution Through Layers

Sources: src/FilesystemManager.php82-87 src/FilesystemManager.php496-499

Key aspects of operation execution:

1. Method Proxying src/FilesystemManager.php496-499: The FilesystemManager implements __call() to proxy method calls to the default disk
2. Disk Caching: Once resolved, disk instances remain in the disks array for the application's lifetime
3. Pooling Transparency: Pooled drivers (S3, GCS) wrapped in FilesystemPoolProxy implement the same interface, making pooling transparent to callers
4. Adapter Delegation: All adapters delegate to League Flysystem's FilesystemOperator for actual storage operations

Sources: src/FilesystemManager.php496-499

---

Configuration and State Management

Configuration Resolution

Diagram: Configuration Loading Flow

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

The configuration system operates in three layers:

Layer	Purpose	Code Reference
Template	Default configuration shipped with package	src/ConfigProvider.php25
Application	Published to config/autoload/filesystems.php for customization	src/ConfigProvider.php26
Runtime	Accessed via ConfigInterface through path notation	src/FilesystemManager.php419-420

Configuration retrieval methods:

• getConfig(string $name) src/FilesystemManager.php417-421: Retrieves disk-specific configuration from filesystems.disks.{name}
• getDefaultDriver() src/FilesystemManager.php426-430: Gets the default disk name from filesystems.default
• getDefaultCloudDriver() src/FilesystemManager.php435-439: Gets the cloud disk name from filesystems.cloud (defaults to 's3')

Sources: src/FilesystemManager.php417-439

Instance Lifecycle and Caching

Diagram: Disk Instance Lifecycle

Sources: src/FilesystemManager.php46 src/FilesystemManager.php82-87 src/FilesystemManager.php446-463

Instance caching behavior:

1. Initial Creation: First call to disk('name') resolves and caches the instance src/FilesystemManager.php86
2. Cache Hits: Subsequent calls return the cached instance from disks array src/FilesystemManager.php116
3. Manual Control:
   • forgetDisk($disk) src/FilesystemManager.php446-453: Removes from cache without cleanup
   • purge($name) src/FilesystemManager.php458-463: Removes default disk from cache
   • set($name, $disk) src/FilesystemManager.php407-412: Manually injects a disk instance

The caching strategy ensures that:

• Disk instances are singletons per disk name
• Configuration is only read once per disk
• Pooled connections are maintained across requests
• No redundant driver initialization occurs

Sources: src/FilesystemManager.php46 src/FilesystemManager.php82-87 src/FilesystemManager.php407-463

---

Driver Creation Patterns

Factory Method Dispatch

Diagram: Driver Factory Method Resolution

Sources: src/FilesystemManager.php135-161

The factory method pattern implementation:

1. Custom Creator Priority src/FilesystemManager.php135-144: Registered custom creators (via extend()) take precedence
2. Dynamic Method Resolution src/FilesystemManager.php146-150: Method name constructed as 'create' . ucfirst($driver) . 'Driver'
3. Method Existence Check src/FilesystemManager.php148-150: Validates method exists before calling
4. Fallback Error src/FilesystemManager.php149: Throws InvalidArgumentException for unsupported drivers

Built-in factory methods and their return types:

Method	Return Type	Code Reference
createLocalDriver()	FileSystem	src/FilesystemManager.php174-202
createS3Driver()	Cloud	src/FilesystemManager.php242-264
createGcsDriver()	Cloud	src/FilesystemManager.php287-314
createFtpDriver()	FileSystem	src/FilesystemManager.php207-217
createSftpDriver()	FileSystem	src/FilesystemManager.php222-237
createScopedDriver()	FileSystem	src/FilesystemManager.php356-375

Sources: src/FilesystemManager.php135-375

Flysystem Adapter Creation

All driver creation methods ultimately call createFlysystem() src/FilesystemManager.php380-400 which wraps the Flysystem adapter with optional decorators:

Diagram: Flysystem Wrapper Construction

Sources: src/FilesystemManager.php380-400

The wrapping process applies decorators in order:

1. Read-Only Wrapper src/FilesystemManager.php382-385: If read-only config is true, wraps with ReadOnlyFilesystemAdapter
2. Path Prefix Wrapper src/FilesystemManager.php387-390: If prefix is configured, wraps with PathPrefixedAdapter
3. Flysystem Instance src/FilesystemManager.php392-399: Creates the final Flysystem instance with filtered configuration options

This layered approach allows combining features (e.g., a read-only prefixed disk) without modifying adapter implementations.

Sources: src/FilesystemManager.php380-400

---

Integration Points

Hyperf Container Integration

Diagram: Container Injection Flow

Sources: src/ConfigProvider.php16-19 src/FilesystemManager.php66-69

The system integrates with Hyperf's DI container through:

1. Constructor Injection src/FilesystemManager.php66-69: FilesystemManager receives ContainerInterface via constructor
2. Interface Resolution: Application code injects interface contracts which resolve to implementations
3. Singleton Pattern: FilesystemManager is effectively a singleton due to container behavior
4. Indirect Access: Factory classes delegate to the manager, providing interface-based access patterns

Sources: src/ConfigProvider.php16-19 src/FilesystemManager.php66-69 src/FilesystemFactory.php13-16 src/CloudStorageFactory.php13-16

Configuration System Integration

The manager accesses configuration through the injected container:

This indirection allows:

• Configuration hot-reloading in development
• Environment-specific configuration
• Runtime configuration modification
• Testing with mock configurations

Sources: src/FilesystemManager.php419-420

---

Summary

The system architecture achieves several design goals:

1. Separation of Concerns: ConfigProvider handles framework integration, FilesystemManager handles disk orchestration, adapters handle storage operations
2. Lazy Instantiation: Disks are created only when first requested and cached thereafter
3. Transparent Pooling: Pooling wraps cloud drivers without modifying their interfaces
4. Extensibility: Custom drivers can be registered via extend() without modifying core code
5. Interface-Based Design: All interactions use contracts, enabling testing and substitution

The flow from application code to storage backend passes through multiple layers:

1. Application → FilesystemManager
2. FilesystemManager → FilesystemPoolProxy (if poolable) or Adapter (direct)
3. Adapter → League Flysystem FilesystemOperator
4. Flysystem → Storage Backend SDK
5. SDK → Physical Storage

This layered design provides abstraction at each level while maintaining performance through caching and pooling strategies.

Sources: src/FilesystemManager.php39-500 src/ConfigProvider.php1-31 src/FilesystemFactory.php1-18 src/CloudStorageFactory.php1-18