AuthorizationException

Purpose and Scope

The AuthorizationException class represents authorization failures in the hypervel/auth package. This exception is thrown when a user attempts to perform an action they are not permitted to execute, typically after a gate evaluation or policy check fails. It encapsulates the authorization response, HTTP status codes, and provides methods for converting authorization failures into appropriate HTTP responses.

For information about authentication failures, see AuthenticationException. For details about the authorization Response object itself, see Authorization Responses.

---

Exception Structure

The AuthorizationException extends PHP's base Exception class and adds authorization-specific functionality through additional properties and methods.

Class Properties

Property	Type	Description
$response	?Response	The Response object from the gate evaluation containing allow/deny status and metadata
$status	?int	The HTTP status code to be returned (e.g., 403, 404)
$message	string	The exception message (inherited, default: "This action is unauthorized.")
$code	int|string	The exception code for categorizing authorization failures (inherited)

Class Hierarchy

Sources: src/Access/AuthorizationException.php1-91

---

Constructor and Default Values

The exception constructor provides sensible defaults for authorization failures:

The constructor src/Access/AuthorizationException.php25-30 accepts three optional parameters:

• $message: Custom error message (defaults to "This action is unauthorized.")
• $code: Error code for categorization (defaults to 0)
• $previous: Previous exception for exception chaining

Sources: src/Access/AuthorizationException.php25-30

---

HTTP Status Code Management

AuthorizationException provides methods for managing HTTP status codes, allowing the exception to specify the appropriate HTTP response status when caught by exception handlers.

Status Code Methods

Method	Return Type	Description
withStatus(?int $status)	static	Sets the HTTP status code (e.g., 403 for forbidden, 404 for not found)
asNotFound()	static	Convenience method that sets status to 404
hasStatus()	bool	Checks if a status code has been explicitly set
status()	?int	Retrieves the current status code

Status Code Flow

Usage Example Context:

When a gate denies access because a resource doesn't exist or shouldn't be revealed to the user, using asNotFound() src/Access/AuthorizationException.php63-66 returns a 404 status instead of 403, preventing information disclosure about the existence of protected resources.

Sources: src/Access/AuthorizationException.php52-82

---

Response Integration

The AuthorizationException is tightly integrated with the Response class, which represents the result of gate evaluations and policy checks.

Response Association

The setResponse() method src/Access/AuthorizationException.php43-48 stores the original Response object within the exception, preserving context about:

• The authorization decision (allow/deny)
• The reason message
• The error code
• Any custom status code

Response Retrieval

The response() method src/Access/AuthorizationException.php35-38 allows exception handlers and middleware to access the original Response object, enabling them to extract detailed authorization context for logging, auditing, or custom error formatting.

Sources: src/Access/AuthorizationException.php35-48 src/Access/Response.php103-112

---

Converting Exception to Response

The toResponse() method src/Access/AuthorizationException.php87-90 converts the exception back into a Response object, which is useful for standardized error handling:

This method creates a denial Response with:

1. The exception's message
2. The exception's code
3. The exception's HTTP status code

Sources: src/Access/AuthorizationException.php87-90

---

Exception Flow in Authorization System

The following diagram illustrates how AuthorizationException fits into the complete authorization flow:

Key Integration Points

1. Response.authorize(): The Response class throws AuthorizationException when the response is denied src/Access/Response.php103-112
2. Middleware Handling: The Authorize middleware catches the exception and converts it to an HTTP response
3. Exception Context: The exception carries both the response and status code for proper error handling

Sources: src/Access/Response.php103-112 src/Access/AuthorizationException.php87-90

---

Usage Patterns

Pattern 1: Automatic Throwing via Response

The most common pattern is through the Response::authorize() method:

Code Location: src/Access/Response.php103-112

Pattern 2: Manual Exception Creation

For custom authorization logic outside the gate system:

Pattern 3: 404 Status for Resource Hiding

When authorization failure should appear as "not found":

This is equivalent to:

Code Location: src/Access/AuthorizationException.php63-66

Pattern 4: Exception with Response Context

Preserving full authorization context:

Sources: src/Access/AuthorizationException.php43-66 src/Access/Response.php53-64

---

Method Reference

Constructor

Signature: __construct(?string $message = null, int|string|null $code = null, ?Throwable $previous = null)

Creates a new authorization exception with optional message, code, and previous exception for chaining.

Location: src/Access/AuthorizationException.php25-30

---

response()

Signature: response(): ?Response

Returns the associated Response object if one has been set via setResponse().

Returns: The gate Response or null if not set

Location: src/Access/AuthorizationException.php35-38

---

setResponse()

Signature: setResponse(?Response $response): static

Associates a Response object with this exception, preserving full authorization context.

Parameters:

• $response: The Response from gate evaluation

Returns: $this for method chaining

Location: src/Access/AuthorizationException.php43-48

---

withStatus()

Signature: withStatus(?int $status): static

Sets the HTTP response status code for this authorization failure.

Parameters:

• $status: HTTP status code (e.g., 403, 404)

Returns: $this for method chaining

Location: src/Access/AuthorizationException.php52-58

---

asNotFound()

Signature: asNotFound(): static

Convenience method that sets the HTTP status to 404, useful for hiding the existence of protected resources.

Returns: $this for method chaining

Location: src/Access/AuthorizationException.php63-66

---

hasStatus()

Signature: hasStatus(): bool

Checks whether an HTTP status code has been explicitly set on this exception.

Returns: true if status is set, false otherwise

Location: src/Access/AuthorizationException.php71-74

---

status()

Signature: status(): ?int

Retrieves the HTTP status code set on this exception.

Returns: The status code or null if not set

Location: src/Access/AuthorizationException.php79-82

---

toResponse()

Signature: toResponse(): Response

Converts the exception into a denial Response object, carrying over the message, code, and status.

Returns: A new Response object representing the denial

Location: src/Access/AuthorizationException.php87-90

---

Code Entity Mapping

Sources: src/Access/AuthorizationException.php1-91 src/Access/Response.php1-159