Add LoginAttempting event for customizing authorization parameters (#382)

Author: Evan Sims

docs/Events.md

@@ -40,21 +40,22 @@ You can learn more about working with the Laravel event system in the [Laravel d
 
 During login with the `Auth0\Laravel\Http\Controller\Stateful\Login` controller, the following events may be raised:
 
-| Event                          | Description                                                                         |
-| ------------------------------ | ----------------------------------------------------------------------------------- |
-| `Illuminate\Auth\Events\Login` | Raised when a user is logging in. The model of the user is provided with the event. |
+| Event                                                   | Description                                                                                  |
+| ------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `Illuminate\Auth\Events\Login`                          | Raised when a user is logging in. The model of the user is provided with the event.          |
+| `Auth0\Laravel\Contract\Event\Stateful\LoginAttempting` | Raised before the login redirect is issued, allowing an opportunity to customize parameters. |
 
 ## Callback Controller Events
 
 During callback with the `Auth0\Laravel\Http\Controller\Stateful\Callback` controller, the following events may be raised:
 
-| Event                                                     | Description                                                                                                                                                                                                                                                             |
-| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `Illuminate\Auth\Events\Attempting`                       | Raised when a user is returned to the application after authenticating with Auth0. This is raised before verification of the authentication process begins.                                                                                                             |
-| `Illuminate\Auth\Events\Failed`                           | Raised when authentication with Auth0 failed. The reason is provided with the event as an array.                                                                                                                                                                        |
+| Event                                                     | Description                                                                                                                                                                                                                                                               |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Illuminate\Auth\Events\Attempting`                       | Raised when a user is returned to the application after authenticating with Auth0. This is raised before verification of the authentication process begins.                                                                                                               |
+| `Illuminate\Auth\Events\Failed`                           | Raised when authentication with Auth0 failed. The reason is provided with the event as an array.                                                                                                                                                                          |
 | `Auth0\Laravel\Event\Stateful\AuthenticationFailed`       | Raised when authentication with Auth0 failed. This provides an opportunity to intercept the exception thrown by the middleware, by using the event's `setThrowException()` method to `false`. You can also customize the type of exception thrown using `setException()`. |
-| `Illuminate\Auth\Events\Illuminate\Auth\Events\Validated` | Raised when authentication was successful, but immediately before the user's session is established.                                                                                                                                                                           |
-| `Auth0\Laravel\Event\Stateful\AuthenticationSucceeded`    | Raised when authentication was successful. The model of the authenticated user is provided with the event.                                                                                                                                                              |
+| `Illuminate\Auth\Events\Illuminate\Auth\Events\Validated` | Raised when authentication was successful, but immediately before the user's session is established.                                                                                                                                                                      |
+| `Auth0\Laravel\Event\Stateful\AuthenticationSucceeded`    | Raised when authentication was successful. The model of the authenticated user is provided with the event.                                                                                                                                                                |
 
 ## Logout Controller Events
 

src/Contract/Event/Stateful/LoginAttempting.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Auth0\Laravel\Contract\Event\Stateful;
+
+interface LoginAttempting
+{
+    /**
+     * @param array $parameters The login parameters array.
+     */
+    public function __construct(
+        array $parameters = [],
+    );
+
+    /**
+     * Returns the login parameters array.
+     */
+    public function getParameters(): array;
+
+    /**
+     * Replace the login parameters array.
+     *
+     * @param array $parameters
+     */
+    public function setParameters(array $parameters): self;
+}

src/Event/Stateful/LoginAttempting.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Auth0\Laravel\Event\Stateful;
+
+use Auth0\Laravel\Contract\Event\Stateful\LoginAttempting as LoginAttemptingContract;
+use Auth0\Laravel\Event\Auth0Event;
+
+final class LoginAttempting extends Auth0Event implements LoginAttemptingContract
+{
+    public function __construct(
+        private array $parameters = [],
+    ) {
+    }
+
+    public function getParameters(): array
+    {
+        return $this->parameters;
+    }
+
+    public function setParameters(array $parameters): self
+    {
+        $this->parameters = $parameters;
+
+        return $this;
+    }
+}

src/Http/Controller/Stateful/Login.php

@@ -8,6 +8,7 @@
 use Auth0\Laravel\Contract\Auth\Guard as GuardContract;
 use Auth0\Laravel\Contract\Entities\Credential;
 use Auth0\Laravel\Contract\Http\Controller\Stateful\Login as LoginContract;
+use Auth0\Laravel\Event\Stateful\LoginAttempting;
 use Auth0\Laravel\Http\Controller\ControllerAbstract;
 use Illuminate\Http\Request;
 use Symfony\Component\HttpFoundation\Response;
@@ -34,7 +35,12 @@ public function __invoke(
             return redirect()->intended(config('auth0.routes.home', '/'));
         }
 
-        $url = $this->getSdk()->login();
+        $event = new LoginAttempting();
+        event($event);
+
+        $url = $this->getSdk()->login(
+            params: $event->getParameters(),
+        );
 
         return redirect()->away($url);
     }