Merge pull request thephpleague#35 from thephpleague/lazy-adapter-doc

Add lazy adapter doc

Author: tgalopin

README.md

@@ -6,15 +6,11 @@
 
 [![SymfonyInsight](https://insight.symfony.com/projects/525fdfa3-d482-4218-b4b9-3c2efc305fac/big.svg)](https://insight.symfony.com/projects/525fdfa3-d482-4218-b4b9-3c2efc305fac)
 
-This repository is a light Symfony bundle integrating the [Flysystem](https://flysystem.thephpleague.com)
-library into Symfony applications. It provides an efficient abstraction for the filesystem,
-for instance to use local files in development and a cloud storage in production or to use a memory
-filesystem in tests to increase their speed.
+flysystem-bundle is a Symfony bundle integrating the [Flysystem](https://flysystem.thephpleague.com)
+library into Symfony applications. 
 
-This bundle relies on 
-[named aliases](https://symfony.com/doc/current/service_container/autowiring.html#dealing-with-multiple-implementations-of-the-same-type) 
-(introduced in Symfony 4.2) in order to create and configure multiple filesystems while still 
-following the best practices of software architecture (SOLID principles). 
+It provides an efficient abstraction for the filesystem in order to change the storage backend depending
+on the execution environment (local files in development, cloud storage in production and memory in tests).
 
 ## Installation
 
@@ -26,7 +22,76 @@ You can install the bundle using Symfony Flex:
 composer require league/flysystem-bundle
 ```
 
-## Documentation
+## Basic usage
+
+The default configuration file created by Symfony Flex provides enough configuration to
+use Flysystem in your application as soon as you install the bundle:
+
+```yaml
+# config/packages/flysystem.yaml
+
+flysystem:
+    storages:
+        default.storage:
+            adapter: 'local'
+            options:
+                directory: '%kernel.project_dir%/var/storage/default'
+```
+
+This configuration defines a single storage service (`default.storage`) based on the local adapter
+and configured to use the `%kernel.project_dir%/var/storage/default` directory.
+
+For each storage defined under `flysystem.storages`, an associated service is created using the
+name you provide (in this case, a service `default.storage` will be created). The bundle also
+creates a named alias for each of these services.
+
+This means you have two way of using the defined storages:
+
+* either using autowiring, by typehinting against the `FilesystemInterface` and using the
+  variable name matching one of your storages:
+
+    ```php
+    use League\Flysystem\FilesystemInterface;
+    
+    class MyService
+    {
+        private $storage;
+        
+        // The variable name $defaultStorage matters: it needs to be the camelized version
+        // of the name of your storage. 
+        public function __construct(FilesystemInterface $defaultStorage)
+        {
+            $this->storage = $defaultStorage;
+        }
+        
+        // ...
+    }
+    ```
+    
+  The same goes for controllers:
+    
+    ```php
+    use League\Flysystem\FilesystemInterface;
+    
+    class MyController
+    {
+        // The variable name $defaultStorage matters: it needs to be the camelized version
+        // of the name of your storage. 
+        public function index(FilesystemInterface $defaultStorage)
+        {
+            // ...
+        }
+    }
+    ```
+
+* or using manual injection, by injecting the service named `default.storage` inside 
+  your services.
+  
+Once you have a FilesystemInterface, you can call methods from the
+[Filesystem API](https://flysystem.thephpleague.com/docs/usage/filesystem-api/)
+to interact with your storage.
+
+## Full documentation
 
 1. [Getting started](https://github.com/thephpleague/flysystem-bundle/blob/master/docs/1-getting-started.md)
 2. Cloud storage providers:
@@ -39,7 +104,8 @@ composer require league/flysystem-bundle
    [WebDAV](https://github.com/thephpleague/flysystem-bundle/blob/master/docs/2-cloud-storage-providers.md#webdav)
 3. [Interacting with FTP and SFTP servers](https://github.com/thephpleague/flysystem-bundle/blob/master/docs/3-interacting-with-ftp-and-sftp-servers.md)
 4. [Caching metadata in Symfony cache](https://github.com/thephpleague/flysystem-bundle/blob/master/docs/4-caching-metadata-in-symfony-cache.md)
-5. [Creating a custom adapter](https://github.com/thephpleague/flysystem-bundle/blob/master/docs/5-creating-a-custom-adapter.md)
+5. [Using a lazy adapter to switch storage backend using an environment variable](https://github.com/thephpleague/flysystem-bundle/blob/master/docs/5-using-lazy-adapter-to-switch-at-runtime.md)
+6. [Creating a custom adapter](https://github.com/thephpleague/flysystem-bundle/blob/master/docs/6-creating-a-custom-adapter.md)
 
 * [Security issue disclosure procedure](https://github.com/thephpleague/flysystem-bundle/blob/master/docs/A-security-disclosure-procedure.md)
 * [Configuration reference](https://github.com/thephpleague/flysystem-bundle/blob/master/docs/B-configuration-reference.md)

docs/5-using-lazy-adapter-to-switch-at-runtime.md

@@ -0,0 +1,109 @@
+# Using a lazy adapter to switch storage backend using an environment variable
+
+One of the main reason why using a filesystem abstraction is useful is because
+you can switch the storage backend depending on the execution environment
+(local files in development, cloud storage in production and memory in tests).
+
+The classical way of doing this would be to create a 
+`config/packages/dev/flysystem.yaml` file that would override the configuration
+defined in `config/packages/flysystem.yaml`, thus creating a different storage 
+service for each environment.
+
+Using this technique is recommended in most cases: by declaring your services
+statically and relying on the environment to choose which one to use, you will
+profit from the performance optimizations done by the Symfony container to remove
+unused services.
+
+However, this technique is not always flexible enough. What if you need
+one staging production environment with local storage and the real production
+environment with cloud storage?
+
+In such cases, you need to choose the adapter to use at runtime instead of
+compile time. To do so, you can use a `lazy` adapter.
+
+A `lazy` adapter is a "fake" adapter that will delay the creation of the actual
+storage at runtime. This will allow you to change the storage to create dynamically,
+for instance using an environment variable.
+
+Let's take a real-world example:
+
+```yaml
+# config/packages/flysystem.yaml
+
+services:
+    Aws\S3\S3Client:
+        arguments:
+            - version: '2006-03-01'
+              region: 'fr-par'
+              credentials:
+                  key: '%env(S3_STORAGE_KEY)%'
+                  secret: '%env(S3_STORAGE_SECRET)%'
+
+flysystem:
+    storages:
+        uploads.storage.aws:
+            adapter: 'aws'
+            options:
+                client: 'Aws\S3\S3Client'
+                bucket: 'my-bucket'
+                prefix: '%env(S3_STORAGE_PREFIX)%'
+
+        uploads.storage.local:
+            adapter: 'local'
+            options:
+                directory: '%kernel.project_dir%/var/storage/uploads'
+
+        uploads.storage.memory:
+            adapter: 'memory'
+
+        uploads.storage:
+            adapter: 'lazy'
+            options:
+                source: '%env(APP_UPLOADS_SOURCE)%'
+```
+
+In this example, we define 3 actual storages: aws, local and memory. They
+have a `uploads.storage.` prefix to note their relationship with `uploads.storage`
+but this prefix does not have any impact on the behavior itself.
+
+By using a `lazy` adapter for `uploads.storage`, we are able to provide a source
+which will be actually used when the service will need to be instantiated. In this case,
+we rely on an environment variable to choose the actual storage to use.
+
+This technique allows us to specify a different storage to use in different environments:
+
+```
+# To use the AWS storage
+APP_UPLOADS_SOURCE=uploads.storage.aws
+
+# To use the local storage
+APP_UPLOADS_SOURCE=uploads.storage.local
+
+# To use the memory storage
+APP_UPLOADS_SOURCE=uploads.storage.memory 
+```
+
+Other than being created at runtime, the `lazy` adapter is behaving in the exact
+same way as any other storage:
+
+* you can use it with autowiring, by typehinting against the `FilesystemInterface` and using the
+  variable name matching its name:
+
+    ```php
+    use League\Flysystem\FilesystemInterface;
+    
+    class MyService
+    {
+        private $storage;
+        
+        public function __construct(FilesystemInterface $uploadsStorage)
+        {
+            $this->storage = $uploadsStorage;
+        }
+        
+        // ...
+    }
+    ```
+
+* you can use it in manual injection by injecting the service named `uploads.storage` inside 
+  your services.