Merge branch '2.3' into 2.6

* 2.3:
  [#5015] Very small tweak
  [#5011] Adding one more fix I missed
  [#5011] Fixing minor build issue
  improved link
  fixed intendation and shortened the link
  Adding a break statement to improve the sample code
  Added an example about how to get the impersonating user object
  #4032 improved comments about em option
  tip for mapping definition

Author: weaverryan

Diff for: book/doctrine.rst

@@ -778,6 +778,8 @@ entities (the topic of :ref:`relations <book-doctrine-relations>` will be
 covered later), group, etc. For more information, see the official
 `Doctrine Query Language`_ documentation.
 
+.. _book-doctrine-custom-repository-classes:
+
 Custom Repository Classes
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 

Diff for: cookbook/form/data_transformers.rst

@@ -122,7 +122,9 @@ by calling ``addModelTransformer`` (or ``addViewTransformer`` - see
         {
             // ...
 
-            // this assumes that the entity manager was passed in as an option
+            // the "em" is an option that you pass when creating your form. Check out
+            // the 3rd argument to createForm in the next code block to see how this
+            // is passed to the form (also see setDefaultOptions).
             $entityManager = $options['em'];
             $transformer = new IssueToNumberTransformer($entityManager);
 

Diff for: cookbook/security/entity_provider.rst

@@ -583,6 +583,11 @@ The code below shows the implementation of the
         }
     }
 
+.. tip::
+
+    Don't forget to add the repository class to the 
+    :ref:`mapping definition of your entity <book-doctrine-custom-repository-classes>`.
+
 To finish the implementation, the configuration of the security layer must be
 changed to tell Symfony to use the new custom entity provider instead of the
 generic Doctrine entity provider. It's trivial to achieve by removing the

Diff for: cookbook/security/impersonating_user.rst

@@ -86,6 +86,23 @@ to show a link to exit impersonation:
             </a>
         <?php endif ?>
 
+In some cases you may need to get the object that represents the impersonating
+user rather than the impersonated user. Use the following snippet to iterate
+over the user's roles until you find one that a ``SwitchUserRole`` object::
+
+    use Symfony\Component\Security\Core\Role\SwitchUserRole;
+
+    $securityContext = $this->get('security.context');
+
+    if ($securityContext->isGranted('ROLE_PREVIOUS_ADMIN')) {
+        foreach ($securityContext->getToken()->getRoles() as $role) {
+            if ($role instanceof SwitchUserRole) {
+                $impersonatingUser = $role->getSource()->getUser();
+                break;
+            }
+        }
+    }
+
 Of course, this feature needs to be made available to a small group of users.
 By default, access is restricted to users having the ``ROLE_ALLOWED_TO_SWITCH``
 role. The name of this role can be modified via the ``role`` setting. For