Overview

The hypervel/auth package provides authentication and authorization for Hyperf applications. It implements a flexible guard-based authentication system and a gate-based authorization system that are cleanly separated but work together in the HTTP request pipeline.

For detailed setup instructions, see Getting Started. For configuration options, see Configuration. For deep dives into specific subsystems, see Authentication System and Authorization System.

Purpose and Scope

The hypervel/auth package provides two independent security subsystems:

Subsystem	Purpose	Key Question
Authentication	Verifies user identity	"Who are you?"
Authorization	Controls access to resources	"What can you do?"

Authentication

The authentication subsystem verifies user identity through multiple guard implementations:

• SessionGuard (src/SessionGuard.php): Stateful session-based authentication for web applications
• JwtGuard (src/JwtGuard.php): Stateless JWT token-based authentication for APIs
• RequestGuard (src/RequestGuard.php): Callback-based custom authentication logic

Each guard retrieves user data through user providers (src/EloquentUserProvider.php src/DatabaseUserProvider.php) and caches authenticated users in Hyperf's request context.

Authorization

The authorization subsystem controls resource access through the Gate class (src/Access/Gate.php):

• Abilities: Simple callback functions for permission checks
• Policies: Class-based authorization logic for models
• Before/After Callbacks: Global hooks for intercepting authorization checks

Sources: composer.json1-58 README.md1-4 src/ConfigProvider.php1-34

Architectural Philosophy

The package follows several key architectural principles:

1. Separation of Concerns: Authentication and authorization are completely independent systems. Authentication establishes identity once per request, while authorization evaluates permissions multiple times as needed.

2. Factory Pattern: The AuthManager (src/AuthManager.php) acts as a factory for creating guard instances based on configuration, enabling runtime guard selection.

3. Provider Abstraction: User data retrieval is abstracted through the UserProvider contract (src/Contracts/UserProvider.php), allowing seamless switching between Eloquent ORM, raw database queries, or custom implementations.

4. Context Caching: Guards cache authenticated users in Hyperf's request context (hyperf/context), preventing redundant database queries within a single request.

5. Middleware Integration: Both authentication and authorization integrate as HTTP middleware, failing fast with appropriate exceptions before reaching application logic.

Sources: src/AuthManager.php src/Contracts/UserProvider.php src/ConfigProvider.php18-23

Package Structure

The package is organized into distinct subsystems. The following diagram maps system components to their concrete implementations:

Package Component Architecture

Sources: src/ConfigProvider.php1-34 composer.json38-44

Core Subsystems

Authentication Subsystem

The authentication subsystem verifies user identity through a flexible guard system. The AuthManager src/AuthManager.php acts as a factory that creates and manages guard instances. Three guard types are provided:

Guard Type	Implementation	Use Case
SessionGuard	src/SessionGuard.php	Traditional web applications with stateful sessions
JwtGuard	src/JwtGuard.php	API authentication with stateless JWT tokens
RequestGuard	src/RequestGuard.php	Custom authentication logic via callbacks

Guards retrieve user data through user providers, which abstract the data source (Eloquent ORM or direct database queries). The Authenticate middleware src/Middleware/Authenticate.php enforces authentication requirements at the HTTP layer.

For detailed information, see Authentication.

Authorization Subsystem

The authorization subsystem controls access to resources through the Gate class (src/Access/Gate.php). Authorization checks can be defined as:

• Abilities: Simple callback functions registered with the gate
• Policies: Class-based authorization logic for specific models
• Before/After Callbacks: Global hooks for intercepting or auditing authorization checks

The Authorize middleware (src/Middleware/Authorize.php) enforces authorization policies on routes. Authorization failures throw an AuthorizationException (src/Access/AuthorizationException.php) resulting in HTTP 403 Forbidden responses.

For detailed information, see Authorization System.

Sources: src/Access/Gate.php src/Middleware/Authorize.php src/Access/AuthorizationException.php

Integration with Hyperf Framework

The package integrates with the Hyperf framework through dependency injection and service registration. The ConfigProvider class (src/ConfigProvider.php13-34) registers the following service bindings during application bootstrap:

Contract	Implementation	Purpose
Factory	AuthManager (src/AuthManager.php)	Guard factory and management
Authenticatable	UserResolver (src/UserResolver.php12-16)	Resolves currently authenticated user
Guard	Factory-resolved guard	Current guard instance
Gate	GateFactory (src/Access/GateFactory.php)	Authorization engine

Hyperf Framework Integration

The package publishes a default configuration file to config/autoload/auth.php (src/ConfigProvider.php24-30) that defines available guards, user providers, and default settings.

Sources: src/ConfigProvider.php1-34 composer.json25-31

External Dependencies

The package relies on several external dependencies for specific functionality:

Required Dependencies

Package	Version	Purpose
hyperf/context	~3.1.0	Request-scoped data storage and caching
hyperf/database	~3.1.0	Database query builder and ORM (Eloquent)
hyperf/http-server	~3.1.0	HTTP middleware and request handling
hyperf/contract	~3.1.0	Framework interface contracts
hyperf/config	~3.1.0	Configuration management
hypervel/hashing	^0.3	Password hashing and verification
hypervel/jwt	^0.3	JWT token generation, parsing, and validation

Optional Dependencies

Package	Version	Purpose
hypervel/session	~0.1.0	Required for SessionGuard functionality

Dependency Architecture

Sources: composer.json22-37

Helper Functions

The package provides a global auth() helper function that returns the authentication manager instance. This function is auto-loaded via src/Functions.php (composer.json42-44) and provides convenient access to authentication services throughout the application.

For detailed information about helper functions, see Helper Functions and Utilities.

Sources: composer.json38-44 src/Functions.php

Configuration and Bootstrap Flow

The following diagram illustrates how the package is configured and initialized:

Configuration and Bootstrap Sequence

Sources: src/ConfigProvider.php1-34

Request Processing Flow

Authentication and authorization work together in the HTTP request pipeline:

Phase	Component	Action	Result on Failure
1. Authentication	Authenticate middleware (src/Middleware/Authenticate.php)	Verifies user identity via guard	HTTP 401 or redirect
2. Authorization	Authorize middleware (src/Middleware/Authorize.php)	Checks permissions via gate	HTTP 403 or 404
3. Controller	Application logic	Processes authorized request	N/A

This two-phase approach ensures clean separation of concerns: authentication answers "who are you?" while authorization answers "what can you do?"

Request Pipeline Integration

For detailed flow diagrams, see System Architecture.

Sources: src/Middleware/Authenticate.php src/Middleware/Authorize.php

Next Steps

To get started with the package:

1. Installation and Setup: See Getting Started for package installation and initial configuration
2. Configuration: See Configuration for detailed explanation of the auth.php configuration file
3. Authentication: See Authentication for implementing user login, logout, and identity verification
4. Authorization: See Authorization for implementing access control with gates and policies
5. Middleware: See Middleware for protecting routes with authentication and authorization requirements

Sources: composer.json1-58 src/ConfigProvider.php1-34