authentication-results.md

Authentication Results

AuthenticationResult is the normal return value for authentication attempts.

Successful Results

$result = AuthenticationResult::authenticated($identity, 'Welcome.', [
    'driver' => 'database',
]);

$result->isAuthenticated(); // true
$result->identity();        // IdentityInterface

Successful results can produce a SecurityContext for authorization-aware code:

$context = $result->securityContext();

Expected Failures

Invalid credentials and unknown identities are expected outcomes:

AuthenticationResult::invalidCredentials();
AuthenticationResult::identityNotFound('ada@example.com');

Use status checks in login flows:

if ($result->status()->isCredentialFailure()) {
    return 'Invalid login.';
}

Other Statuses

The package also models locked identities, expired credentials, generic failures, guest state, and infrastructure errors:

AuthenticationResult::locked();
AuthenticationResult::expired();
AuthenticationResult::failed('Provider rejected the attempt.');
AuthenticationResult::error($throwable);

Exceptions On Demand

Most callers should use result objects. If a layer needs exceptions, call:

$result->throwIfFailed();

Credential failures become InvalidCredentialsException or IdentityNotFoundException; other failures become AuthenticationException.