default redirect with 302 instead of 301

DependencyInjection/Configuration.php

@@ -153,7 +153,7 @@ public function getConfigTreeBuilder()
                     ->children()
                         ->scalarNode('filter_action')->defaultValue(sprintf('%s::filterAction', ImagineController::class))->end()
                         ->scalarNode('filter_runtime_action')->defaultValue(sprintf('%s::filterRuntimeAction', ImagineController::class))->end()
-                        ->integerNode('redirect_response_code')->defaultValue(301)
+                        ->integerNode('redirect_response_code')->defaultValue(302)
                             ->validate()
                                 ->ifTrue(function ($redirectResponseCode) {
                                     return !\in_array($redirectResponseCode, ControllerConfig::REDIRECT_RESPONSE_CODES, true);

Resources/doc/basic-usage.rst

@@ -117,9 +117,10 @@ for subsequent requests. The final cached image path would be similar to
 .. tip::
 
     You can prepare the cache in advance with either the :doc:`commands <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.
+    or the :doc:`message queue <optimizations/resolve-cache-images-in-background>`,
+    or :doc:`handle missing files with web server configuration <optimizations/avoid-redirects>`.
+    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/commands.rst

@@ -38,7 +38,7 @@ Warm up Cache
 .. note::
 
     To automate cache warming, have a look at the
-    :doc:`Symfony Messenger integration <resolve-cache-images-in-background>`.
+    :doc:`Symfony Messenger integration <optimizations/resolve-cache-images-in-background>`.
 
 .. code-block:: bash
 

Resources/doc/configuration.rst

@@ -42,7 +42,7 @@ The default configuration for the bundle looks like this:
         controller:
             filter_action:          liip_imagine.controller:filterAction
             filter_runtime_action:  liip_imagine.controller:filterRuntimeAction
-            redirect_response_code: 301
+            redirect_response_code: 302
         webp:
             generate:    false
             quality:     100
@@ -91,7 +91,8 @@ There are several configuration options available:
     * ``filter_runtime_action`` - name of the controller action to use in the route
       loader for runtimeconfig images. Default value: ``liip_imagine.controller:filterRuntimeAction``
     * ``redirect_response_code`` - The HTTP redirect response code to return from the imagine controller,
-      one of ``201``, ``301``, ``302``, ``303``, ``307``, or ``308``. Default value: ``301``
+      one of ``201``, ``301``, ``302``, ``303``, ``307``, or ``308``. Default value: ``302``
+      See :doc:`optimizations/avoid-redirects` if you want to change this configuration.
 * ``webp``
     * ``generate`` - enabling the generation a copy of the image in the WebP format.
     * ``quality`` - override the quality from filter option.

Resources/doc/index.rst

@@ -45,11 +45,6 @@ usage to the architecture of bundle.
     cache-manager
     asset-versioning
     commands
-
-.. toctree::
-    :maxdepth: 2
-
-    resolve-cache-images-in-background
-
+    optimizations
 
 .. _`LiipImagineBundle`: /~https://github.com/liip/LiipImagineBundle

Resources/doc/optimizations.rst

@@ -0,0 +1,10 @@
+
+
+Optimizations
+=============
+
+.. toctree::
+    :maxdepth: 2
+
+    optimizations/resolve-cache-images-in-background
+    optimizations/avoid-redirects

Resources/doc/optimizations/avoid-redirects.rst

@@ -0,0 +1,46 @@
+
+
+Avoid unnecessary redirects
+===========================
+
+If you can not use :doc:`symfony messenger <resolve-cache-images-in-background>`,
+you can configure your webserver to avoid some redirects from the image
+controller. The solution described in this documentation only works when using
+the ``WebPathResolver``, not when you store the images in a place outside of
+the web server.
+
+When an image has not been cached, the ``imagine_filter`` generates the image
+link as a path to the image controller. The image controller creates the image
+and then redirects the client to the generated image.
+
+By default, this redirection is done with status ``302`` (moved temporarily).
+This is important, because when you later clear the cache, the controller needs
+to be called again so that the image is regenerated. When returning ``301``, we
+tell the client that the resource moved permanently. The client will cache this
+information and directly request the (not existing) cached image even when the
+twig filter generates the controller URL again.
+
+If you want to safely use ``301`` to avoid unnecessary redirects, you need to
+configure your webserver to route requests for missing images to Symfony.
+
+.. code-block:: bash
+
+    # bypass thumbs cache image files
+    location ~ ^/media/cache/resolve {
+      expires 1M;
+      access_log off;
+      add_header Cache-Control "public";
+      try_files $uri $uri/ /index.php?$query_string;
+    }
+
+    location ~* .(js|jpg|jpeg|gif|png|css|tgz|gz|rar|bz2|doc|pdf|ppt|tar|wav|bmp|rtf|swf|ico|flv|txt|woff|woff2|svg)$ {
+        expires 30d;
+        add_header Pragma "public";
+        add_header Cache-Control "public";
+    }
+
+With such a configuration, you can safely set ``liip_imagine.controller.redirect_response_code``
+to 301.
+
+If you configure your web server like this, you can also use the
+``imagine_filter_cache`` to never redirect your client.