[Security] backported phpdoc from Guard component.

1 files changed, 11 insertions, 1 deletions

diff --git a/Http/EntryPoint/AuthenticationEntryPointInterface.php b/Http/EntryPoint/AuthenticationEntryPointInterface.php
index 0d7595d..c8e43e5 100644
--- a/Http/EntryPoint/AuthenticationEntryPointInterface.php
+++ b/Http/EntryPoint/AuthenticationEntryPointInterface.php
@@ -24,7 +24,17 @@ use Symfony\Component\HttpFoundation\Response;
 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 RedirectResponse('/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