Filesystem and Cloud Storage
Relevant source files
The following files were used as context for generating this wiki page:
The Filesystem and Cloud Storage system provides a powerful abstraction for managing file storage across multiple backends. It allows the application to interact with local disks, FTP, SFTP, and cloud-based solutions like Amazon S3 using a unified API. By defining "disks" in the configuration, developers can switch storage backends without changing the application's core logic.
This system is integral to the framework's goal of easing common development tasks, such as handling user uploads, generating public URLs for assets, and managing private application data. It integrates with the environment configuration to allow different storage settings for local development and production environments.
Sources: README.md:12-25, config/filesystems.php:3-23
Storage Architecture and Disks
The storage system is built around the concept of "disks." Each disk represents a specific storage location and driver. The application defines a default disk via the FILESYSTEM_DISK environment variable, which typically defaults to local.
Supported Drivers
The framework supports several storage drivers out of the box:
- local: Stores files on the local server's filesystem.
- s3: Interfaces with Amazon S3 or compatible object storage services.
- ftp/sftp: Connects to remote servers via file transfer protocols.
Sources: config/filesystems.php:12-32
Default Disk Resolution
The following diagram illustrates how the application resolves the storage disk to use based on configuration:
The application uses the FILESYSTEM_DISK env variable to select a configuration from the disks array.
Sources: config/filesystems.php:14-23
Local Storage Configuration
Local storage is split into private and public sectors to ensure security while allowing web accessibility where needed.
Private Storage
The local disk is configured for private files that should not be accessible via a web browser. These files are stored in the storage/app/private directory.
Sources: config/filesystems.php:36-42
Public Storage
The public disk is intended for files that will be publicly accessible. These files are stored in storage/app/public. To make these files accessible from the web, a symbolic link must be created from the public/storage directory to the storage/app/public directory.
Sources: config/filesystems.php:44-51, config/filesystems.php:82-84
| Option | Description | Default Value |
|---|---|---|
driver | The underlying driver used for the disk. | local |
root | The absolute path where files are stored. | storage_path('app/private') |
url | The base URL used for public file access. | env('APP_URL').'/storage' |
visibility | Visibility level (private or public). | public (for public disk) |
| Sources: config/filesystems.php:36-51 |
Cloud Storage with Amazon S3
The s3 disk configuration allows the application to utilize Amazon S3 for scalable cloud storage. It requires specific AWS credentials and bucket details provided through environment variables.
S3 Configuration Parameters
The following table outlines the configuration requirements for the S3 driver:
| Key | Environment Variable | Description |
|---|---|---|
key | AWS_ACCESS_KEY_ID | AWS Access Key ID. |
secret | AWS_SECRET_ACCESS_KEY | AWS Secret Access Key. |
region | AWS_DEFAULT_REGION | The AWS region where the bucket is located. |
bucket | AWS_BUCKET | The name of the S3 bucket. |
endpoint | AWS_ENDPOINT | Optional custom endpoint for S3-compatible services. |
use_path_style_endpoint | AWS_USE_PATH_STYLE_ENDPOINT | Whether to use path-style URLs (default: false). |
| Sources: config/filesystems.php:53-65 |
Symbolic Links and Public Access
To serve files from the public disk, the application relies on a symbolic link. This link bridges the gap between the protected storage directory and the web-accessible public directory.
Link Definition
The configuration defines the mapping for the storage:link Artisan command:
'links' => [
public_path('storage') => storage_path('app/public'),
],
Sources: config/filesystems.php:82-84
Data Flow for Public Assets
The following sequence diagram shows how a request for a public file is handled:
Requests to /storage are transparently redirected by the OS-level symbolic link to the actual file location in the storage directory.
Sources: config/filesystems.php:44-51, config/filesystems.php:82-84
Integration with Application Lifecycle
The filesystem system is initialized during the application bootstrapping process. While the public/index.php file handles the entry point, the filesystem configuration is loaded as part of the service container initialization to ensure storage drivers are available to handle incoming requests or background jobs.
- Composer Integration: The
composer.jsonfile ensures that the necessary framework components are loaded, including the filesystem abstractions. - Artisan Commands: Scripts like
migrateandkey:generateoften run before filesystem use is finalized in production.
Sources: public/index.php:14-25, composer.json:49-65
Summary
The Filesystem and Cloud Storage system provides a versatile and secure method for managing application data. By separating local private storage from public storage and providing a seamless transition to cloud-based S3 storage, it ensures that applications can scale their storage needs without significant refactoring. The use of symbolic links allows the application to maintain a secure directory structure while still serving assets efficiently to the end-user.