Merge branch '5.1'

javiereguiluz · javiereguiluz · commit d0afa4f2c893 · 2020-09-07T20:51:34.000+02:00
* 5.1:
  Added the missing versionadded directive
  Tweak
  Update using_components.rst
  Add documentation about impersonating users with an HTTP Header
  Document RecoverableMessageHandlingException
diff --git a/components/using_components.rst b/components/using_components.rst
@@ -20,7 +20,7 @@ Using the Finder Component
 
 **1.** If you're creating a new project, create a new empty directory for it.
 
-**2.** Open a terminal and use Composer to grab the library.
+**2.** Open a terminal, step into this directory and use Composer to grab the library.
 
 .. code-block:: terminal
 
@@ -43,18 +43,26 @@ the ``vendor/autoload.php`` file that was generated by Composer. This file
 takes care of autoloading all of the libraries so that you can use them
 immediately::
 
-    // File example: src/script.php
-
-    // update this to the path to the "vendor/"
-    // directory, relative to this file
+    // Project structure example:
+    // my_project/
+    //     data/
+    //         ...              # Some project data
+    //     src/
+    //         my_script.php    # Main entry point
+    //     vendor/
+    //         autoload.php     # Autoloader generated by Composer
+    //         ...              # Packages downloaded by Composer
+
+    // File example: src/my_script.php
+    // Autoloader relative path to this PHP file
     require_once __DIR__.'/../vendor/autoload.php';
 
     use Symfony\Component\Finder\Finder;
 
     $finder = new Finder();
     $finder->in('../data/');
 
-    // ...
+    // rest of your PHP code...
 
 Now what?
 ---------
diff --git a/messenger.rst b/messenger.rst
@@ -724,6 +724,18 @@ and should not be retried. If you throw
 :class:`Symfony\\Component\\Messenger\\Exception\\UnrecoverableMessageHandlingException`,
 the message will not be retried.
 
+Forcing Retrying
+~~~~~~~~~~~~~~~~
+
+.. versionadded:: 5.1
+
+    The ``RecoverableMessageHandlingException`` was introduced in Symfony 5.1.
+
+Sometimes handling a message must fail in a way that you *know* is temporary
+and must be retried. If you throw
+:class:`Symfony\\Component\\Messenger\\Exception\\RecoverableMessageHandlingException`,
+the message will always be retried.
+
 .. _messenger-failure-transport:
 
 Saving & Retrying Failed Messages
diff --git a/security/impersonating_user.rst b/security/impersonating_user.rst
@@ -74,6 +74,11 @@ as the value to the current URL:
 
     http://example.com/somewhere?_switch_user=thomas
 
+.. tip::
+
+    Instead of adding a ``_switch_user`` query string parameter, you can pass
+    the username in a ``HTTP_X_SWITCH_USER`` header.
+
 To switch back to the original user, use the special ``_exit`` username:
 
 .. code-block:: text
