Introduction
Laravel provides a powerful filesystem abstraction thanks to the wonderful Flysystem PHP package by Frank de Jonge. The Laravel Flysystem integration provides simple to use drivers for working with local filesystems, Amazon S3, and Rackspace Cloud Storage. Even better, it's amazingly simple to switch between these storage options as the API remains the same for each system.
Configuration
The filesystem configuration file is located at
config/filesystems.php
. Within this file
you may configure all of your "disks". Each
disk represents a particular storage driver and storage
location. Example configurations for each supported
driver is included in the configuration file. So, simply
modify the configuration to reflect your storage
preferences and credentials.
Of course, you may configure as many disks as you like, and may even have multiple disks that use the same driver.
The Public Disk
The public
disk is meant for files that are
going to be publicly accessible. By default, the
public
disk uses the local
driver and stores these files in
storage/app/public
. To make them accessible
from the web, you should create a symbolic link from
public/storage
to
storage/app/public
. This 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.
Of course, once a file has been stored and the symbolic
link has been created, you can create an URL to the
files using the asset
helper:
echo asset('storage/file.txt');
The Local Driver
When using the local
driver, note that all
file operations are relative to the root
directory defined in your configuration file. By
default, this value is set to the
storage/app
directory. Therefore, the
following method would store a file in
storage/app/file.txt
:
Storage::disk('local')->put('file.txt', 'Contents');
Other Driver Prerequisites
Before using the S3 or Rackspace drivers, you will need to install the appropriate package via Composer:
- Amazon S3:
league/flysystem-aws-s3-v3 ~1.0
- Rackspace:
league/flysystem-rackspace ~1.0
FTP Driver Configuration
Laravel's Flysystem integrations works great with FTP;
however, a sample configuration is not included with the
framework's default filesystems.php
configuration file. If you need to configure a FTP
filesystem, you may use the example configuration
below:
'ftp' => [
'driver' => 'ftp',
'host' => 'ftp.example.com',
'username' => 'your-username',
'password' => 'your-password',
// Optional FTP Settings...
// 'port' => 21,
// 'root' => '',
// 'passive' => true,
// 'ssl' => true,
// 'timeout' => 30,
],
Rackspace Driver Configuration
Laravel's Flysystem integrations works great with
Rackspace; however, a sample configuration is not
included with the framework's default
filesystems.php
configuration file. If you
need to configure a Rackspace filesystem, you may use
the example configuration below:
'rackspace' => [
'driver' => 'rackspace',
'username' => 'your-username',
'key' => 'your-key',
'container' => 'your-container',
'endpoint' => 'https://identity.api.rackspacecloud.com/v2.0/',
'region' => 'IAD',
'url_type' => 'publicURL',
],
Basic Usage
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 call will
automatically be passed to the default disk:
<?php
namespace App\Http\Controllers;
use Storage;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller;
class UserController extends Controller
{
/**
* Update the avatar for the given user.
*
* @param Request $request
* @param int $id
* @return Response
*/
public function updateAvatar(Request $request, $id)
{
$user = User::findOrFail($id);
Storage::put(
'avatars/'.$user->id,
file_get_contents($request->file('avatar')->getRealPath())
);
}
}
When using multiple disks, you may access a particular
disk using the disk
method on the
Storage
facade. Of course, you may continue
to chain methods to execute methods on the disk:
$disk = Storage::disk('s3');
$contents = Storage::disk('local')->get('file.jpg')
Retrieving Files
The get
method may be used to retrieve the
contents of a given file. The raw string contents of the
file will be returned by the method:
$contents = Storage::get('file.jpg');
The exists
method may be used to determine
if a given file exists on the disk:
$exists = Storage::disk('s3')->exists('file.jpg');
File URLs
When using the local
or s3
drivers, you may use the url
method to get
the URL for the 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.
$url = Storage::url('file1.jpg');
Note: When using the
local
driver, be sure to create a symbolic link atpublic/storage
which points to thestorage/app/public
directory.
File Meta Information
The size
method may be used to get the size
of the file in bytes:
$size = Storage::size('file1.jpg');
The lastModified
method returns the UNIX
timestamp of the last time the file was modified:
$time = Storage::lastModified('file1.jpg');
Storing Files
The put
method may be used to store a file
on disk. You may also pass a PHP resource
to the put
method, which will use
Flysystem's underlying stream support. Using streams is
greatly recommended when dealing with large files:
Storage::put('file.jpg', $contents);
Storage::put('file.jpg', $resource);
The copy
method may be used to copy an
existing file to a new location on the disk:
Storage::copy('old/file1.jpg', 'new/file1.jpg');
The move
method may be used to rename or
move an existing file to a new location:
Storage::move('old/file1.jpg', 'new/file1.jpg');
Prepending / Appending To Files
The prepend
and append
methods
allow you to easily insert content at the beginning or
end of a file:
Storage::prepend('file.log', 'Prepended Text');
Storage::append('file.log', 'Appended Text');
File Visibility
File visibility can be retrieved and set via the
getVisibility
and
setVisibility
methods. Visibility is the
abstraction of file permissions across multiple
platforms:
Storage::getVisibility('file.jpg');
Storage::setVisibility('file.jpg', 'public')
Additionally, you can set the visibility when setting the
file via the put
method. The valid
visibility values are public
and
private
:
Storage::put('file.jpg', $contents, 'public');
Deleting Files
The delete
method accepts a single filename
or an array of files to remove from the disk:
Storage::delete('file.jpg');
Storage::delete(['file1.jpg', 'file2.jpg']);
Directories
Get All Files Within A Directory
The files
method returns an array of all of
the files in a given directory. If you would like to
retrieve a list of all files within a given directory
including all sub-directories, you may use the
allFiles
method:
$files = Storage::files($directory);
$files = Storage::allFiles($directory);
Get All Directories Within A Directory
The directories
method returns an array of
all the directories within a given directory.
Additionally, you may use the
allDirectories
method to get a list of all
directories within a given directory and all of its
sub-directories:
$directories = Storage::directories($directory);
// Recursive...
$directories = Storage::allDirectories($directory);
Create A Directory
The makeDirectory
method will create the
given directory, including any needed
sub-directories:
Storage::makeDirectory($directory);
Delete A Directory
Finally, the deleteDirectory
may be used to
remove a directory, including all of its files, from the
disk:
Storage::deleteDirectory($directory);
Custom Filesystems
Laravel's Flysystem integration provides drivers for several "drivers" out of the box; however, Flysystem is not limited to these and has adapters for many other storage systems. You can create a custom driver if you want to use one of these additional adapters in your Laravel application.
In order to set up the custom filesystem you will need to
create a service provider
such as DropboxServiceProvider
. In the
provider's boot
method, you may use the
Storage
facade's extend
method
to define the custom driver:
<?php
namespace App\Providers;
use Storage;
use League\Flysystem\Filesystem;
use Dropbox\Client as DropboxClient;
use Illuminate\Support\ServiceProvider;
use League\Flysystem\Dropbox\DropboxAdapter;
class DropboxServiceProvider extends ServiceProvider
{
/**
* Perform post-registration booting of services.
*
* @return void
*/
public function boot()
{
Storage::extend('dropbox', function($app, $config) {
$client = new DropboxClient(
$config['accessToken'], $config['clientIdentifier']
);
return new Filesystem(new DropboxAdapter($client));
});
}
/**
* Register bindings in the container.
*
* @return void
*/
public function register()
{
//
}
}
The first argument of the extend
method is
the name of the driver and the second is a Closure that
receives the $app
and $config
variables. The resolver Closure must return an instance
of League\Flysystem\Filesystem
. The
$config
variable contains the values
defined in config/filesystems.php
for the
specified disk.
Once you have created the service provider to register
the extension, you may use the dropbox
driver in your config/filesystem.php
configuration file.