DatabaseUserProvider

Purpose and Scope

The DatabaseUserProvider class provides a lightweight, database query builder-based implementation of user data retrieval for the authentication system. This provider uses Hyperf's ConnectionInterface directly to execute raw SQL queries, bypassing the ORM layer entirely. It returns GenericUser objects instead of Eloquent models, making it significantly more lightweight than EloquentUserProvider (see page 2.4.1).

Key Characteristics:

Feature	DatabaseUserProvider	EloquentUserProvider
Data Layer	Raw Database Queries	Eloquent ORM
User Objects	GenericUser (plain arrays)	Eloquent Models
Overhead	Minimal	Higher (model hydration, events)
Features	Basic authentication only	Relationships, mutators, events
Use Case	Legacy schemas, performance-critical	Feature-rich applications

This provider is ideal for:

• Legacy database schemas that don't map cleanly to ORM models
• Performance-critical authentication flows where ORM overhead is undesirable
• Simple authentication requirements without complex user relationships
• Systems that need direct control over SQL query generation

For broader context on user providers, see page 2.4.

Sources: src/Providers/DatabaseUserProvider.php1-98 src/GenericUser.php1-90

Class Overview and Dependencies

The DatabaseUserProvider implements the UserProvider contract and requires three key dependencies injected through its constructor:

Dependency	Type	Purpose
$connection	ConnectionInterface	Database connection for query execution
$hasher	HashContract	Password hashing and verification
$table	string	Database table name containing user records

Constructor and Dependency Injection

Sources: src/Providers/DatabaseUserProvider.php15-22

User Retrieval by Identifier

The retrieveById method provides the simplest user lookup mechanism, retrieving a user by their primary key identifier. The implementation uses the database connection's find method for direct primary key lookup.

The method delegates the actual user object creation to the protected getGenericUser method, which handles the conversion of raw database results into GenericUser instances.

Sources: src/Providers/DatabaseUserProvider.php24-34

Credential-Based User Retrieval

The retrieveByCredentials method implements flexible user lookup based on arbitrary credential arrays. This method includes sophisticated query building logic to handle different credential types and structures.

Credential Filtering Process

The method first filters out password-related fields from the credentials array to prevent them from being used in database queries:

Dynamic Query Building

The query building logic handles three distinct credential value types:

Value Type	Query Method	Purpose
Array or Arrayable	whereIn(key, value)	Multiple possible values
Closure	value(query)	Custom query logic
Scalar	where(key, value)	Exact match

Sources: src/Providers/DatabaseUserProvider.php36-72

GenericUser Objects

The DatabaseUserProvider returns GenericUser instances rather than Eloquent models. The GenericUser class is a lightweight implementation of the Authenticatable contract that wraps a simple array of user attributes.

GenericUser Architecture:

Key Implementation Details:

Method	Behavior	Source
getAuthIdentifierName()	Always returns "id" (hardcoded)	src/GenericUser.php27-30
getAuthIdentifier()	Returns $attributes['id']	src/GenericUser.php35-38
getAuthPassword()	Returns $attributes['password']	src/GenericUser.php43-46
__get()	Direct array access via magic method	src/GenericUser.php54-57
__set()	Direct array assignment via magic method	src/GenericUser.php65-68

Object Creation Flow:

The getGenericUser method creates GenericUser instances from raw database query results:

The method casts database results to arrays before instantiation, ensuring compatibility with different database result object formats (stdClass, etc.).

Attribute Access:

GenericUser provides dynamic attribute access through PHP magic methods, making it behave similar to objects:

Limitations:

Unlike Eloquent models, GenericUser objects:

• Do not support relationships
• Do not trigger model events
• Do not have mutators/accessors
• Do not provide dirty tracking
• Are not database-persistent (read-only from authentication perspective)

Sources: src/GenericUser.php1-90 src/Providers/DatabaseUserProvider.php74-86

Password Validation

The validateCredentials method implements password verification by delegating to the injected hasher implementation. This method follows the standard authentication pattern of comparing a plain-text password against a stored hash.

The method extracts the password from the credentials array and compares it against the user's stored password hash using the configured hashing algorithm.

Sources: src/Providers/DatabaseUserProvider.php88-97

Integration with Authentication System

The DatabaseUserProvider integrates with the broader authentication system through the UserProvider contract, enabling it to work with any authentication guard that requires user data retrieval.

Configuration and Instantiation

The provider is typically configured in the authentication configuration file and instantiated through the authentication manager's factory pattern. The manager provides the required dependencies based on the application's dependency injection container.

Sources: src/Providers/DatabaseUserProvider.php1-98