0 follower

Final Class Yiisoft\Security\PasswordHasher

All Classes | Methods | Constants
InheritanceYiisoft\Security\PasswordHasher

PasswordHasher allows generating password hash and verifying passwords against a hash.

Public Methods

Hide inherited methods

Method Description Defined By
__construct() Yiisoft\Security\PasswordHasher
hash() Generates a secure hash from a password and a random salt. Yiisoft\Security\PasswordHasher
needsRehash() Verifies if a hash needs rehash. Yiisoft\Security\PasswordHasher
validate() Verifies a password against a hash. Yiisoft\Security\PasswordHasher

Constants

Hide inherited constants

Constant Value Description Defined By
SAFE_PARAMETERS [ \PASSWORD_BCRYPT => [ 'cost' => 13, ], ] Yiisoft\Security\PasswordHasher

Method Details

Hide inherited methods

__construct() public method

See also https://www.php.net/manual/en/function.password-hash.php.

public __construct( string|null $algorithm = PASSWORD_DEFAULT, array|null $parameters = null ): mixed
$algorithm string|null

Algorithm to use. If not specified, PHP chooses safest algorithm available in the current version of PHP.
$parameters array|null

Algorithm parameters. If not specified, safe defaults are used.

 

                public function __construct(
    private readonly string|null $algorithm = PASSWORD_DEFAULT,
    array|null $parameters = null,
) {
    if ($parameters === null) {
        $this->parameters = self::SAFE_PARAMETERS[$this->algorithm] ?? [];
    } else {
        $this->parameters = $parameters;
    }
}
hash() public method

Generates a secure hash from a password and a random salt.

The generated hash can be stored in database. Later when a password needs to be validated, the hash can be fetched and passed to validate(). For example,

// generates the hash (usually done during user registration or when the password is changed)
$hash = (new PasswordHasher())->hash($password);
// ...save $hash in database...

// during login, validate if the password entered is correct using $hash fetched from database
if ((new PasswordHasher())->validate($password, $hash)) {
    // password is good
} else {
    // password is bad
}

See also validate().

public hash( string $password ): string
$password string

The password to be hashed.
return string

The password hash string. The output length might increase in future versions of PHP (https://php.net/manual/en/function.password-hash.php)

 

                public function hash(
    #[SensitiveParameter]
    string $password
): string {
    return password_hash($password, $this->algorithm, $this->parameters);
}
needsRehash() public method

Verifies if a hash needs rehash.

See also https://www.php.net/manual/function.password-needs-rehash.php.

public needsRehash( string $hash ): boolean
$hash string

The hash to verify.
return boolean

Whether rehash is needed.

 

                public function needsRehash(
    #[SensitiveParameter]
    string $hash
): bool {
    return password_needs_rehash($hash, $this->algorithm, $this->parameters);
}
validate() public method

Verifies a password against a hash.

See also hash().

public validate( string $password, string $hash ): boolean
$password string

The password to verify.
$hash string

The hash to verify the password against.
return boolean

Whether the password is correct.
throws InvalidArgumentException

on bad password/hash parameters or if crypt() with Blowfish hash is not available.

 

                public function validate(
    #[SensitiveParameter]
    string $password,
    #[SensitiveParameter]
    string $hash
): bool {
    if ($password === '') {
        throw new InvalidArgumentException('Password must be a string and cannot be empty.');
    }
    return password_verify($password, $hash);
}