[5.2] Add authenticate method to the guards (#13651)

* Make setUser fluent

* Create AuthenticationException

* Add authenticate method to the guards

* Convert an AuthenticationException into an unauthenticated response

AuthenticationException.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace Illuminate\Auth;
+
+use Exception;
+
+class AuthenticationException extends Exception
+{
+    /**
+     * The guard instance.
+     *
+     * @var \Illuminate\Contracts\Auth\Guard
+     */
+    protected $guard;
+
+    /**
+     * Create a new authentication exception.
+     *
+     * @param \Illuminate\Contracts\Auth\Guard|null  $guard
+     */
+    public function __construct($guard = null)
+    {
+        $this->guard = $guard;
+
+        parent::__construct('Unauthenticated.');
+    }
+
+    /**
+     * Get the guard instance.
+     *
+     * @return \Illuminate\Contracts\Auth\Guard|null
+     */
+    public function guard()
+    {
+        return $this->guard;
+    }
+}

GuardHelpers.php

@@ -23,6 +23,22 @@ trait GuardHelpers
      */
     protected $provider;
 
+    /**
+     * Determine if the current user is authenticated.
+     *
+     * @return \Illuminate\Contracts\Auth\Authenticatable
+     *
+     * @throws \Illuminate\Auth\AuthenticationException
+     */
+    public function authenticate()
+    {
+        if (! is_null($user = $this->user())) {
+            return $user;
+        }
+
+        throw new AuthenticationException($this);
+    }
+
     /**
      * Determine if the current user is authenticated.
      *
@@ -59,10 +75,12 @@ public function id()
      * Set the current user.
      *
      * @param  \Illuminate\Contracts\Auth\Authenticatable  $user
-     * @return void
+     * @return $this
      */
     public function setUser(AuthenticatableContract $user)
     {
         $this->user = $user;
+
+        return $this;
     }
 }

SessionGuard.php

@@ -691,13 +691,15 @@ public function getUser()
      * Set the current user.
      *
      * @param  \Illuminate\Contracts\Auth\Authenticatable  $user
-     * @return void
+     * @return $this
      */
     public function setUser(AuthenticatableContract $user)
     {
         $this->user = $user;
 
         $this->loggedOut = false;
+
+        return $this;
     }
 
     /**