Improve documentation

Author: tgalopin

README.md

@@ -11,8 +11,10 @@ library into Symfony applications. It provides an efficient abstraction for the
 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.
 
-This bundle relies on **named aliases** (introduced in Symfony 4.2) in order to create and configure
-multiple filesystems and still follow the best practices of software architecture (SOLID principles). 
+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). 
 
 ## Installation
 
@@ -29,15 +31,18 @@ composer require league/flysystem-bundle
 1. [Getting started](https://github.com/thephpleague/flysystem-bundle/blob/master/docs/1-getting-started.md)
 2. Cloud storage providers:
    [Azure](https://github.com/thephpleague/flysystem-bundle/blob/master/docs/2-cloud-storage-providers.md#azure),
-   [AWS S3](https://github.com/thephpleague/flysystem-bundle/blob/master/docs/2-cloud-storage-providers.md#aws),
+   [AWS S3](https://github.com/thephpleague/flysystem-bundle/blob/master/docs/2-cloud-storage-providers.md#aws-s3),
    [DigitalOcean Spaces](https://github.com/thephpleague/flysystem-bundle/blob/master/docs/2-cloud-storage-providers.md#digitalocean-spaces),
    [Scaleway Object Storage](https://github.com/thephpleague/flysystem-bundle/blob/master/docs/2-cloud-storage-providers.md#scaleway-object-storage),
    [Google Cloud Storage](https://github.com/thephpleague/flysystem-bundle/blob/master/docs/2-cloud-storage-providers.md#google-cloud-storage),
    [Rackspace](https://github.com/thephpleague/flysystem-bundle/blob/master/docs/2-cloud-storage-providers.md#rackspace),
    [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. [Configuration reference](https://github.com/thephpleague/flysystem-bundle/blob/master/docs/5-configuration-reference.md)
+5. [Creating a custom adapter](https://github.com/thephpleague/flysystem-bundle/blob/master/docs/5-creating-a-custom-adapter.md)
+
+A. [Security issue disclosure procedure](https://github.com/thephpleague/flysystem-bundle/blob/master/docs/A-security-disclosure-procedure.md)
+B. [Configuration reference](https://github.com/thephpleague/flysystem-bundle/blob/master/docs/B-configuration-reference.md)
 
 ## Security Issues
 

docs/1-getting-started.md

@@ -157,3 +157,7 @@ flysystem:
 
 This configuration will swap every reference to the `users.storage` service (or to the
 `FilesystemInterface $usersStorage` typehint) from a local adapter to a memory one during tests.
+
+## Next
+
+[Cloud storage providers](https://github.com/thephpleague/flysystem-bundle/blob/master/docs/2-cloud-storage-providers.md)

docs/2-cloud-storage-providers.md

@@ -4,6 +4,14 @@ One of the core feature of Flysystem is its ability to interact easily with remo
 including many cloud storage providers. This bundle provides the same level of support for these
 cloud providers by providing corresponding adapters in the configuration.
 
+* [Azure](#azure)
+* [AWS S3](#aws-s3)
+* [DigitalOcean Spaces](#digitalocean-spaces)
+* [Scaleway Object Storage](#scaleway-object-storage)
+* [Google Cloud Storage](#google-cloud-storage)
+* [Rackspace](#rackspace)
+* [WebDAV](#webdav)
+
 ## Azure
 
 ### Installation
@@ -27,7 +35,7 @@ flysystem:
                 prefix: 'optional/path/prefix'
 ```
 
-## AWS
+## AWS S3
 
 ### Installation
 
@@ -150,3 +158,7 @@ flysystem:
                 prefix: 'optional/path/prefix'
                 use_stream_copy: false
 ```
+
+## Next
+
+[Interacting with FTP and SFTP servers](https://github.com/thephpleague/flysystem-bundle/blob/master/docs/3-interacting-with-ftp-and-sftp-servers.md)

docs/3-interacting-with-ftp-and-sftp-servers.md

@@ -1,7 +1,7 @@
 # Interacting with FTP and SFTP servers
 
-Flysystem is able to interact using the same FilesystemInterface with FTP and SFTP servers.
-To configure this bundle for this usage, you can rely on adapters in the same way you would
+Flysystem is able to interact with FTP and SFTP servers using the same FilesystemInterface.
+To configure this bundle for such usage, you can rely on adapters in the same way you would
 for other storages.
 
 ## FTP
@@ -56,3 +56,7 @@ flysystem:
                 root: '/path/to/root'
                 timeout: 10
 ```
+
+## Next
+
+[Caching metadata in Symfony cache](https://github.com/thephpleague/flysystem-bundle/blob/master/docs/4-caching-metadata-in-symfony-cache.md)

docs/4-caching-metadata-in-symfony-cache.md

@@ -1,13 +1,17 @@
 # Caching metadata in Symfony cache
 
+[Read the associated library documentation](https://flysystem.thephpleague.com/docs/advanced/caching/)
+
 Networking and I/O are often the source of performance problems in applications.
 On top of this, Flysystem generally aims to be as reliable as possible, which 
 means it will often check and validate operations before they are done. This
 involves an additional overhead on top of the classical slowness of I/O.
 
 When your application needs to scale, you may need to cache metadata in order to
-improve performances on this level. To do this, you can use the `cache` adapter
-in this bundle.
+improve performances on this level. To do this, you can use the `cache` adapter.
+
+> *Note:* this adapter caches anything but the file content. This keeps the cache 
+> small enough to be beneficial and covers all the file system inspection operations.
 
 ### Installation
 
@@ -17,71 +21,68 @@ composer require league/flysystem-cached-adapter
 
 ### Usage
 
-```yaml
-# config/packages/flysystem.yaml
+The cache adapter works using a source storage (from which it will read the uncached data)
+and a [Symfony cache pool](https://symfony.com/doc/current/reference/configuration/framework.html#pools). 
 
-flysystem:
-    storages:
-        users.storage.source:
-            adapter: 'aws'
-            options:
-                client: 'aws_client_service'
-                bucket: 'bucket_name'
-                prefix: 'optional/path/prefix'
+Most of the time you are only going to need one of two possibilities:
 
-        users.storage:
-            adapter: 'cache'
-            options:
-                store: 'psr6_cache_pool' # A service ID implementing Psr\Cache\CacheItemPoolInterface
-                source: 'users.storage.source'
-```
-
-However, this configuration is generic. Most of the time you are only
-going to need one of two possibilities:
-
-* memory cache: this cache will expire at the end of the current CLI process or 
-  HTTP request ;
-* persistant cache: this cache will only expire when you clear it ;
+* in-memory cache (will expire at the end of the CLI process or HTTP request) ;
+* persistant cache (will stay persistent in a cache backend) ;
 
 #### Memory caching
 
-To enable memory cache, you can create a dedicated service based on the Symfony
-Cache component:
+To use in-memory caching, you can create a dedicated Symfony cache pool:
 
 ```yaml
 # config/packages/flysystem.yaml
 
-services:
-    users.storage.cache:
-        class: 'Symfony\Component\Cache\Adapter\ArrayAdapter'
+framework:
+    cache:
+        pools:
+            cache.users.storage:
+                adapter: cache.adapter.array
+                default_lifetime: 3600
 
 flysystem:
     storages:
-        # ...
+        users.storage.source:
+            adapter: 'aws'
+            options:
+                client: 'aws_client_service'
+                bucket: 'bucket_name'
+                prefix: 'optional/path/prefix'
 
         users.storage:
             adapter: 'cache'
             options:
-                store: 'users.storage.cache'
+                store: 'cache.users.storage'
                 source: 'users.storage.source'
 ```
 
 #### Persistent caching
 
-To enable persistent cache, you can either define your own service in the same way
-as the memory cache, or rely on the `cache.app` service provided automatically by
-Symfony:
+To use persistent caching, you can either create a dedicated Symfony cache pool
+or use the pool `cache.app` which is defined by default by Symfony:
 
 ```yaml
 # config/packages/flysystem.yaml
 
 flysystem:
     storages:
-        # ...
+        users.storage.source:
+            adapter: 'aws'
+            options:
+                client: 'aws_client_service'
+                bucket: 'bucket_name'
+                prefix: 'optional/path/prefix'
 
         users.storage:
             adapter: 'cache'
             options:
                 store: 'cache.app'
                 source: 'users.storage.source'
 ```
+
+## Next
+
+[Configuration reference](https://github.com/thephpleague/flysystem-bundle/blob/master/docs/5-configuration-reference.md)

docs/5-creating-a-custom-adapter.md

@@ -0,0 +1,36 @@
+# Creating a custom adapter
+
+[Read the associated library documentation](https://flysystem.thephpleague.com/docs/advanced/creating-an-adapter/)
+
+If you have highly specific requirements, you may need to create your own
+Flysystem adapter. To do so, you first need to create the adapter code itself
+and then use it in your storages configuration.
+
+## Creating the adapter class
+
+A Flysystem adapter is a class implementing the `League\Flysystem\AdapterInterface` inteface.
+To learn all the details about how to create this class, you can read the 
+[library documentation](https://flysystem.thephpleague.com/docs/advanced/creating-an-adapter/).
+
+You can create this class everywhere you want in your application. We usually recommend a clear
+namespace and class name such as `App\Flysystem\MyCustomAdapter`.
+
+## Using the adapter in a storage configuration
+
+To use the adapter inside your storages configuration, you need to register your newly created
+as a service. Fortunately, in most Symfony 4.2+ applications, this is done automatically by Symfony.
+
+> *Note:* if you disabled autodiscovery, you can register manually your adapter as a normal service
+> and use the ID your registered instead of the class name in the next YAML examples.
+
+Once created and (automatically) registered as a service, you can reference your adapter inside your
+storages:
+
+```yaml
+# config/packages/flysystem.yaml
+
+flysystem:
+    storages:
+        users.storage:
+            adapter: 'App\Flysystem\MyCustomAdapter'
+```