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 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
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 has method may be used to determine if a
given file exists on the disk:
$exists = Storage::disk('s3')->has('file.jpg');
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');
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.