Configuration Reference

This page provides a comprehensive reference of all configuration options available in the Hypervel Filesystem package. Each driver type (local, S3, GCS, FTP, SFTP) has its own set of configuration parameters that control its behavior, credentials, and performance characteristics.

For information about creating custom drivers, see Creating Custom Drivers. For general installation and setup guidance, see Installation and Configuration.

---

Configuration File Structure

The filesystem configuration is stored in config/autoload/filesystems.php and consists of two main sections: a default disk identifier and a collection of disk configurations.

Sources: publish/filesystems.php1-88

---

Global Configuration Options

Default Disk

Option	Type	Default	Description
default	string	'local'	The name of the disk to use when no disk is explicitly specified via disk() method

The default disk is resolved using the FILESYSTEM_DISK environment variable.

Sources: publish/filesystems.php17

---

Common Disk Options

These options are available across all driver types, though some may have driver-specific behavior.

Core Options

Option	Type	Default	Description
driver	string	required	The driver type: 'local', 's3', 'gcs', 'ftp', 'sftp'
throw	bool	false	Whether to throw exceptions on errors or return false
visibility	string	null	Default visibility for files: 'public' or 'private'

Sources: publish/filesystems.php32-86

---

Local Driver Configuration

The local driver stores files on the server's filesystem using the League Flysystem local adapter.

Local Driver Options

Option	Type	Default	Description
root	string	required	Absolute path to the root directory for file storage
url	string	null	Base URL for generating public URLs to files
visibility	string	null	Default visibility: 'public' or 'private'
throw	bool	false	Whether to throw exceptions on errors
serve_signed_urls	bool	false	Whether to serve files through signed URL verification (requires routing setup)
links	array	[]	Array of symbolic links to create: ['public/storage' => 'storage/app/public']
lock	int	LOCK_EX	File lock constant for LockableFile operations
permissions	array	See below	Directory and file permission settings

Permissions Configuration

The permissions array controls Unix file permissions:

Example Configurations

Private Disk:

Public Disk with URLs:

Sources: publish/filesystems.php33-45 composer.json43

---

AWS S3 Driver Configuration

The s3 driver integrates with Amazon S3 and S3-compatible storage services using the AWS SDK for PHP.

S3 Driver Options

Option	Type	Default	Description
key	string	required	AWS access key ID for authentication
secret	string	required	AWS secret access key for authentication
region	string	required	AWS region code (e.g., 'us-east-1')
bucket	string	required	S3 bucket name
url	string	null	Custom base URL for public file access
endpoint	string	null	Custom S3-compatible endpoint (for MinIO, DigitalOcean Spaces, etc.)
use_path_style_endpoint	bool	false	Use path-style endpoint format instead of virtual-hosted style
token	string	null	AWS session token for temporary credentials
temporary_url	array	[]	Options for temporary URL generation
throw	bool	false	Whether to throw exceptions on errors
root	string	''	Path prefix within the bucket
visibility	string	null	Default visibility: 'public' or 'private'
options	array	[]	Additional S3Client configuration options
pool	array	See Pool Configuration	Connection pooling settings

S3 Options Array

The options array is passed directly to the AWS S3Client constructor and can include:

Option	Type	Description
version	string	S3 API version (default: 'latest')
signature_version	string	AWS signature version (e.g., 'v4')
use_dual_stack_endpoint	bool	Use dual-stack endpoints for IPv4/IPv6
use_accelerate_endpoint	bool	Use S3 Transfer Acceleration
retries	int	Number of retry attempts for failed requests
http	array	HTTP client configuration (timeout, proxy, etc.)

Temporary URL Configuration

The temporary_url array controls signed URL generation:

Example Configuration

Sources: publish/filesystems.php47-63 composer.json46

---

Google Cloud Storage Configuration

The gcs driver integrates with Google Cloud Storage using the Google Cloud SDK for PHP.

GCS Driver Options

Option	Type	Default	Description
key_file_path	string	null	Path to service account JSON key file
key_file	array	[]	Service account credentials as array (alternative to file)
project_id	string	required	Google Cloud project ID
bucket	string	required	GCS bucket name
path_prefix	string	''	Default path prefix within the bucket
storage_api_uri	string	null	Custom storage API URI for public URLs
api_endpoint	string	null	Custom API endpoint for StorageClient
visibility	string	null	Default visibility: 'public' or 'private'
visibility_handler	string	null	FQCN of custom visibility handler
metadata	array	[]	Default metadata for all uploaded objects
stream_reads	bool	false	Enable streaming reads for better memory efficiency
throw	bool	false	Whether to throw exceptions on errors
pool	array	See Pool Configuration	Connection pooling settings

Key File Authentication

Option 1: JSON File Path

Option 2: Inline Array

Visibility Handler

Set visibility_handler to enable uniform bucket-level access:

Metadata Configuration

Default metadata is applied to all uploaded objects:

Example Configuration

Sources: publish/filesystems.php65-85 composer.json47

---

FTP/SFTP Driver Configuration

FTP and SFTP drivers provide remote file access over traditional network protocols.

FTP Driver Options

Option	Type	Default	Description
host	string	required	FTP server hostname or IP address
port	int	21	FTP server port
username	string	required	FTP username
password	string	required	FTP password
root	string	''	Root directory on the FTP server
passive	bool	true	Use passive mode for data transfers
ssl	bool	false	Use FTPS (FTP over SSL/TLS)
timeout	int	30	Connection timeout in seconds
visibility	string	null	Default visibility (may not be supported by all servers)
throw	bool	false	Whether to throw exceptions on errors

SFTP Driver Options

Option	Type	Default	Description
host	string	required	SFTP server hostname or IP address
port	int	22	SFTP server port
username	string	required	SFTP username
password	string	null	SFTP password (if not using key authentication)
privateKey	string	null	Path to private key file for authentication
passphrase	string	null	Passphrase for encrypted private key
root	string	''	Root directory on the SFTP server
timeout	int	30	Connection timeout in seconds
permissions	array	See local driver	Directory and file permissions
visibility	string	null	Default visibility
throw	bool	false	Whether to throw exceptions on errors

Example FTP Configuration

Example SFTP Configuration

Sources: composer.json41 composer.json48-49

---

Pool Configuration

Connection pooling is available for S3 and GCS drivers to improve performance in high-concurrency Swoole/Hyperf environments. The pool is managed by the FilesystemPoolProxy class using the hypervel/object-pool library.

Pool Options

Option	Type	Default	Description
min_objects	int	1	Minimum number of connection objects to maintain in the pool
max_objects	int	10	Maximum number of connection objects allowed in the pool
wait_timeout	float	3.0	Maximum seconds to wait when borrowing an object if pool is exhausted
max_lifetime	float	60.0	Maximum seconds an object can live before being destroyed and recreated

Pool Configuration Guidelines

Optimal Settings for Different Workloads:

Workload Type	min_objects	max_objects	wait_timeout	max_lifetime
Low traffic	1	5	3.0	60.0
Medium traffic	2	10	5.0	120.0
High traffic	5	20	10.0	300.0
Burst traffic	2	30	3.0	60.0

Configuration Considerations:

• min_objects: Higher values provide better response times but consume more resources when idle
• max_objects: Should be set based on expected concurrency and upstream service limits (S3/GCS rate limits)
• wait_timeout: Balance between request timeout and resource availability
• max_lifetime: Shorter values refresh connections more frequently but increase overhead

Example Pool Configuration

Conservative (default):

Aggressive (high throughput):

Sources: publish/filesystems.php57-62 publish/filesystems.php79-84 composer.json37

---

Advanced Configuration Options

Scoped Driver (Path Prefixing)

Wrap any driver with automatic path prefixing using the scoped driver:

All operations on this disk will be automatically prefixed with uploads/2024/.

Required: league/flysystem-path-prefixing package

Read-Only Driver

Make any disk read-only by wrapping it:

Write operations will throw UnableToWriteFile exceptions.

Required: league/flysystem-read-only package

Custom Driver Configuration

Custom drivers registered via FilesystemManager::extend() can accept arbitrary configuration:

The configuration array is passed to the custom creator callback.

Sources: composer.json44-45

---

Configuration Loading and Caching

The configuration is loaded by FilesystemManager through Hyperf's configuration system:

Configuration Access

The FilesystemManager accesses configuration through the ConfigInterface:

• Disk configurations: filesystems.disks.{name}
• Default disk: filesystems.default

Disk Instance Caching

Created disk instances are cached in FilesystemManager::$disks to avoid redundant initialization:

To purge a specific disk from cache:

Sources: publish/filesystems.php1-88

---

Environment Variable Reference

Common environment variables used in filesystem configuration:

Global

Variable	Description	Example
FILESYSTEM_DISK	Default disk name	local
APP_URL	Base application URL (for local public URLs)	https://example.com

AWS S3

Variable	Description	Example
AWS_ACCESS_KEY_ID	AWS access key	AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY	AWS secret key	wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_DEFAULT_REGION	AWS region	us-east-1
AWS_BUCKET	S3 bucket name	my-bucket
AWS_URL	Custom public URL	https://cdn.example.com
AWS_ENDPOINT	Custom endpoint	https://nyc3.digitaloceanspaces.com
AWS_USE_PATH_STYLE_ENDPOINT	Path-style endpoints	true or false

Google Cloud Storage

Variable	Description	Example
GOOGLE_CLOUD_KEY_FILE	Service account key file path	/path/to/key.json
GOOGLE_CLOUD_PROJECT_ID	GCP project ID	my-project-123456
GOOGLE_CLOUD_STORAGE_BUCKET	GCS bucket name	my-bucket
GOOGLE_CLOUD_STORAGE_PATH_PREFIX	Default path prefix	uploads/
GOOGLE_CLOUD_STORAGE_API_URI	Custom storage API URI	https://storage.example.com
GOOGLE_CLOUD_STORAGE_API_ENDPOINT	Custom API endpoint	https://api.example.com

FTP/SFTP

Variable	Description	Example
FTP_HOST	FTP server hostname	ftp.example.com
FTP_PORT	FTP server port	21
FTP_USERNAME	FTP username	user@example.com
FTP_PASSWORD	FTP password	secret
FTP_ROOT	FTP root directory	/public_html
SFTP_HOST	SFTP server hostname	sftp.example.com
SFTP_PORT	SFTP server port	22
SFTP_USERNAME	SFTP username	deploy
SFTP_PASSWORD	SFTP password	secret
SFTP_PRIVATE_KEY	Private key file path	/home/.ssh/id_rsa
SFTP_PASSPHRASE	Key passphrase	passphrase
SFTP_ROOT	SFTP root directory	/var/www

Sources: publish/filesystems.php17 publish/filesystems.php42 publish/filesystems.php49-55 publish/filesystems.php67-73

---

Configuration Validation

The following table summarizes required vs optional configuration by driver:

Option	Local	S3	GCS	FTP	SFTP
driver	✓ Required	✓ Required	✓ Required	✓ Required	✓ Required
root	✓ Required	Optional	Optional	Optional	Optional
host	—	—	—	✓ Required	✓ Required
username	—	—	—	✓ Required	✓ Required
password	—	—	—	✓ Required	Optional*
key	—	✓ Required	—	—	—
secret	—	✓ Required	—	—	—
region	—	✓ Required	—	—	—
bucket	—	✓ Required	✓ Required	—	—
project_id	—	—	✓ Required	—	—
key_file	—	—	Optional*	—	—
privateKey	—	—	—	—	Optional*
pool	—	Optional	Optional	—	—
url	Optional	Optional	Optional	—	—
throw	Optional	Optional	Optional	Optional	Optional
visibility	Optional	Optional	Optional	Optional	Optional

* For SFTP, either password or privateKey is required. For GCS, either key_file_path or key_file array is required.

Sources: publish/filesystems.php32-86