Installation and Configuration

Purpose and Scope

This document guides you through installing the Hypervel Filesystem package and configuring it for use in your Hyperf application. It covers Composer installation, publishing configuration files, setting up storage drivers (local, S3, GCS, FTP, SFTP), and managing driver-specific dependencies.

For information about the underlying architecture and how components interact, see Architecture. For detailed configuration options reference, see Configuration Reference.

---

Installation via Composer

Basic Installation

Install the package using Composer:

This installs the core package with its required dependencies:

Package	Version	Purpose
hyperf/collection	~3.1.0	Collection utilities
hyperf/macroable	~3.1.0	Trait for extending classes
hyperf/support	~3.1.0	Support utilities
hyperf/conditionable	~3.1.0	Conditional method chaining
hypervel/object-pool	^0.3	Connection pooling for cloud drivers

Requirements:

• PHP ^8.2
• ext-fileinfo extension (for MIME type detection)
• ext-hash extension (for file hashing operations)

Sources: composer.json31-38

---

Driver-Specific Dependencies

The core package does not include driver implementations by default. Install additional packages based on your storage backend requirements:

Local Filesystem Driver

AWS S3 Driver

Google Cloud Storage Driver

FTP Driver

Requires ext-ftp PHP extension.

SFTP Driver

Optional Features

Package	Purpose
league/flysystem-path-prefixing:^3.3	Scoped/prefixed disk paths
league/flysystem-read-only:^3.3	Read-only disk restrictions
hypervel/http	Accept PSR-7 StreamInterface in put operations

Sources: composer.json39-51

---

Installation Flow

Sources: composer.json23-29 composer.json55-58

---

Publishing Configuration

Configuration File Publication

After installation, publish the configuration file to your Hyperf application:

This copies the template from the package to your application's configuration directory.

Sources: src/ConfigProvider.php21-27

---

Framework Integration

The ConfigProvider class integrates the package with Hyperf's dependency injection container:

The bindings enable dependency injection:

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

Sources: src/ConfigProvider.php14-29 composer.json55-58

---

Configuration File Structure

The published configuration file config/autoload/filesystems.php has two main sections:

Default Disk

Specifies which disk is used when no disk name is provided:

Set via environment variable:

Sources: publish/filesystems.php17

---

Disk Configuration Array

Each disk is configured under the disks array with a unique identifier:

Sources: publish/filesystems.php5-87

---

Driver Configuration

Local Driver Configuration

The local driver stores files on the server's filesystem.

Basic Configuration:

Option	Type	Description	Example
driver	string	Must be 'local'	'local'
root	string	Absolute path to storage directory	storage_path('app/private')
throw	bool	Throw exceptions on errors	false
visibility	string	Default visibility ('public' or 'private')	'public'

Private Disk Example:

Public Disk Example:

The url option enables URL generation for public files via web server.

Sources: publish/filesystems.php33-45

---

AWS S3 Driver Configuration

The S3 driver connects to Amazon S3 or S3-compatible services.

Required Options:

Option	Type	Environment Variable	Description
driver	string	-	Must be 's3'
key	string	AWS_ACCESS_KEY_ID	AWS access key
secret	string	AWS_SECRET_ACCESS_KEY	AWS secret key
region	string	AWS_DEFAULT_REGION	AWS region (e.g., 'us-east-1')
bucket	string	AWS_BUCKET	S3 bucket name

Optional Options:

Option	Type	Environment Variable	Description
url	string	AWS_URL	Custom S3 URL for public access
endpoint	string	AWS_ENDPOINT	Custom endpoint (for S3-compatible services)
use_path_style_endpoint	bool	AWS_USE_PATH_STYLE_ENDPOINT	Use path-style URLs (false for virtual-hosted style)
throw	bool	-	Throw exceptions on errors

Connection Pool Configuration:

Complete Example:

Sources: publish/filesystems.php47-63

---

Google Cloud Storage Driver Configuration

The GCS driver connects to Google Cloud Storage buckets.

Authentication Options (Choose One):

Option	Type	Environment Variable	Description
key_file_path	string	GOOGLE_CLOUD_KEY_FILE	Path to service account JSON file
key_file	array	-	Service account credentials as array

Required Options:

Option	Type	Environment Variable	Description
driver	string	-	Must be 'gcs'
bucket	string	GOOGLE_CLOUD_STORAGE_BUCKET	GCS bucket name

Optional Options:

Option	Type	Environment Variable	Description
project_id	string	GOOGLE_CLOUD_PROJECT_ID	GCP project ID (included in key file)
path_prefix	string	GOOGLE_CLOUD_STORAGE_PATH_PREFIX	Default path prefix in bucket
storage_api_uri	string	GOOGLE_CLOUD_STORAGE_API_URI	Custom storage API URI
api_endpoint	string	GOOGLE_CLOUD_STORAGE_API_ENDPOINT	Custom API endpoint
visibility	string	-	Default visibility ('public' or 'private')
visibility_handler	string	-	Visibility handler class
metadata	array	-	Default metadata for objects
stream_reads	bool	-	Enable stream reads
throw	bool	-	Throw exceptions on errors

Connection Pool Configuration:

Same structure as S3 driver pool configuration.

Complete Example:

Sources: publish/filesystems.php65-85

---

Environment Variables

Environment File Setup

Create or update your .env file with driver-specific credentials:

Local Driver:

AWS S3 Driver:

Google Cloud Storage Driver:

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

---

Configuration Validation

Driver and Dependency Matrix

Ensure proper dependencies are installed for your configured drivers:

Verification Steps:

1. Check installed packages:

2. Verify PHP extensions:

3. Validate configuration file syntax:

Sources: composer.json39-50

---

Post-Installation Verification

Testing Basic Functionality

After configuration, verify the installation by testing disk access:

Common Installation Issues

Issue	Cause	Solution
Class FilesystemManager not found	Package not installed	Run composer require hypervel/filesystem
Missing driver adapter	Driver package not installed	Install appropriate league/flysystem-* package
Configuration file not found	File not published	Run php bin/hyperf.php vendor:publish
AWS credentials error	Invalid or missing credentials	Check .env file and AWS IAM permissions
GCS authentication error	Invalid service account key	Verify key_file_path points to valid JSON file
FTP extension not loaded	ext-ftp not installed	Install and enable ext-ftp PHP extension

Sources: src/ConfigProvider.php16-19

---

Next Steps

After successful installation and configuration:

1. Understand Core Concepts: Learn about disks, drivers, and the Factory pattern in Core Concepts
2. Explore Architecture: Understand how components interact in System Design
3. Driver-Specific Features: See detailed driver documentation in Filesystem Drivers
4. Advanced Configuration: Review all configuration options in Configuration Reference

Sources: composer.json1-63 src/ConfigProvider.php1-31 publish/filesystems.php1-87