Hasher Interface

Purpose and Scope

The Hasher interface defines the contract that all password hashing implementations in the Hypervel/Hashing library must follow. It establishes a consistent API for creating password hashes, verifying passwords against hashes, retrieving hash metadata, and determining when hashes should be regenerated.

This document covers the interface contract itself. For information about:

• The base implementation of this interface, see Abstract Base Classes
• How the interface is used in the factory pattern, see Hash Manager
• Specific algorithm implementations, see Hashing Algorithms

Sources: src/Contracts/Hasher.php1-29

Interface Definition

The Hasher interface is located in the Hypervel\Hashing\Contracts namespace and consists of four method signatures that form the complete hashing API.

Method Summary

Method	Purpose	Parameters	Return Type
info()	Retrieve metadata about a hashed value	string $hashedValue	array
make()	Generate a password hash	string $value, array $options = []	string
check()	Verify a password against a hash	string $value, ?string $hashedValue, array $options = []	bool
needsRehash()	Determine if a hash needs regeneration	string $hashedValue, array $options = []	bool

Sources: src/Contracts/Hasher.php7-28

Method Specifications

info()

Retrieves information about the given hashed value, including the algorithm used and algorithm-specific parameters.

Parameters:

• $hashedValue (string): A previously generated password hash

Returns: An associative array containing:

• algo: The algorithm identifier (e.g., PASSWORD_BCRYPT, PASSWORD_ARGON2I)
• algoName: Human-readable algorithm name
• Algorithm-specific options (e.g., cost for Bcrypt, memory_cost for Argon2)

This method wraps PHP's password_get_info() function and is typically used for debugging or auditing purposes to inspect hash properties without needing the original password.

Sources: src/Contracts/Hasher.php10-12

make()

Creates a secure hash from a plain-text password string.

Parameters:

• $value (string): The plain-text password to hash
• $options (array, optional): Algorithm-specific configuration overrides
  • For Bcrypt: ['rounds' => 12]
  • For Argon2: ['memory' => 65536, 'time' => 4, 'threads' => 1]

Returns: A string containing the hashed password, including algorithm identifier and parameters encoded in the hash itself.

This is the primary method for creating new password hashes. The $options parameter allows per-operation customization of hashing parameters, overriding the defaults configured for the hasher instance.

Sources: src/Contracts/Hasher.php14-17

check()

Verifies that a plain-text password matches a previously generated hash.

Parameters:

• $value (string): The plain-text password to verify
• $hashedValue (string|null): The hash to verify against; null values return false
• $options (array, optional): Algorithm-specific verification options (rarely used)

Returns: true if the password matches the hash, false otherwise.

This method uses timing-safe comparison internally to prevent timing attacks. It correctly handles null hashed values by returning false, which is useful in scenarios where a user might not have a password set.

Sources: src/Contracts/Hasher.php19-22

needsRehash()

Determines if a hash was created with parameters that differ from the current configuration and should be regenerated.

Parameters:

• $hashedValue (string): The hash to evaluate
• $options (array, optional): The current target parameters to compare against

Returns: true if the hash should be regenerated, false if it's still valid.

This method enables automatic password hash upgrades. When security requirements change (e.g., increasing Bcrypt rounds from 10 to 12), this method identifies which hashes need regeneration. Typically called after successful login verification.

Sources: src/Contracts/Hasher.php24-27

Architectural Role

Strategy Pattern Implementation

The Hasher interface serves as the Strategy in the Strategy pattern, allowing the system to switch between different hashing algorithms transparently.

Sources: src/Contracts/Hasher.php1-29

Interface Contract Guarantees

The Hasher interface provides the following guarantees to consumers:

1. Algorithm Agnosticism: Client code can work with any hashing algorithm without knowing implementation details
2. Consistent API: All four methods are available on every implementation
3. Type Safety: Parameter and return types are enforced by PHP's type system
4. Null Safety: The check() method explicitly handles nullable hash values
5. Options Flexibility: All methods accept optional configuration arrays for runtime customization

Implementation Hierarchy

Sources: src/Contracts/Hasher.php1-29

Usage in Runtime

The following diagram illustrates how the interface methods are invoked during typical password operations:

Sources: src/Contracts/Hasher.php1-29

Design Principles

Separation of Concerns

The interface cleanly separates four distinct concerns in password hashing:

Concern	Method	Responsibility
Hash Creation	make()	Generate new hashes with current parameters
Hash Verification	check()	Validate passwords against existing hashes
Hash Inspection	info()	Extract metadata from hash strings
Hash Maintenance	needsRehash()	Identify outdated hashes requiring upgrade

Extensibility

The interface design enables extensibility in multiple dimensions:

1. New Algorithms: Additional hashing algorithms can be added by implementing the four methods
2. Parameter Overrides: The $options parameter allows runtime customization without changing method signatures
3. Backward Compatibility: Existing hashes continue to work even when default parameters change

Framework Integration

The interface serves as the injection point for Hyperf's dependency injection container:

When application code requests Hasher::class from the container, it receives a HashManager instance that implements the Hasher interface and delegates to the configured driver.

Sources: src/Contracts/Hasher.php1-29

Interface vs. Implementation

The interface defines what operations are available, while implementations define how they are performed:

Aspect	Interface	Implementation
Location	src/Contracts/Hasher.php	src/BcryptHasher.php, etc.
Concern	Method signatures and contracts	Algorithm-specific logic
Dependencies	None	PHP password functions, configuration
Instantiation	Cannot be instantiated	Created by HashManager factory
Coupling	Client code depends on interface	Interface does not depend on implementations

This separation enables the Dependency Inversion Principle: high-level authentication code depends on the abstract Hasher interface, not on concrete implementations like BcryptHasher.

Sources: src/Contracts/Hasher.php1-29