Version
File Storage
- Introduction
-
Configuration
- The Local Driver
- The Public Disk
- Driver Prerequisites
- Scoped & Read-Only Filesystems
- Amazon S3 Compatible Filesystems
- Obtaining Disk Instances
- On-Demand Disks
- Retrieving Files
- Downloading Files
- File URLs
- File Metadata
- Storing Files
- Prepending & Appending To Files
- Copying & Moving Files
- Automatic Streaming
- File Uploads
- File Visibility
- Deleting Files
- Directories
- Custom Filesystems
Introduction
Laravel provides a powerful filesystem abstraction thanks to the wonderful Flysystem PHP package by Frank de Jonge. The Laravel Flysystem integration provides simple drivers for working with local filesystems, SFTP, and Amazon S3. Even better, it's amazingly simple to switch between these storage options between your local development machine and production server as the API remains the same for each system.
Configuration
Laravel's filesystem configuration file is located at config/filesystems.php
. Within this file, you may configure all of your filesystem "disks". Each disk represents a particular storage driver and storage location. Example configurations for each supported driver are included in the
configuration file so you can modify the configuration to reflect your storage preferences and credentials.
The local
driver interacts with files stored locally on the server running the Laravel application while the s3
driver is used to write to Amazon's S3 cloud storage service.
Note You may configure as many disks as you like and may even have multiple disks that use the same driver.
The Local Driver
When using the
local
driver, all file operations are relative to the root
directory defined in your filesystems
configuration file. By default, this value is set to the storage/app
directory. Therefore, the following method would write to storage/app/example.txt
:
use Illuminate\Support\Facades\Storage;
Storage::disk['local']->put['example.txt', 'Contents'];
The Public Disk
The public
disk included in your application's filesystems
configuration file is intended for files that are going to be publicly accessible. By default, the public
disk uses the local
driver and stores its files in
storage/app/public
.
To make these files accessible from the web, you should create a symbolic link from public/storage
to storage/app/public
. Utilizing this folder convention will keep your publicly accessible files in one directory that can be easily shared across deployments when using zero down-time deployment systems like Envoyer.
To create the symbolic link, you may use the storage:link
Artisan command:
php artisan storage:link
Once a file has been
stored and the symbolic link has been created, you can create a URL to the files using the asset
helper:
echo asset['storage/file.txt'];
You may configure additional symbolic links in your filesystems
configuration file. Each of the configured links will be created when you run the storage:link
command:
'links' => [
public_path['storage'] => storage_path['app/public'],
public_path['images'] => storage_path['app/images'],
],
Driver Prerequisites
S3 Driver Configuration
Before using the S3 driver, you will need to install the Flysystem S3 package via the Composer package manager:
composer require league/flysystem-aws-s3-v3 "^3.0"
The S3 driver
configuration information is located in your config/filesystems.php
configuration file. This file contains an example configuration array for an S3 driver. You are free to modify this array with your own S3 configuration and credentials. For convenience, these environment variables match the naming convention used by the AWS CLI.
FTP Driver Configuration
Before using the FTP driver, you will need to install the Flysystem FTP package via the Composer package manager:
composer require league/flysystem-ftp "^3.0"
Laravel's
Flysystem integrations work great with FTP; however, a sample configuration is not included with the framework's default filesystems.php
configuration file. If you need to configure an FTP filesystem, you may use the configuration example below:
'ftp' => [
'driver' => 'ftp',
'host' => env['FTP_HOST'],
'username' => env['FTP_USERNAME'],
'password' => env['FTP_PASSWORD'],
// Optional FTP Settings...
// 'port' => env['FTP_PORT', 21],
// 'root' => env['FTP_ROOT'],
// 'passive' => true,
// 'ssl' => true,
// 'timeout' => 30,
],
SFTP Driver Configuration
Before using the SFTP driver, you will need to install the Flysystem SFTP package via the Composer package manager:
composer require league/flysystem-sftp-v3 "^3.0"
Laravel's Flysystem integrations work great with SFTP; however, a sample
configuration is not included with the framework's default filesystems.php
configuration file. If you need to configure an SFTP filesystem, you may use the configuration example below:
'sftp' => [
'driver' => 'sftp',
'host' => env['SFTP_HOST'],
// Settings for basic authentication...
'username' => env['SFTP_USERNAME'],
'password' => env['SFTP_PASSWORD'],
// Settings for SSH key based authentication with encryption password...
'privateKey' => env['SFTP_PRIVATE_KEY'],
'password' => env['SFTP_PASSWORD'],
// Optional SFTP Settings...
// 'hostFingerprint' => env['SFTP_HOST_FINGERPRINT'],
// 'maxTries' => 4,
// 'passphrase' => env['SFTP_PASSPHRASE'],
// 'port' => env['SFTP_PORT', 22],
// 'root' => env['SFTP_ROOT', ''],
// 'timeout' => 30,
// 'useAgent' => true,
],
Scoped & Read-Only Filesystems
You may create a path scoped instance of any existing filesystem disk by defining a disk that utilizes the scoped
driver. Scoped disks allow you to define a filesystem where all paths are automatically prefixed with a given path prefix. For example, you may create
a disk which scopes your existing s3
disk to a specific path prefix, and then every file operation using your scoped disk will utilize the specified prefix:
's3-videos' => [
'driver' => 'scoped',
'disk' => 's3',
'prefix' => 'path/to/videos',
],
If you would like to specify that any filesystem disk should be "read-only", you may include the read-only
configuration option in the disk's configuration array:
's3-videos' => [
'driver' => 's3',
// ...
'read-only' => true,
],
Amazon S3 Compatible Filesystems
By default, your application's filesystems
configuration file contains a disk configuration for the s3
disk. In addition to using this disk to interact with Amazon S3, you may use it to interact with any S3 compatible file storage service such as MinIO or DigitalOcean Spaces.
Typically, after updating the disk's credentials to match the credentials of the service you are planning to use, you only need to update the value of the endpoint
configuration
option. This option's value is typically defined via the AWS_ENDPOINT
environment variable:
'endpoint' => env['AWS_ENDPOINT', '//minio:9000'],
Obtaining Disk Instances
The Storage
facade may be used to interact with any of your configured disks. For example, you may use the put
method on the facade to store an avatar on the default disk. If you call methods on the Storage
facade without first calling the disk
method, the method will automatically be passed to the default disk:
use Illuminate\Support\Facades\Storage;
Storage::put['avatars/1', $content];
If your application
interacts with multiple disks, you may use the disk
method on the Storage
facade to work with files on a particular disk:
Storage::disk['s3']->put['avatars/1', $content];
On-Demand Disks
Sometimes you may wish to create a disk at runtime using a given configuration without that configuration actually being present in your application's filesystems
configuration file. To accomplish this, you may pass a configuration array to the Storage
facade's build
method:
use Illuminate\Support\Facades\Storage;
$disk = Storage::build[[
'driver' => 'local',
'root' => '/path/to/root',
]];
$disk->put['image.jpg', $content];
Retrieving Files
The get
method
may be used to retrieve the contents of a file. The raw string contents of the file will be returned by the method. Remember, all file paths should be specified relative to the disk's "root" location:
$contents = Storage::get['file.jpg'];
The exists
method may be used to determine if a file exists on the disk:
if [Storage::disk['s3']->exists['file.jpg']] {
// ...
}
The missing
method may be used to determine if a file is missing from the disk:
if [Storage::disk['s3']->missing['file.jpg']] {
// ...
}
Downloading Files
The download
method may be used to generate a response that forces the user's
browser to download the file at the given path. The download
method accepts a filename as the second argument to the method, which will determine the filename that is seen by the user downloading the file. Finally, you may pass an array of HTTP headers as the third argument to the method:
return Storage::download['file.jpg'];
return Storage::download['file.jpg', $name, $headers];
File URLs
You may use the url
method to get the URL for a given file. If you are using the local
driver, this will typically just prepend /storage
to the given path and return a
relative URL to the file. If you are using the s3
driver, the fully qualified remote URL will be returned:
use Illuminate\Support\Facades\Storage;
$url = Storage::url['file.jpg'];
When using the local
driver, all files that should be publicly accessible should be placed in the storage/app/public
directory. Furthermore, you should create a symbolic link at public/storage
which points to the storage/app/public
directory.
Warning
When using thelocal
driver, the return value ofurl
is not URL encoded. For this reason, we recommend always storing your files using names that will create valid URLs.
Temporary URLs
Using the temporaryUrl
method, you may create temporary URLs to files stored using the s3
driver. This method accepts a path and a DateTime
instance specifying when the URL should expire:
use Illuminate\Support\Facades\Storage;
$url = Storage::temporaryUrl[
'file.jpg', now[]->addMinutes[5]
];
If you need to specify additional
S3 request parameters, you may pass the array of request parameters as the third argument to the temporaryUrl
method:
$url = Storage::temporaryUrl[
'file.jpg',
now[]->addMinutes[5],
[
'ResponseContentType' => 'application/octet-stream',
'ResponseContentDisposition' => 'attachment; filename=file2.jpg',
]
];
If you need to customize how temporary URLs are created for a specific storage disk, you can use the buildTemporaryUrlsUsing
method. For example, this can be useful if you have a controller that allows you to download files stored via a disk that doesn't typically
support temporary URLs. Usually, this method should be called from the boot
method of a service provider: