improve documentation

Resources/doc/basic-usage.rst

@@ -116,8 +116,10 @@ for subsequent requests. The final cached image path would be similar to
 
 .. tip::
 
-    You can :doc:`prepare the cache in advance <commands>` and use the ``imagine_filter_cache`` filter to always
-    return a link to the final cached image.
+    You can prepare the cache in advance with either :doc:`the <commands>` or the
+    :doc:`message queue <resolve-cache-images-in-background>`. When you do that,
+    you can use the ``imagine_filter_cache`` filter to always return a link to
+    the final cached image.
 
 .. note::
 

Resources/doc/cache-manager.rst

@@ -6,21 +6,21 @@ Cache Manager
 Cache Removal
 -------------
 
-CacheManager allows to remove cache in various ways.
+CacheManager allows to remove cached images.
 
-Single path and filter:
+Remove the cache for a specific image and one filter set:
 
 .. code-block:: php
 
     $cacheManager->remove($path, $filter);
 
-Single path and all filters:
+Remove the cache for a specific image in all filter sets:
 
 .. code-block:: php
 
     $cacheManager->remove($path);
 
-Some paths and some filters:
+Remove a list of images for a list of filter sets:
 
 .. code-block:: php
 
@@ -29,7 +29,7 @@ Some paths and some filters:
         ['thumbnail_233x233', 'thumbnail_100x100']
     );
 
-The whole cache.
+Clear the whole cache:
 
 .. code-block:: php
 

Resources/doc/cache-resolver/amazons3.rst

@@ -16,11 +16,6 @@ by executing the following command in your project directory:
 
     $ composer require aws/aws-sdk-php
 
-.. note::
-
-    This command requires that `Composer`_ is installed globally, as explained in
-    their `installation documentation`_.
-
 Configuration
 -------------
 
@@ -141,5 +136,3 @@ options.
 
 
 .. _`aws-sdk-php`: https://github.com/amazonwebservices/aws-sdk-for-php
-.. _`Composer`: https://getcomposer.org/
-.. _`installation documentation`: https://getcomposer.org/doc/00-intro.md

Resources/doc/cache-resolver/aws_s3.rst

@@ -17,13 +17,6 @@ by executing the following command in your project directory:
 
     $ composer require aws/aws-sdk-php
 
-
-.. note::
-
-    This command requires that `Composer`_ is installed globally, as explained in
-    their `installation documentation`_.
-
-
 Configuration
 -------------
 
@@ -312,7 +305,5 @@ You can also use the constructor of the resolver to directly inject multiple opt
 
 
 .. _`aws-sdk-php`: https://github.com/amazonwebservices/aws-sdk-for-php
-.. _`Composer`: https://getcomposer.org/
-.. _`installation documentation`: https://getcomposer.org/doc/00-intro.md
 .. _`S3 SDK documentation`: http://docs.aws.amazon.com/aws-sdk-php/latest/class-Aws.S3.S3Client.html#_putObject
 .. _`Default Credential Provider Chain`: https://docs.aws.amazon.com/sdk-for-php/v3/developer-guide/guide_credentials.html

Resources/doc/cache-resolver/cache.rst

@@ -1,8 +1,14 @@
 
 .. _cache-resolver-cache:
 
-Cache Resolver
-==============
+Cache Resolver (deprecated)
+===========================
+
+.. warning::
+
+    This cache resolver is based on the discontinued `Doctrine Cache`_ library.
+
+    It is recommended to use the :doc:`PsrCacheResolver <psr_cache>` instead.
 
 The ``CacheResolver`` cannot be used by itself. Instead, it is a "wrapper" for
 another resolver.
@@ -18,11 +24,6 @@ by executing the following command in your project directory:
 
     $ composer require doctrine/cache
 
-.. note::
-
-    This command requires that `Composer`_ is installed globally, as explained in
-    their `installation documentation`_.
-
 Configuration
 -------------
 
@@ -110,5 +111,3 @@ filter set using the following configuration.
 
 
 .. _`Doctrine Cache`: https://github.com/doctrine/cache
-.. _`Composer`: https://getcomposer.org/
-.. _`installation documentation`: https://getcomposer.org/doc/00-intro.md

Resources/doc/cache-resolver/flysystem.rst

@@ -17,11 +17,6 @@ can be installed by executing the following command in your project directory:
 
     $ composer require oneup/flysystem-bundle
 
-.. note::
-
-    This command requires that `Composer`_ is installed globally, as explained in
-    their `installation documentation`_.
-
 Configuration
 -------------
 
@@ -103,5 +98,3 @@ the following configuration.
 
 .. _`Flysystem`: https://github.com/thephpleague/flysystem
 .. _`OneupFlysystemBundle`: https://github.com/1up-lab/OneupFlysystemBundle
-.. _`Composer`: https://getcomposer.org/
-.. _`installation documentation`: https://getcomposer.org/doc/00-intro.md

Resources/doc/cache-resolvers-custom.rst

@@ -0,0 +1,71 @@
+
+Custom Cache Resolver
+=====================
+
+You can define your own custom cache resolvers to handle cache resolution using
+your storage backend. Creating a custom cache resolver begins by creating
+a class that implements the ``ResolverInterface``:
+
+.. code-block:: php
+
+    interface ResolverInterface
+    {
+        public function isStored($path, $filter);
+        public function resolve($path, $filter);
+        public function store(BinaryInterface $binary, $path, $filter);
+        public function remove(array $paths, array $filters);
+    }
+
+Once you have defined your custom cache resolver, you need to define it as a
+service and tag it with ``liip_imagine.cache.resolver``:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/services.yml
+
+        services:
+            imagine.cache.resolver.my_custom:
+                class: AppBundle\Imagine\Cache\Resolver\MyCustomResolver
+                arguments:
+                    - "@filesystem"
+                    - "@router"
+                tags:
+                    - { name: "liip_imagine.cache.resolver", resolver: my_custom_cache }
+
+    .. code-block:: xml
+
+        <!-- app/config/services.xml -->
+
+        <service id="imagine.cache.resolver.my_custom" class="AppBundle\Imagine\Cache\Resolver\MyCustomResolver">
+            <tag name="liip_imagine.cache.resolver" resolver="my_custom_cache" />
+            <argument type="service" id="filesystem" />
+            <argument type="service" id="router" />
+        </service>
+
+.. note::
+
+    For more information on the Service Container, reference the official
+    `Symfony Service Container documentation`_.
+
+Now your custom cache resolver can be set as the global default
+using the name defined in the ``resolver`` attribute of the ``tags`` key.
+
+.. code-block:: yaml
+
+    liip_imagine:
+        cache: my_custom_cache
+
+Alternatively you can only set the custom cache resolver for just a specific
+filter set:
+
+.. code-block:: yaml
+
+    liip_imagine:
+        filter_sets:
+            my_special_style:
+                cache: my_custom_cache
+
+
+.. _`Symfony Service Container documentation`: http://symfony.com/doc/current/book/service_container.html

Resources/doc/cache-resolvers.rst

@@ -11,15 +11,18 @@ A number of built-in cache resolvers are available:
 
     cache-resolver/*
 
+When the built-in resolvers do not fit your requirements, you can write your own
+:doc:`custom cache resolver <cache-resolvers-custom>`.
 
-Set the Default Cache Resolver
-------------------------------
+
+Configure which Cache Resolver to use
+-------------------------------------
 
 The default cache is the :ref:`web path cache resolver <cache-resolver-web-path>`,
 which caches images under ``/media/cache/`` within your application web root path.
 
 You can specify the cache resolver to use per individual ``filter_sets`` or globally.
-To set the default cache resolver globally, use:
+To change the default cache resolver globally, use:
 
 .. code-block:: yaml
 
@@ -55,131 +58,3 @@ To change the cache resolver for a specific ``filter_set``, use the following co
                 cache: your_resolver
                 filters:
                     # the filter list
-
-Custom Cache Resolver
----------------------
-
-You can easily define your own, custom cache resolvers to handle cache resolution
-using any imaginable backend. Creating a custom cache resolver begins by creating
-a class that implements the ``ResolverInterface``, as shown below.
-
-.. code-block:: php
-
-    interface ResolverInterface
-    {
-        public function isStored($path, $filter);
-        public function resolve($path, $filter);
-        public function store(BinaryInterface $binary, $path, $filter);
-        public function remove(array $paths, array $filters);
-    }
-
-The following is a template for creating your own cache resolver. You must provide
-implementations for all methods to create a valid cache resolver.
-
-.. code-block:: php
-
-    <?php
-
-    namespace AppBundle\Imagine\Cache\Resolver;
-
-    use Liip\ImagineBundle\Binary\BinaryInterface;
-    use Liip\ImagineBundle\Exception\Imagine\Cache\Resolver\NotResolvableException;
-    use Liip\ImagineBundle\Imagine\Cache\Resolver\ResolverInterface;
-
-    class MyCustomResolver implements ResolverInterface
-    {
-        /**
-         * @param string $path
-         * @param string $filter
-         *
-         * @return bool
-         */
-        public function isStored($path, $filter)
-        {
-            /** @todo: implement */
-        }
-
-        /**
-         * @param string $path
-         * @param string $filter
-         *
-         * @return string
-         */
-        public function resolve($path, $filter)
-        {
-            /** @todo: implement */
-        }
-
-        /**
-         * @param BinaryInterface $binary
-         * @param string          $path
-         * @param string          $filter
-         */
-        public function store(BinaryInterface $binary, $path, $filter)
-        {
-            /** @todo: implement */
-        }
-
-        /**
-         * @param string[] $paths
-         * @param string[] $filters
-         */
-        public function remove(array $paths, array $filters)
-        {
-            /** @todo: implement */
-        }
-    }
-
-Once you have defined your custom cache resolver, you must define it as a service and tag it
-with ``liip_imagine.cache.resolver``.
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # app/config/services.yml
-
-        services:
-            imagine.cache.resolver.my_custom:
-                class: AppBundle\Imagine\Cache\Resolver\MyCustomResolver
-                arguments:
-                    - "@filesystem"
-                    - "@router"
-                tags:
-                    - { name: "liip_imagine.cache.resolver", resolver: my_custom_cache }
-
-    .. code-block:: xml
-
-        <!-- app/config/services.xml -->
-
-        <service id="imagine.cache.resolver.my_custom" class="AppBundle\Imagine\Cache\Resolver\MyCustomResolver">
-            <tag name="liip_imagine.cache.resolver" resolver="my_custom_cache" />
-            <argument type="service" id="filesystem" />
-            <argument type="service" id="router" />
-        </service>
-
-.. note::
-
-    For more information on the Service Container, reference the official
-    `Symfony Service Container documentation`_.
-
-Now your custom cache resolver can be set as the global default
-using the name defined in the ``resolver`` attribute of the ``tags`` key.
-
-.. code-block:: yaml
-
-    liip_imagine:
-        cache: my_custom_cache
-
-Alternatively you can only set the custom cache resolver for just a specific
-filter set:
-
-.. code-block:: yaml
-
-    liip_imagine:
-        filter_sets:
-            my_special_style:
-                cache: my_custom_cache
-
-
-.. _`Symfony Service Container documentation`: http://symfony.com/doc/current/book/service_container.html