working on filesystem docs.

filesystem.md

@@ -8,31 +8,63 @@
 <a name="introduction"></a>
 ## Introduction
 
-Laravel provides a wonderful filesystem abstraction thanks to the [Flysystem](https://github.com/thephpleague/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!
+Laravel provides a powerful filesystem abstraction thanks to the wonderful [Flysystem](https://github.com/thephpleague/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.
 
 <a name="configuration"></a>
 ## 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!
 
-Before using the S3 or Rackspace drivers, you will need to install the appropriate package via Composer:
-
-- Amazon S3: `league/flysystem-aws-s3-v2 ~1.0`
-- Rackspace: `league/flysystem-rackspace ~1.0`
-
 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-v2 ~1.0`
+- Rackspace: `league/flysystem-rackspace ~1.0`
+
 <a name="basic-usage"></a>
 ## Basic Usage
 
-The `Storage` facade may be used to interact with any of your configured disks. Alternatively, you may type-hint the `Illuminate\Contracts\Filesystem\Factory` contract on any class that is resolved via the Laravel [service container](/docs/{{version}}/container).
+The `Storage` facade may be used to interact with any of your configured disks. For example, to store an avatar on 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())
+			);
+		}
+	}
 
 #### Retrieving A Particular Disk
 
+When using multiple disks, you may access a particular disk using the `disk` method on the `Storage` facade:
+
 	$disk = Storage::disk('s3');
 
 	$disk = Storage::disk('local');
@@ -43,8 +75,9 @@ The `Storage` facade may be used to interact with any of your configured disks.
 
 #### Calling Methods On The Default Disk
 
-	if (Storage::exists('file.jpg'))
-	{
+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:
+
+	if (Storage::exists('file.jpg')) {
 		//
 	}
 
@@ -111,39 +144,47 @@ The `Storage` facade may be used to interact with any of your configured disks.
 <a name="custom-filesystems"></a>
 ## 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. Don't worry, it's not too hard!
-
-In order to set up the custom filesystem you will need to create a service provider such as `DropboxFilesystemServiceProvider`. In the provider's `boot` method, you can inject an instance of the `Illuminate\Contracts\Filesystem\Factory` contract and call the `extend` method of the injected instance. Alternatively, you may use the `Disk` facade's `extend` method.
-
-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`.
+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.
 
-> **Note:** The $config variable will already contain the values defined in `config/filesystems.php` for the specified disk.
-
-#### Dropbox Example
+In order to set up the custom filesystem you will need to create a [service provider](/docs/{{version}}/providers) 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 League\Flysystem\Dropbox\DropboxAdapter;
 	use Illuminate\Support\ServiceProvider;
+	use League\Flysystem\Dropbox\DropboxAdapter;
 
-	class DropboxFilesystemServiceProvider extends ServiceProvider {
-
+	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']);
+			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.