Configuration

Purpose and Scope

This document explains the configuration system for the hypervel/auth package, focusing on the auth.php configuration file structure and how it controls authentication and authorization behavior. It covers the configuration sections (defaults, guards, providers), the publishing process, and how configuration values drive service resolution at runtime.

For information about installing the package and initial setup steps, see Getting Started. For details on how guards and providers are implemented, see Guards and User Providers respectively.

---

Configuration File Overview

The authentication system is configured through a single configuration file that gets published to your application. The ConfigProvider class defines the publishing configuration at src/ConfigProvider.php24-30 specifying that the source template publish/auth.php1-30 should be copied to config/autoload/auth.php in your application.

Sources: src/ConfigProvider.php24-30 publish/auth.php1-30

---

Configuration Structure

The configuration file returns a PHP array with three main sections:

Section	Purpose	Required
defaults	Specifies which guard and provider to use when none is explicitly requested	Yes
guards	Defines available authentication guards and their configurations	Yes
providers	Defines available user providers and their configurations	Yes

---

Defaults Section

The defaults section at publish/auth.php6-9 specifies which guard and provider the AuthManager should use when no specific guard is requested.

Configuration Keys:

• guard: The name of the default guard (must exist in the guards array). In the default configuration, this is set to 'jwt' at publish/auth.php7
• provider: The name of the default provider (must exist in the providers array). In the default configuration, this is set to 'users' at publish/auth.php8

When AuthManager::guard() is called without arguments, it uses defaults.guard to determine which guard to instantiate.

Sources: publish/auth.php6-9

---

Guards Section

The guards section at publish/auth.php10-23 defines the available authentication guards. Each guard configuration specifies a driver type and which user provider it should use.

Guard Configuration Structure

Each guard entry is a named array with the following keys:

Key	Description	Required
driver	The guard driver type (session, jwt, request, or custom)	Yes
provider	The name of the provider this guard uses (must exist in providers array)	Yes

Default Guard Configurations

The default configuration provides three pre-configured guards at publish/auth.php11-22:

Guard Drivers:

• session: Uses SessionGuard for stateful, cookie-based authentication. See SessionGuard for implementation details.
• jwt: Uses JwtGuard for stateless, token-based authentication. See JwtGuard for implementation details.
• request: Uses RequestGuard for callback-based custom authentication. See RequestGuard for implementation details.
• sanctum: A custom guard type (implementation not shown in provided files).

Adding Custom Guards

You can add custom guard configurations by adding new entries to the guards array:

Sources: publish/auth.php10-23

---

Providers Section

The providers section at publish/auth.php24-29 defines the available user providers. Each provider configuration specifies how to retrieve user data from persistent storage.

Provider Configuration Structure

Each provider entry is a named array with keys that vary by driver type:

Key	Description	Required
driver	The provider driver type (eloquent, database, or custom)	Yes
model	The fully-qualified user model class (for eloquent driver)	If driver is eloquent
table	The database table name (for database driver)	If driver is database

Default Provider Configuration

The default configuration provides one provider at publish/auth.php25-28:

Provider Drivers:

• eloquent: Uses EloquentUserProvider to retrieve users via Eloquent ORM. Requires model key specifying the user model class. See EloquentUserProvider for implementation details.
• database: Uses DatabaseUserProvider to retrieve users via query builder without ORM. Requires table key specifying the database table name. See DatabaseUserProvider for implementation details.

Adding Custom Providers

You can add additional provider configurations:

Sources: publish/auth.php24-29

---

Configuration Publishing Process

The ConfigProvider class at src/ConfigProvider.php13-34 handles configuration publishing during package setup. The __invoke() method returns an array containing both service bindings and publish configurations.

The publish configuration at src/ConfigProvider.php24-30 defines:

• id: Identifier for this publish configuration ('config')
• description: Human-readable description ('The config for auth.')
• source: Source file path in the package (__DIR__ . '/../publish/auth.php')
• destination: Destination path in the application (BASE_PATH . '/config/autoload/auth.php')

Users trigger the publishing process using Hyperf's vendor:publish command, which copies the template configuration to their application where it can be customized.

Sources: src/ConfigProvider.php24-30

---

Service Registration

The ConfigProvider also registers service bindings that use the configuration values at runtime. The dependency injection bindings are defined at src/ConfigProvider.php18-23

Key Bindings:

Contract	Implementation	Purpose
AuthFactoryContract	AuthManager	Factory for creating guards based on configuration
Authenticatable	UserResolver	Resolves the currently authenticated user
Guard	Closure returning default guard	Provides the default guard instance
GateContract	GateFactory	Creates the authorization gate

The AuthManager reads the configuration file to determine which guard drivers to instantiate and which providers each guard should use. See AuthManager for detailed information on how guards are resolved from configuration.

Sources: src/ConfigProvider.php18-23

---

Configuration Flow at Runtime

When the authentication system is used at runtime, the configuration values control which components are instantiated and how they interact.

Configuration Resolution Steps:

1. Application requests a Guard from the container
2. Container resolves AuthFactoryContract to AuthManager
3. AuthManager::guard() is called with no arguments
4. AuthManager reads defaults.guard to get the default guard name
5. AuthManager reads guards[{name}] to get the guard configuration
6. AuthManager reads providers[{name}] to get the provider configuration
7. AuthManager instantiates the provider based on its driver
8. AuthManager instantiates the guard with the provider
9. Guard instance is returned to the application

Sources: src/ConfigProvider.php18-23 publish/auth.php1-30

---

Configuration Examples

API-Only Application

For applications that only use JWT authentication:

Multi-Tenant Application

For applications with separate user types:

Database-Only Provider

For applications that don't use Eloquent:

Sources: publish/auth.php1-30