AuthenticationException

Purpose and Scope

The AuthenticationException class represents a failed authentication attempt within the hypervel/auth system. This exception is thrown when a user cannot be authenticated by any of the specified guards, typically during middleware processing. It encapsulates context about which guards were checked and provides flexible redirect path resolution for handling unauthenticated requests.

This page covers the exception's structure, lifecycle, and redirect handling mechanisms. For information about how the exception is caught and processed in the authentication middleware, see Authenticate Middleware. For general exception handling concepts, see Exception Handling.

Class Overview

The AuthenticationException class extends PHP's base Exception class and adds authentication-specific context. It tracks which guards failed authentication and provides multiple strategies for determining where to redirect unauthenticated users.

Key Properties

Property	Type	Visibility	Purpose
$guards	array	protected	List of guard names that were checked during authentication
$redirectTo	?string	protected	Instance-specific redirect path
$redirectToCallback	?callable	protected static	Global callback for generating redirect paths

Sources: src/AuthenticationException.php15-27

Constructor

The exception constructor accepts three parameters:

• $message: Human-readable error message (defaults to "Unauthenticated.")
• $guards: Array of guard names that failed authentication
• $redirectTo: Optional redirect path specific to this exception instance

Sources: src/AuthenticationException.php34-40

Exception Structure and Properties

Diagram: AuthenticationException class structure

The exception maintains three pieces of state for redirect resolution, evaluated in order of precedence: instance-level redirect path, static callback, and null (no redirect).

Sources: src/AuthenticationException.php1-75

Exception Throwing Flow

The AuthenticationException is thrown by the Authenticate middleware when no guards successfully authenticate the user.

Diagram: Exception throwing sequence from middleware

The middleware iterates through configured guards, throwing the exception only after all guards fail. The exception carries the list of checked guards for diagnostic purposes.

Sources: src/Middleware/Authenticate.php38-65

Guard Context

The guards property stores the names of all guards that were checked during the authentication attempt. This context is useful for:

• Debugging: Identifying which authentication strategies were attempted
• Logging: Recording authentication failures with specific guard context
• Exception Handling: Customizing responses based on which guards failed

Accessing Guards

The guards() method returns the array of guard names:

When the Authenticate middleware doesn't specify guards explicitly, the array contains [null], indicating the default guard was checked.

Sources: src/AuthenticationException.php47-50 src/Middleware/Authenticate.php40-42

Redirect Resolution Mechanism

The exception provides a three-tiered strategy for determining redirect paths, evaluated in order:

Diagram: Redirect path resolution logic

Sources: src/AuthenticationException.php55-66

1. Instance-Level Redirect

The most specific redirect path, set during exception construction:

This takes precedence over all other redirect mechanisms.

2. Static Callback Registration

Applications can register a global callback for dynamic redirect generation using AuthenticationException::redirectUsing():

The callback receives the PSR-7 RequestInterface and can inspect request properties (path, headers, etc.) to determine the appropriate redirect path.

Sources: src/AuthenticationException.php69-74

3. Null Return

If neither an instance redirect nor a static callback is configured, redirectTo() returns null. Exception handlers should interpret this as:

• For API requests: Return a 401 JSON response
• For web requests: Use a default login route or return 401

Integration with Exception Handlers

Exception handlers should implement the following pattern when catching AuthenticationException:

Diagram: Exception handler response decision tree

The handler should:

1. Call $exception->redirectTo($request) to get the redirect path
2. If a path is returned, redirect the user (HTTP 302)
3. If null is returned:
   • Check if the request expects JSON (via Accept header)
   • Return 401 with JSON body for API requests
   • Return 401 with HTML for web requests

Sources: src/AuthenticationException.php55-66

Usage Examples

Basic Usage in Middleware

The Authenticate middleware creates the exception with guard context:

Sources: src/Middleware/Authenticate.php59-65

Registering a Global Redirect Callback

In your application bootstrap:

Custom Exception Throwing

While typically thrown by middleware, you can throw the exception directly:

Exception Handling Best Practices

Logging Authentication Failures

Exception handlers should log authentication failures with guard context:

Conditional Redirects

Use the static callback for complex redirect logic:

Response Formatting

Structure JSON error responses consistently:

Relationship to Authentication Flow

The exception serves as the failure boundary in the authentication system:

Diagram: Exception's role in authentication flow

The exception acts as the boundary between the authentication system and the HTTP response layer, carrying context needed for proper error handling.

Sources: src/Middleware/Authenticate.php26-66 src/AuthenticationException.php1-75

Summary

The AuthenticationException class provides:

• Context preservation: Maintains a record of which guards were checked
• Flexible redirects: Three-tiered strategy for determining redirect paths
• PSR-7 integration: Works with PSR-7 request interfaces for framework interoperability
• Static configuration: Global callback registration for application-wide redirect logic

This exception is the primary mechanism for signaling authentication failures in the hypervel/auth system, enabling exception handlers to respond appropriately based on request type (web vs. API), guard context, and application-specific redirect requirements.