Authenticatable Contract

The Authenticatable interface at src/Contracts/Authenticatable.php defines the contract that user models must implement to participate in authentication. Guards and user providers depend on this interface to retrieve user identifiers and validate credentials.

The package provides the Authenticatable trait at src/Authenticatable.php with default implementations compatible with Hyperf's model conventions.

Related documentation: Authorizable Contract, Guards, User Providers.

Overview

The Authenticatable contract defines three methods:

Method	Return Type	Description
getAuthIdentifierName()	string	Name of the unique identifier field
getAuthIdentifier()	mixed	Value of the unique identifier
getAuthPassword()	string	Hashed password for validation

These methods enable guards and providers to:

• Query users by identifier (src/UserProvider/EloquentUserProvider.php src/UserProvider/DatabaseUserProvider.php)
• Store user identifiers in sessions/tokens (src/Guards/SessionGuard.php src/Guards/JwtGuard.php)
• Validate credentials via password comparison

Sources: src/Contracts/Authenticatable.php1-24 src/Authenticatable.php1-42

Interface Definition

src/Contracts/Authenticatable.php7-23 defines the interface:

Diagram: Authenticatable Interface and Consumers

Sources: src/Contracts/Authenticatable.php1-24

Trait Implementation

src/Authenticatable.php7-41 provides the Authenticatable trait with default implementations:

getAuthIdentifierName()

src/Authenticatable.php12-15 delegates to the model's getKeyName() method:

This returns the model's primary key field name, typically "id".

getAuthIdentifier()

src/Authenticatable.php20-23 retrieves the identifier value dynamically:

Accesses the property returned by getAuthIdentifierName().

getAuthIdentifierForBroadcasting()

src/Authenticatable.php28-31 provides a broadcast-safe identifier:

Not part of the core interface. Used by broadcasting subsystems.

getAuthPassword()

src/Authenticatable.php36-40 returns the password field:

Assumes a password attribute exists. Override for custom password field names.

Sources: src/Authenticatable.php1-42

Model Integration

User models implement the interface and use the trait:

Diagram: User Model Implementation Structure

The trait's default implementations work with Hyperf's model conventions. Models with non-standard structures override specific methods.

Sources: src/Authenticatable.php1-42 src/Contracts/Authenticatable.php1-24

Usage by Guards and Providers

Guards and providers call Authenticatable methods during authentication:

Diagram: Authenticatable Method Calls in Authentication Flow

Provider Usage

EloquentUserProvider at src/UserProvider/EloquentUserProvider.php:

• Calls getAuthIdentifierName() in retrieveById() and retrieveByCredentials()
• Calls getAuthPassword() in validateCredentials() for password comparison
• Returns Authenticatable instances to guards

DatabaseUserProvider at src/UserProvider/DatabaseUserProvider.php:

• Uses getAuthIdentifierName() for table queries
• Uses getAuthPassword() for credential validation
• Returns GenericUser instances implementing Authenticatable

Guard Usage

SessionGuard at src/Guards/SessionGuard.php:

• Calls getAuthIdentifier() in updateSession() to store user ID
• Returns Authenticatable|null from user() method

JwtGuard at src/Guards/JwtGuard.php:

• Calls getAuthIdentifier() when encoding JWT payload
• Returns Authenticatable|null from user() method

Sources: src/Contracts/Authenticatable.php1-24 src/UserProvider/EloquentUserProvider.php src/UserProvider/DatabaseUserProvider.php src/Guards/SessionGuard.php src/Guards/JwtGuard.php

Method Reference

getAuthIdentifierName(): string

Returns the unique identifier field name.

Trait Implementation: src/Authenticatable.php12-15 - Returns getKeyName() result

Typical Return Values: "id", "user_id", "uuid"

Called By:

• EloquentUserProvider::retrieveById() - Constructs database query
• EloquentUserProvider::retrieveByCredentials() - Constructs database query
• DatabaseUserProvider::retrieveById() - Constructs database query
• DatabaseUserProvider::retrieveByCredentials() - Constructs database query

getAuthIdentifier(): mixed

Returns the unique identifier value.

Trait Implementation: src/Authenticatable.php20-23 - Accesses $this->{getAuthIdentifierName()}

Typical Return Values: 123, "550e8400-e29b-41d4-a716-446655440000"

Called By:

• SessionGuard::updateSession() - Stores user ID in session
• JwtGuard - Encodes user ID in JWT payload
• Gate - Identifies user for authorization checks

getAuthPassword(): string

Returns the hashed password.

Trait Implementation: src/Authenticatable.php36-40 - Returns $this->password

Return Value: Hashed password string from hypervel/hashing

Called By:

• EloquentUserProvider::validateCredentials() - Compares with input password
• DatabaseUserProvider::validateCredentials() - Compares with input password

Note: Must return hashed password, not plaintext.

getAuthIdentifierForBroadcasting(): mixed

Returns broadcast-safe identifier.

Trait Implementation: src/Authenticatable.php28-31 - Returns getAuthIdentifier() result

Not Required: Not part of core Authenticatable interface

Used By: Hyperf broadcasting subsystem for private channel authentication

Sources: src/Authenticatable.php1-42 src/Contracts/Authenticatable.php1-24

Customization

Override trait methods for non-standard model structures.

Custom Identifier Field

Override getAuthIdentifierName() for custom primary key names:

Custom Password Field

Override getAuthPassword() for custom password field names:

UUID Primary Keys

No customization needed if UUID field is named id. The trait's getAuthIdentifier() at src/Authenticatable.php20-23 returns the UUID value.

Composite Keys

Override both methods for composite key support:

Sources: src/Authenticatable.php1-42

Contract Relationships

Diagram: Authenticatable Contract Dependencies

Authenticatable is separate from authorization concerns:

Contract	Purpose	Relationship to Authenticatable
Authenticatable	Identity and credentials	Core authentication contract
Authorizable (5.5)	Permission checks	Independent, often co-implemented
Guard (5.2)	Authentication mechanism	Returns Authenticatable instances
UserProvider (5.3)	User retrieval	Returns Authenticatable instances

Models typically implement both Authenticatable and Authorizable for full authentication and authorization support.

Sources: src/Contracts/Authenticatable.php1-24 src/Contracts/Guard.php src/Contracts/StatefulGuard.php src/Contracts/UserProvider.php

Summary

Component	Location	Purpose
Authenticatable Interface	src/Contracts/Authenticatable.php	Defines contract for user models
Authenticatable Trait	src/Authenticatable.php	Provides default implementation
getAuthIdentifierName()	Interface method	Returns identifier field name
getAuthIdentifier()	Interface method	Returns identifier value
getAuthPassword()	Interface method	Returns hashed password
getAuthIdentifierForBroadcasting()	Trait method	Returns broadcast identifier

All user models participating in authentication must implement the Authenticatable interface. The provided trait offers a zero-configuration implementation for standard Hyperf models, while allowing customization for non-standard requirements.

Sources: src/Contracts/Authenticatable.php1-24 src/Authenticatable.php1-42