[8.x] Adds attemptWith() with tests

[DarkGhostHunter]

This PR expands on the discussion here about adding callbacks the the authentication attempt mechanism.

Problem

There is no way to add additional checks at runtime when using attempt(). Any addition forces the developer to create a new Guard, or use nonchalantly validate() and getLastAttempted(), and fire Attempting and Failed manually.

if (Auth::validate($credentials) && $user = Auth::getLastAttempted()) {
    if ($user->isAwesomeAndCool()) {
        Auth::login($user, $request->filled('remember'));
        Event::fire(Attempting('session', $credentials, $request->filled('remember')));
        return $this->redirect();
    }
    Event::fire(Failed(...));
}


return $this->sendAttemptFailed();

As you can see, this whole mess becomes spaghetti (yum!) code quickly.

Solution

This PR adds the SessionGuard::attemptWith() method. It's a carbon copy of the original attempt() method, but receives a third argument of one or multiple callbacks. After the user is validated, each of these run an additional check by receiving the validated User. If one callback returns false, the whole attempt fails.

$result = Auth::attempt($credentials, false, function (Authenticatable $user, SessionGuard $guard) {
    return $user->isAwesomeAndCool();
});

return $result 
    ? $this->redirect() 
    : $this->sendAttemptFailed();

Since there are callables, the developer can add its own checks, or use checks made by external packages, all while controlling manually the flow and order of these.

If the user validation fails, the callbacks are not executed, thus keeping the original validation procedure intact.

How it works

The change adds the attemptWith() and the internal method shouldLogin(). The latter executes each callback and returns false if one of them "fails". This is called after the user is properly validated:

if ($this->hasValidCredentials($user, $credentials) && $this->shouldLogin($callbacks, $user)) {
    $this->login($user, $remember);

     return true;
}

Since it's a new method, no breaking changes are in sight.