Storage Backends

This document details the supported storage adapters in the Light framework's filesystem abstraction layer. The framework uses League Flysystem to provide a unified interface over multiple storage backends: local filesystem, AWS S3, Aliyun OSS, Hostlink Storage, and FTP (advertised but not fully implemented).

For information about the filesystem architecture and MountManager, see page 7.1. For file operation APIs, see page 7.4.

Overview

The Light framework implements a flexible multi-backend storage system that allows applications to:

• Configure multiple storage backends simultaneously (e.g., local for development, S3 for production)
• Switch between storage providers without code changes through configuration
• Access files through a unified interface regardless of the underlying storage provider
• Support blob storage in cloud environments while maintaining local development workflows

The storage adapter configuration is stored in the Config model with the name "fs" and contains a JSON array of storage backend definitions.

Sources: src/App.php695-714 src/App.php717-786

Configuration Structure

Storage adapters are configured through a JSON array stored in the database. Each adapter configuration has the following structure:

Field	Type	Description
name	string	Identifier for the storage backend
type	string	Adapter type: "local", "s3", "aliyun-oss", or "hostlink"
data	object	Adapter-specific configuration parameters

The configuration is retrieved via the getFSConfig() method, which provides a default local filesystem configuration if no configuration exists.

Sources: src/App.php695-714

Supported Adapter Types

Local Filesystem Adapter

The local adapter stores files on the server's filesystem using League\Flysystem\Local\LocalFilesystemAdapter. This adapter is always available and serves as the default when no configuration is provided.

Configuration Parameters:

Parameter	Type	Description	Default
location	string	Absolute path to storage directory	getcwd() . "/uploads"
public_url	string	URL prefix for accessing files	"/api/uploads/"

Example Configuration:

Visibility Settings:

The adapter uses PortableVisibilityConverter::fromArray() to configure permissions:

• Files: Both public and private files use 0640 (owner read/write, group read)
• Directories: Both public and private directories use 0777 (full permissions)
• Lazy Root Creation: The root directory is created only when first accessed

Sources: src/App.php723-742 src/Type/Filesystem.php35-44

Diagram: Local Adapter Instantiation in App::getFS()

Sources: src/App.php723-742

AWS S3 Adapter

The S3 adapter connects to AWS S3 or S3-compatible storage services using League\Flysystem\AwsS3V3\AwsS3V3Adapter. This adapter requires the optional package league/flysystem-aws-s3-v3.

Configuration Parameters:

Parameter	Type	Required	Description
region	string	Yes	AWS region (e.g., "us-east-1")
endpoint	string	Yes	S3 endpoint URL
access_key	string	Yes	AWS access key ID
secret_key	string	Yes	AWS secret access key
bucket	string	Yes	S3 bucket name
prefix	string	No	Optional path prefix within bucket
visibility	string	No	Default visibility for uploaded files
public_url	string	No	Public URL base path

Example Configuration:

S3Client Configuration:

The implementation creates an Aws\S3\S3Client instance with:

• version: "latest"
• region: From configuration
• endpoint: From configuration (supports S3-compatible services like MinIO, DigitalOcean Spaces)
• use_path_style_endpoint: true (enables path-style URLs for compatibility)
• credentials: Array with key and secret from configuration

Sources: src/App.php749-777 src/Type/Filesystem.php48-61

Diagram: S3 Adapter Instantiation in App::getFS()

Sources: src/App.php749-777

Aliyun OSS Adapter

The Aliyun OSS adapter integrates with Alibaba Cloud Object Storage Service using AlphaSnow\Flysystem\Aliyun\AliyunFactory. This adapter requires the optional package alphasnow/aliyun-oss-flysystem.

Configuration Parameters:

The entire data object is passed to AliyunFactory::createFilesystem(). Based on the advertised options in Type\Filesystem::getTypes():

Parameter	Type	Required	Description
access_key_id	string	Yes	Aliyun Access Key ID
access_key_secret	string	Yes	Aliyun Access Key Secret
endpoint	string	Yes	OSS endpoint (e.g., "oss-cn-hangzhou.aliyuncs.com")
bucket	string	Yes	OSS bucket name
public_url	string	No	Public URL base path

Example Configuration:

Implementation:

The adapter instantiation is delegated to AliyunFactory:

Sources: src/App.php745-747 src/Type/Filesystem.php78-89

Hostlink Storage Adapter

The Hostlink adapter is a custom storage provider using HL\Storage\Adapter. This adapter requires the optional package hostlink/hostlink-storage-adapter.

Configuration Parameters:

Parameter	Type	Required	Description
token	string	Yes	Authentication token for Hostlink API
endpoint	string	Yes	Hostlink API endpoint URL
public_url	string	No	Public URL base path

Example Configuration:

Implementation:

The adapter is instantiated directly:

Sources: src/App.php780-784 src/Type/Filesystem.php65-74

FTP Adapter

The FTP adapter is advertised in the GraphQL API via Type\Filesystem::getTypes() but not implemented in App::getFS(). Attempting to use FTP configuration will result in an exception: "File system not found".

Advertised Configuration Parameters:

Parameter	Type	Required	Description	Default
host	string	Yes	FTP server hostname	-
username	string	Yes	FTP username	-
password	string	Yes	FTP password	-
port	int	No	FTP port	21
root	string	No	Root directory path	"/"
public_url	string	No	Public URL base path	-

Package Requirement:

The type is marked as disabled if league/flysystem-ftp is not installed:

Implementation Status:

To enable FTP support, a case must be added to App::getFS() that instantiates League\Flysystem\Ftp\FtpAdapter.

Sources: src/Type/Filesystem.php93-105 src/App.php717-786

Adapter Instantiation Process

The App::getFS(int $index = 0) method is responsible for instantiating League\Flysystem\Filesystem instances based on the adapter type specified in configuration.

Diagram: App::getFS() Method Flow

Sources: src/App.php717-786

Instantiation Pattern

Each adapter type follows a consistent pattern:

1. Extract configuration: $data = $fs["data"]
2. Create adapter instance: Using the appropriate adapter class constructor
3. Wrap in Filesystem: new \League\Flysystem\Filesystem($adapter, $config)
4. Return Filesystem: Implements FilesystemOperator interface

Exception Handling:

If $fs["type"] doesn't match any implemented adapter, the method throws:

This occurs when:

• An unknown type is specified
• FTP configuration is used (advertised but not implemented)
• Typos in the type field (e.g., "oss" instead of "aliyun-oss")

Sources: src/App.php717-786

Integration with MountManager

Storage adapters are loaded into League\Flysystem\MountManager during application initialization. The MountManager allows accessing multiple filesystems through a unified interface using protocol-style paths (e.g., local://path/to/file).

Diagram: MountManager Initialization in App Constructor

Sources: src/App.php134-146

The initialization process:

1. Retrieve all filesystem configurations via getFSConfig()
2. For each configuration, call getFS($index) to instantiate the adapter
3. Build filesystems array keyed by configuration name: $filesystems[$config["name"]] = $this->getFS($index)
4. Create MountManager: new MountManager($filesystems)
5. Store in App and register in container for dependency injection

The MountManager is then accessible via:

• App::getMountManager() method
• Dependency injection with #[Autowire] MountManager $mountManager

Sources: src/App.php134-146 src/App.php149-152

Configuration Management

Retrieving Configuration: App::getFSConfig()

The getFSConfig() method retrieves filesystem configurations from the Config model with fallback to a default local configuration.

Diagram: getFSConfig() Logic Flow

Sources: src/App.php695-714

Default Configuration:

When no filesystem configuration exists, the method returns a single local filesystem:

Sources: src/App.php704-712

GraphQL API for Configuration Management

The FileSystemController (registered at src/App.php93) provides GraphQL mutations for CRUD operations on filesystem configurations. The configurations are stored as JSON in the Config model with name = "fs".

Sources: src/App.php93 src/App.php695-714

HTTP File Access Routes

The framework provides two HTTP routes for accessing files stored in configured backends. Both routes require authentication.

Route 1: /fs/{protocol}/{path}

Accesses files through the MountManager using protocol-style paths.

Route Definition:

GET /fs/{protocol}/{path:.*}

Example URL:

GET /api/fs/local/uploads/document.pdf

Diagram: /fs/ Route Handler

Sources: src/App.php850-865

Route 2: /drive/{index}/{path}

Accesses files by filesystem configuration index.

Route Definition:

GET /drive/{index}/{path:.*}

Example URL:

GET /api/drive/0/uploads/image.jpg

Diagram: /drive/ Route via getDriveResponse()

Sources: src/App.php867-875 src/App.php540-564

Authentication Requirement:

Both routes check authentication status using Auth\Service::isLogged() before serving files. Unauthenticated requests receive a 401 Unauthorized response.

Sources: src/App.php850-875

Dependency Requirements

The storage adapter system requires the following Composer packages:

Package	Purpose
league/flysystem	Core filesystem abstraction
league/flysystem-local	Local filesystem adapter
league/flysystem-aws-s3-v3	AWS S3 adapter (optional)
alphasnow/flysystem-aliyun	Aliyun OSS adapter (optional)
Custom package	Hostlink adapter (optional)

Sources: composer.lock1696-1826