Password

Password properties are accessed directly as object properties. The pass property is write-only (sets a new password and re-hashes), while salt and hash are readable representations of the stored password data.

Note: The __get() and __set() magic methods that back these properties are tagged #pw-internal. Access the properties directly as shown above — do not call the magic methods.

Setting a password: $password->pass = '...'

Assign a plain-text password string to the pass property. This internally calls the hookable setPass() method, which generates a salt when needed, hashes the password with that salt, and stores the result. If the new password matches the existing stored hash when checked with the existing salt, no change is recorded:

$password = $page->pass;
$password->pass = 'newSecret456';       // hash is computed and stored
$password->pass = 'newSecret456';       // no change — matches existing stored hash

If the property is set to an empty string, the operation is silently ignored and the existing password remains unchanged.

Comparing a password: matches($pass)

Check whether a plain-text password matches the stored hash:

$password = $page->pass;

if($password->matches('attemptedPassword')) {
    echo "Password is correct";
} else {
    echo "Wrong password";
}

matches() hashes the given password with the stored salt and compares the result using hash_equals() (timing-attack-safe comparison) when available, falling back to strict string comparison on older PHP versions.

When the system supports Blowfish but the stored password was hashed with an older algorithm, matches() returns true (if the password matches) and sets a notice message prompting the user to change their password to upgrade to Blowfish hashing.

isBlowfish($str = '')

Check whether a given salt string (or the stored salt, if no argument is passed) uses the Blowfish algorithm. Blowfish salts begin with $2a$, $2x$, or $2y$:

// Check the stored salt
if($password->isBlowfish()) {
    echo "Password uses Blowfish hashing";
}

// Check an arbitrary string
if($password->isBlowfish($someOtherSalt)) {
    // ...
}

supportsBlowfish()

Check whether the current PHP environment supports Blowfish hashing. Returns true when PHP is version 5.3.0 or higher and the CRYPT_BLOWFISH constant is defined:

if($password->supportsBlowfish()) {
    echo "Blowfish is available";
}

On any modern PHP installation 7.0+, this method returns true.

The Password class provides several methods for generating random strings. Most of these methods delegate to a WireRandom instance. Some older methods are retained for backward compatibility but are deprecated in favor of WireRandom methods.

randomPass(array $options = [])

Generate a cryptographically secure random password. Delegates to WireRandom::pass(). Options control length, character sets, and other parameters:

// Generate a 16-character random password
$pass = $password->randomPass(['length' => 16]);

// Use only letters and digits (default includes symbols)
$pass = $password->randomPass(['length' => 12, 'alnum' => true]);

See WireRandom for the full list of options.

randomBase64String($requiredLength = 22, $options = [])

Generate a cryptographically secure random base64 string of a specified length. Delegates to WireRandom::base64():

// Generate a 44-character base64 string for a custom salt
$base64 = $password->randomBase64String(44);

For fast (non-cryptographic) generation, pass the fast option:

$base64 = $password->randomBase64String(22, ['fast' => true]);

See WireRandom for all options.

Deprecated random methods

The following methods are retained for backward compatibility but are deprecated. Use the corresponding methods on WireRandom instead:

// Deprecated usage — prefer wire('random')->alpha(10) instead
$letters = $password->randomLetters(10);  // still works, but deprecated

Password::setPass($value)

Called when a new password is assigned via $password->pass = '...'. Receives the plain-text password string and generates the salt and hash.

/**
 * Hook before a password is hashed.
 *
 * @param HookEvent $event
 */
$wire->addHookBefore('Password::setPass', function(HookEvent $event) {
    $password = $event->object;  /** @var Password $password */
    $pass = $event->arguments(0); // plain-text password string

    // Enforce a minimum password length
    if(strlen($pass) < 8) {
        $event->replace = true;
        throw new WireException('Password must be at least 8 characters');
    }
});

You can also hook after to react to password changes:

$wire->addHookAfter('Password::setPass', function(HookEvent $event) {
    $password = $event->object;
    // $password->salt and $password->hash now contain the new values
    wire('log')->save('passwords', "Password updated for user");
});

When cast to a string, a Password object returns the stored hash:

echo (string) $password;       // outputs the hash string
echo $password->__toString();  // equivalent

The __toString() method is useful when you need the raw hash for debugging or logging, but it should never be exposed to users or transmitted.

• Source file: wire/core/Tools/Password/Password.php
• Extends: Wire — inherits hook support and Wire instance access via $this->wire()
• Used by: FieldtypePassword, InputfieldPassword, Session::login(), $users authentication
• Salt format: When using Blowfish, the salt is 29 characters with the format $2y$11$<22-base64-chars>$. The cost parameter (11 in the example) controls the hashing complexity. Older installations may use $2a$ or $2x$ prefixes instead of $2y$.
• Hash algorithm: When Blowfish is not available, the hash type is determined by $config->userAuthHashType (e.g. sha256). If neither Blowfish nor a configured hash type is available, the system falls back to MD5 for backward compatibility with very old installations.
• Change tracking: Password extends Wire and supports change tracking. After setting a new password, $password->isChanged('pass') returns true until resetTrackChanges() is called. This is used by FieldtypePassword::sanitizeValue() to mark the parent page's field as changed.
• Security: matches() uses hash_equals() (when available) for timing-attack-safe string comparison.
• Related classes: FieldtypePassword, InputfieldPassword, WireRandom, User, Session