Laravel 5.0 - Cloud File Drivers

(This is part of a series of posts on New Features in Laravel 5.0.)

  1. Laravel 5.0 - Form Requests
  2. Laravel 5.0 - ValidatesWhenResolved
  3. Laravel 5.0 - Directory structure and namespace
  4. Laravel 5.0 - Route Caching
  5. Laravel 5.0 - Cloud File Drivers
  6. Laravel 5.0 - Method Injection
  7. Laravel 5.0 - Route Annotations (removed)
  8. Laravel 5.0 - Event Annotations (removed)
  9. Laravel 5.0 - Middleware (Filter-style)
  10. Laravel 5.0 - Environment Detection & Environment Variables
  11. Laravel 5.0 - Event Scheduling
  12. Laravel 5.0 - Commands & Handlers
  13. Upgrading from Laravel 4 to Laravel 5
  14. Bringing Whoops Back to Laravel 5
  15. Laravel 5.0 - Events & Handlers
  16. Laravel 5.0 - Generating Missing Events
  17. Laravel 5.0 - Custom Error Pages
  18. Laravel 5.0 - Eloquent Attribute Casting

In Laravel 5, you can now use the same Filesystem class which previously simplified interactions with the local filesystem, and now also use it with S3 and Rackspace. It's a simple interface, powered on the backend by Frank de Jonge's Flysystem.

That means that you can write your app just like you did using local file storage:

/**
 * Save a thing
 * @param Thing  $thing
 * @param string $filename
 */
public function saveThing(Thing $thing, $filename)
{
    File::put('uploads/' . $filename, $thing);
}

But now you can, at any point, change your production app settings to use an external host (we'll use s3 in our example) instead, without changing a line of your business logic.

Making the switch to s3 #

First, you have to add the cloud provider's dependency to composer.json; for s3, it's the AWS SDK (aws\aws-sdk-php).

$ composer require aws\aws-sdk-php

Then, edit config/filesystems.php (or config/production/filesystems.php, so you're only configuring for the production site), change the default driver from local to s3, and then add your s3 credentials to the s3 section of the disks array:

return [
    'default' => 's3',
    'disks' => [
        's3' => [
            'driver' => 's3',
            'key' => 'fslkfqweoirqew',
            'secret' => '24j12oin12oi5nio251',
            'bucket' => 'my-awesome-website-bucket'                        
        ]
    ]
];

Cloud default vs. normal default #

Uniquely, the Filesystem config has two defaults: The Filesystem default (which is injected when you typehint Illuminate\Contracts\Filesystem\Filesystem, and also bound to the Container as filesystem.disk) and the Cloud default (which is injected when you typehint Illuminate\Contracts\Filesystem\Cloud, and also bound to the Container as filesystem.cloud). This way you can have any given environment have a default local and a default cloud filesystem config.

If you're using the façade, you're going to get the default default by default, rather than the cloud default. (Say that five times fast...)

Notes #

  • You could also use the same credentials for multiple environments and just use different buckets; or you could use different credentials; or you could even use different drivers. It's entirely up to you.
  • All of the usual File methods are available against these new drivers—put, get, etc.
  • Remember to inject the Filesystem Contract (Illuminate\Contracts\Filesystem\Filesystem) instead of using the façade if you're accessing files anywhere other than your controllers.
  • I didn't know this, but Jeffrey Way shows you how you can in your code (not in config) define which driver you want to use by injecting the Filesystem Factory. Learn more at his Laracast about Multiple Filesystems

Conclusion #

Once you've installed the AWS SDK and edited filesystems.php, all of your file operations are now happening against your s3 account. That's it! No extra work, no extra steps: you're up and running, storing and accessing files in the cloud like a pro. Way to go.


Comments? I'm @stauffermatt on Twitter


Tags: laravel | laravel 5 | 5.0

Matt Stauffer headshot

Hi, I'm Matt Stauffer.

I'm partner & technical director at Tighten Co.

You can find me on Twitter at @stauffermatt


Like what you're reading?

I wrote an entire 450+ page book for O'Reilly: Laravel: Up and Running.

You can order the eBook or print book today.