Advanced Features

This document provides an overview of the advanced capabilities available in the Hypervel Filesystem package beyond basic file operations. These features include connection pooling for cloud storage drivers, file locking mechanisms for concurrent access, URL generation for public and private file access, streaming operations for efficient content delivery, and utility functions for path management.

For details on basic filesystem operations and driver configuration, see Architecture. For extending the system with custom drivers, see Extending and Customization.

---

Overview

The Hypervel Filesystem package extends basic CRUD operations with several advanced capabilities designed for production environments. These features address common requirements such as:

• Performance optimization through connection pooling in high-concurrency environments
• Concurrent access control via file locking with coroutine safety
• Secure content delivery using signed URLs with expiration
• Efficient data transfer through streaming and range request support
• HTTP integration for serving files directly as responses

The availability of these features varies by driver type, with cloud storage drivers (S3, GCS) offering the most comprehensive feature set.

Sources: src/FilesystemAdapter.php1-867 src/FilesystemPoolProxy.php1-224 src/LockableFile.php1-192

---

Advanced Features Architecture

The following diagram illustrates how advanced features are layered on top of the core filesystem abstraction:

This architecture shows that advanced features are implemented at different levels:

• FilesystemPoolProxy wraps adapters to provide pooling
• LockableFile operates directly on local filesystem resources
• URL generation, streaming, and HTTP response features are built into FilesystemAdapter
• Cloud drivers extend FilesystemAdapter with specialized implementations

Sources: src/FilesystemAdapter.php50-92 src/FilesystemPoolProxy.php13-14 src/LockableFile.php13-41

---

Feature Support Matrix

Different filesystem drivers support different subsets of advanced features. The following table summarizes feature availability:

Feature	Local	S3	GCS	FTP/SFTP
Connection Pooling	✗	✓	✓	✗
File Locking	✓	✗	✗	✗
Public URLs	✓	✓	✓	✓*
Temporary URLs	✓**	✓	✓	✗
Upload URLs	✗	✓	✗	✗
Stream Reading	✓	✓	✓	✓
Stream Writing	✓	✓	✓	✓
Range Requests	✓	✓	✓	✗
HTTP Response	✓	✓	✓	✓
File Upload Handling	✓	✓	✓	✓

* Requires URL configuration
** Requires hypervel/http package and signed URL setup

Key Observations:

• Cloud drivers (S3, GCS) support connection pooling, which is critical for high-concurrency Swoole/Hyperf environments
• Local driver is the only driver supporting file locking via LockableFile
• Temporary URLs are available for all major drivers but require different implementation approaches
• Range requests enable partial content delivery for efficient streaming of large files

Sources: src/FilesystemAdapter.php241-284 src/FilesystemAdapter.php546-566 src/FilesystemAdapter.php661-676 src/FilesystemPoolProxy.php1-224 src/LockableFile.php1-192

---

Connection Pooling

Connection pooling is a performance optimization for cloud storage drivers (S3 and GCS) that maintains a pool of reusable adapter instances. This dramatically reduces overhead in Swoole/Hyperf applications where many concurrent requests access cloud storage.

The FilesystemPoolProxy class wraps cloud adapters and delegates method calls to pooled instances:

For detailed configuration options and usage examples, see Object Pooling for Cloud Drivers.

Sources: src/FilesystemPoolProxy.php1-224

---

File Locking

The LockableFile class provides atomic file operations with support for both shared and exclusive locks. It is designed for local filesystem operations and includes coroutine-safe locking mechanisms for Swoole/Hyperf environments.

Lock types:

• Shared locks (getSharedLock()) allow multiple readers
• Exclusive locks (getExclusiveLock()) ensure single-writer access

The implementation uses Hyperf's Locker for coroutine synchronization at src/LockableFile.php175-190:

For usage examples and timeout handling, see File Locking.

Sources: src/LockableFile.php1-192

---

URL Generation

The filesystem abstraction provides multiple methods for generating URLs to access stored files:

URL Generation Methods

Method	Purpose	Drivers	Expiration
url(string $path)	Public permanent URL	All	Never
temporaryUrl(string $path, DateTimeInterface $expiration)	Time-limited signed URL	Local*, S3, GCS	Custom
temporaryUploadUrl(string $path, DateTimeInterface $expiration)	Pre-signed upload URL	S3	Custom

* Local requires hypervel/http package

The base implementation delegates to the underlying adapter at src/FilesystemAdapter.php591-612:

For configuration examples and custom domain setup, see URL Generation.

Sources: src/FilesystemAdapter.php587-698

---

Streaming and Content Handling

Streaming operations enable efficient handling of large files without loading entire contents into memory. The package provides several streaming capabilities:

Core Streaming Methods

The response() method at src/FilesystemAdapter.php242-284 integrates with hypervel/http to generate streaming HTTP responses with support for:

• Content-Type detection via mimeType()
• Content-Disposition headers (inline/attachment)
• Range request handling for partial content delivery
• Chunked streaming with configurable buffer size (default 64KB)

For detailed streaming patterns and range request handling, see Streaming and Content Handling.

Sources: src/FilesystemAdapter.php240-292 src/FilesystemAdapter.php542-584

---

Path Utilities

The package includes utility functions for path manipulation and directory management. These utilities are particularly useful when working with relative paths and ensuring proper directory structure.

Key utility functions are provided through the global join_paths() function and the Filesystem utility class's ensureDirectoryExists() method.

The LockableFile class demonstrates directory creation at src/LockableFile.php46-51:

For additional path manipulation utilities, see Path Utilities and Helper Functions.

Sources: src/LockableFile.php43-51

---

Integration with Hyperf HTTP

Many advanced features integrate with the hypervel/http package to provide seamless HTTP functionality:

The integration occurs at src/FilesystemAdapter.php244-246 where the application container provides HTTP contracts:

This integration is optional but recommended for web applications serving files.

Sources: src/FilesystemAdapter.php241-284

---

Advanced Feature Configuration

Advanced features can be enabled and configured through the driver configuration array. Common configuration options include:

Configuration Key	Purpose	Applicable Features
pool	Connection pool settings	S3, GCS drivers
pool.min_connections	Minimum pool size	Connection pooling
pool.max_connections	Maximum pool size	Connection pooling
pool.wait_timeout	Pool acquisition timeout	Connection pooling
url	Custom base URL	URL generation
temporary_url	Signed URL configuration	Local driver URLs
throw	Exception handling mode	All error scenarios

Configuration is passed to the adapter constructor at src/FilesystemAdapter.php75-92 and stored for feature implementations.

For comprehensive configuration reference, see Configuration Reference.

Sources: src/FilesystemAdapter.php60-92

---

Next Steps

This overview introduces the advanced features available in the Hypervel Filesystem package. For detailed implementation guidance, refer to the following subsections:

• Object Pooling for Cloud Drivers - Configure connection pooling for S3 and GCS
• File Locking - Implement atomic file operations with locks
• URL Generation - Generate public and signed URLs for file access
• Streaming and Content Handling - Efficiently handle large files with streaming
• Path Utilities and Helper Functions - Use utility functions for path management