Authorization Responses

Purpose

This document details the Response class, which encapsulates authorization decisions with allow/deny outcomes, optional messages, codes, and HTTP status codes. Authorization responses provide a structured way to represent authorization results that can be inspected programmatically or converted to exceptions for error handling.

For the overall authorization system, see page 3. For the Gate implementation, see page 3.1. For policies, see page 3.2.

Sources: src/Access/Response.php1-159

Overview

The authorization system returns Response objects from all authorization checks. Each response encapsulates:

• Allowed/Denied state: Boolean indicating authorization success
• Message: Optional human-readable explanation
• Code: Optional machine-readable identifier
• HTTP Status: Optional status code for web framework integration

Sources: src/Access/Response.php10-32

Response Class Structure

Class Definition and Interfaces

The Response class implements two interfaces for flexible usage:

Response Class Structure

Sources: src/Access/Response.php10-32 src/Access/Response.php143-158

Response Properties

Property	Type	Description	Access
allowed	bool	Authorization decision (true = allowed, false = denied)	Protected, via constructor
message	?string	Human-readable explanation of the decision	Protected, via constructor
code	int|string|null	Machine-readable identifier for the result	Protected, via constructor
status	?int	HTTP status code for web responses	Protected, set via methods

Sources: src/Access/Response.php15-27

Creating Responses

Static Factory Methods

The Response class provides static factory methods for creating responses:

Response Factory Methods

Sources: src/Access/Response.php37-64

Factory Method Reference

Method	Signature	Returns	Use Case
allow()	allow(?string $message, int|string|null $code): Response	Allow response	Authorization granted
deny()	deny(?string $message, int|string|null $code): Response	Deny response	Authorization denied
denyWithStatus()	denyWithStatus(int $status, ?string $message, int|string|null $code): Response	Deny response with HTTP status	Custom HTTP status needed
denyAsNotFound()	denyAsNotFound(?string $message, int|string|null $code): Response	Deny response with 404 status	Hide resource existence

Sources: src/Access/Response.php37-64

Response Methods

Inspection Methods

The Response class provides methods to inspect the authorization decision:

Method	Returns	Description
allowed()	bool	Returns true if authorization was granted
denied()	bool	Returns true if authorization was denied (inverse of allowed())
message()	?string	Returns the human-readable message
code()	int|string|null	Returns the machine-readable code
status()	?int	Returns the HTTP status code if set

Sources: src/Access/Response.php69-96 src/Access/Response.php135-138

Fluent Modification Methods

Response objects can be modified using fluent methods:

Method	Returns	Description
withStatus(int $status)	static	Sets HTTP status code
asNotFound()	static	Sets HTTP status to 404

Fluent Method Chaining

Sources: src/Access/Response.php117-130

HTTP Status Code Integration

Status Code Purpose

Authorization responses can include HTTP status codes to provide semantic meaning for web responses:

Status Code	Method	Semantic Meaning	Use Case
403	withStatus(403)	Forbidden	User authenticated but lacks permission
404	asNotFound()	Not Found	Hide resource existence for security
401	withStatus(401)	Unauthorized	User not authenticated (rare, handled by authentication)
Custom	withStatus($code)	Application-specific	Custom authorization scenarios

Sources: src/Access/Response.php117-130

Status Code Patterns

HTTP Status Decision Tree

Sources: src/Access/Response.php117-130

Practical Status Code Usage

The choice between 403 and 404 depends on security requirements:

• 403 Forbidden: Use when the user should know the resource exists but lacks permission
• 404 Not Found: Use to hide the resource's existence from unauthorized users (security through obscurity)

Sources: src/Access/Response.php127-130 src/Access/Response.php53-56

Response Conversion Features

Array Conversion

The Response class implements Arrayable for serialization:

toArray() Output Structure

The toArray() method returns:

[
 'allowed' => bool,
 'message' => ?string,
 'code' => int|string|null
]

Note: HTTP status is not included in the array representation.

Sources: src/Access/Response.php143-150

String Conversion

The Response class implements Stringable via __toString(), which returns the message:

(string) $response === $response->message()

This enables responses to be used directly in string contexts.

Sources: src/Access/Response.php155-158

Exception Handling

The authorize() Method

The authorize() method converts denied responses into exceptions:

Response.authorize() Flow

Sources: src/Access/Response.php103-112

AuthorizationException Integration

The AuthorizationException class stores the original response and provides bidirectional conversion:

Direction	Method	Purpose
Response → Exception	authorize()	Throw exception on denial
Exception → Response	toResponse()	Recreate response from exception

Bidirectional Conversion

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

Exception Properties

The AuthorizationException class extends Exception with authorization-specific features:

Property/Method	Type	Description
response	?Response	Original response object
status	?int	HTTP status code
response()	?Response	Get the stored response
setResponse(Response)	static	Set the response (fluent)
withStatus(int)	static	Set HTTP status (fluent)
asNotFound()	static	Set status to 404 (fluent)
hasStatus()	bool	Check if status is set
status()	?int	Get the HTTP status
toResponse()	Response	Convert back to response

Sources: src/Access/AuthorizationException.php14-90

Usage Patterns

Pattern 1: Boolean Inspection

Inspect responses without throwing exceptions:

Boolean Inspection Pattern

Use when:

• Building API responses with detailed authorization info
• Implementing conditional UI elements
• Logging authorization decisions without failing

Sources: src/Access/Response.php69-96

Pattern 2: Exception-Based Authorization

Throw exceptions on denial for immediate error handling:

Exception-Based Pattern

Use when:

• Protecting controller actions
• Implementing fail-fast authorization
• Simplifying control flow (exception handling vs explicit checks)

Sources: src/Access/Response.php103-112

Pattern 3: Custom HTTP Status Responses

Set specific HTTP status codes for web responses:

Status Code Pattern

Use when:

• Hiding resource existence for security
• Providing semantic HTTP responses
• Integrating with web frameworks

Sources: src/Access/Response.php117-130 src/Access/Response.php53-64

Integration with Gate System

Gate Method Return Values

The Gate class methods return different types based on their purpose:

Gate Method	Returns	Throws on Denial	Use Case
check()	bool	No	Simple boolean checks
allows()	bool	No	Alias for check()
denies()	bool	No	Inverse boolean check
inspect()	Response	No	Detailed response inspection
authorize()	void	Yes	Exception-based authorization
any()	bool	No	Check multiple abilities
none()	bool	No	Ensure all abilities denied

Gate Response Flow

Sources: src/Access/Response.php103-112

Response Lifecycle in Authorization

Complete Authorization Flow with Response

Sources: src/Access/Response.php37-112

Best Practices

Choosing Response Messages and Codes

Authorization responses support three levels of information:

Component	Audience	Purpose	Example
Message	Human users	UI display, error messages	"You cannot edit posts by other users"
Code	Application code	Programmatic handling, error classification	"insufficient_permissions"
Status	HTTP clients	Web framework integration, REST semantics	403, 404

Information Hierarchy

Sources: src/Access/Response.php24-28

Response vs Exception Pattern Selection

Scenario	Recommended Pattern	Rationale
Controller action protection	Gate::authorize() (exception)	Fail-fast, simplified control flow
API response building	Gate::inspect() (response)	Need full response details for JSON
Conditional UI rendering	Gate::check() (boolean)	Simple true/false needed
Custom error handling	Gate::inspect() then authorize()	Inspect first, throw if needed
Batch authorization checks	Gate::inspect() multiple (response)	Collect all results, then decide

Sources: src/Access/Response.php69-112

HTTP Status Code Guidelines

Status Code Decision Matrix

User Authenticated	Has Permission	Resource Exists	Recommended Status	Method
Yes	No	Yes	403 Forbidden	deny().withStatus(403)
Yes	No	No/Hidden	404 Not Found	deny().asNotFound()
Yes	No	Want to hide	404 Not Found	deny().asNotFound()
No	N/A	N/A	401 Unauthorized	Handled by auth middleware

Sources: src/Access/Response.php117-130 src/Access/AuthorizationException.php53-66

Exception Safety Patterns

When using exception-based authorization:

1. Always catch AuthorizationException when using authorize() methods unless middleware handles it
2. Check status availability with hasStatus() before accessing status() to avoid null issues
3. Preserve response information by using exception.toResponse() to access original response data
4. Set appropriate status codes early in the response chain for consistent error handling

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

Summary

The Authorization Response system in Hypervel Auth provides a flexible way to represent, communicate, and handle authorization results. Through the Response class and AuthorizationException, the system enables both boolean-based and exception-based handling patterns, with support for messages, codes, and HTTP status integration.