minor symfony#9726 Improved the multiple user providers article (javi…

…ereguiluz)

This PR was squashed before being merged into the 2.7 branch (closes symfony#9726).

Discussion
----------

Improved the multiple user providers article

This tries to solve both symfony#8582 and symfony#8611. Please @xabbuh, @chalasr and @ogizanagi tell me if I did what you expected according to your comments in the related issues. Thanks!

Commits
-------

e0f483b Improved the multiple user providers article

security/multiple_user_providers.rst

@@ -1,6 +1,12 @@
 How to Use multiple User Providers
 ==================================
 
+.. note::
+
+    It's always better to use a specific user provider for each authentication
+    mechanism. Chaining user providers should be avoided in most applications
+    and used only to solve edge cases.
+
 Each authentication mechanism (e.g. HTTP Authentication, form login, etc)
 uses exactly one user provider, and will use the first declared user provider
 by default. But what if you want to specify a few users via configuration
@@ -150,5 +156,25 @@ system will use the ``in_memory`` user provider. But if the user tries to
 log in via the form login, the ``user_db`` provider will be used (since it's
 the default for the firewall as a whole).
 
+If you need to check that the user being returned by  your provider is a allowed
+to authenticate, check the returned user object::
+
+    use Symfony\Component\Security\Core\User;
+    // ...
+
+    public function loadUserByUsername($username)
+    {
+        // ...
+
+        // you can, for example, test that the returned user is an object of a
+        // particular class or check for certain attributes of your user objects
+        if ($user instance User) {
+            // the user was loaded from the main security config file. Do something.
+            // ...
+        }
+
+        return $user;
+    }
+
 For more information about user provider and firewall configuration, see
 the :doc:`/reference/configuration/security`.