Merge branch '2.8'

* 2.8: (29 commits)
  Updating AbstractVoter so that the method receives the TokenInterface
  Adding the necessary files so that Guard can be its own installable component
  Fix syntax in a test
  Normalize the way we check versions
  Avoid errors when generating the logout URL when there is no firewall key
  Removing unnecessary override
  fabbot
  Adding a new exception and throwing it when the User changes
  Fixing a bug where having an authentication failure would log you out.
  Tweaks thanks to Wouter
  Adding logging  on this step and switching the order - not for any huge reason
  Adding a base class to assist with form login authentication
  Allowing for other authenticators to be checked
  meaningless author and license changes
  Adding missing factory registration
  Thanks again fabbot!
  A few more changes thanks to @iltar
  Splitting the getting of the user and checking credentials into two steps
  Tweaking docblock on interface thanks to @iltar
  Adding periods at the end of exceptions, and changing one class name to LogicException thanks to @iltar
  ...

Conflicts:
	UPGRADE-2.8.md
	src/Symfony/Bridge/Twig/Tests/Node/DumpNodeTest.php
	src/Symfony/Bundle/FrameworkBundle/Command/ServerCommand.php
	src/Symfony/Component/Validator/Tests/Constraints/AbstractComparisonValidatorTestCase.php
	src/Symfony/Component/Validator/Tests/Constraints/IdenticalToValidatorTest.php
	src/Symfony/Component/Validator/Tests/Constraints/RangeValidatorTest.php

1 files changed, 13 insertions, 3 deletions

diff --git a/Http/EntryPoint/AuthenticationEntryPointInterface.php b/Http/EntryPoint/AuthenticationEntryPointInterface.php
index 0d7595d..df777f6 100644
--- a/Http/EntryPoint/AuthenticationEntryPointInterface.php
+++ b/Http/EntryPoint/AuthenticationEntryPointInterface.php
@@ -16,15 +16,25 @@ use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\HttpFoundation\Response;
 
 /**
- * AuthenticationEntryPointInterface is the interface used to start the
- * authentication scheme.
+ * Implement this interface for any classes that will be called to "start"
+ * the authentication process (see method for more details).
  *
  * @author Fabien Potencier <fabien@symfony.com>
  */
 interface AuthenticationEntryPointInterface
 {
     /**
-     * Starts the authentication scheme.
+     * Returns a response that directs the user to authenticate.
+     *
+     * This is called when an anonymous request accesses a resource that
+     * requires authentication. The job of this method is to return some
+     * response that "helps" the user start into the authentication process.
+     *
+     * Examples:
+     *  A) For a form login, you might redirect to the login page
+     *      return new Response('/login');
+     *  B) For an API token authentication system, you return a 401 response
+     *      return new Response('Auth header required', 401);
      *
      * @param Request                 $request       The request that resulted in an AuthenticationException
      * @param AuthenticationException $authException The exception that started the authentication process