Documentation

Password
in package

Password hashing on PHP's native Argon2id (at PHP's default cost), the public entry point for the framework's password handling. A `password_scheme` marker lets legacy and onion-wrapped hashes coexist and self-heal to native on login.

  • native: password is a password_hash() string; salt is null.
  • legacy: password is the SHA-512 hex; salt is the per-row salt.
  • onion : password is a native hash of the SHA-512 hex; salt is kept.
  • wordpress: password is a WordPress $P$ or $wp$ string; salt is null.

Table of Contents

LEGACY  = "legacy"
MAX_LENGTH_BYTES  = 1024
MIN_LENGTH_BYTES  = 3
NATIVE  = "native"
ONION  = "onion"
WORDPRESS  = "wordpress"
ONION_OPTS  = ["memory_cost" => 12288, "time_cost" => 1, "threads" => 1]
Reduced cost for the onion layer only. An un-peeled onion row is verified up to 26 times (the legacy a-z "pepper" was never stored), so the default cost would make one login multi-second and a DoS vector. Still far stronger than the bare SHA-512 it wraps, and peeled to the default on the next login.
hash()  : string
Create a native hash from a plaintext password.
verify()  : Verification
Verify a plaintext against a stored credential. `scheme` selects how to read the stored value (defaults to native); `salt` is only needed for legacy/onion rows.
verifyLegacy()  : Verification
Legacy or onion (the shim detects which); any match self-heals to native.
verifyNative()  : Verification
Native Argon2id: matches, and self-heals when below the current cost.
verifyWordPress()  : Verification
WordPress import, `$wp$` (6.8+) or `$P$` (phpass); the shims pick by prefix. Any match self-heals to native.

Constants

MAX_LENGTH_BYTES

public mixed MAX_LENGTH_BYTES = 1024

MIN_LENGTH_BYTES

public mixed MIN_LENGTH_BYTES = 3

WORDPRESS

public mixed WORDPRESS = "wordpress"

ONION_OPTS

Reduced cost for the onion layer only. An un-peeled onion row is verified up to 26 times (the legacy a-z "pepper" was never stored), so the default cost would make one login multi-second and a DoS vector. Still far stronger than the bare SHA-512 it wraps, and peeled to the default on the next login.

private mixed ONION_OPTS = ["memory_cost" => 12288, "time_cost" => 1, "threads" => 1]

Methods

hash()

Create a native hash from a plaintext password.

public static hash(string $password) : string
Parameters
$password : string
Tags
throws
InvalidArgumentException

when the password is shorter than 3 or longer than 1024 bytes.

Return values
string —

verify()

Verify a plaintext against a stored credential. `scheme` selects how to read the stored value (defaults to native); `salt` is only needed for legacy/onion rows.

public static verify(string $password, string $stored[, string|null $scheme = self::NATIVE ][, string|null $salt = null ]) : Verification
Parameters
$password : string

Plaintext; outside MIN/MAX_LENGTH_BYTES counts as wrong, never truncated.

$stored : string

The stored credential; empty counts as wrong.

$scheme : string|null = self::NATIVE

One of the scheme constants; an explicit null or unknown value counts as wrong.

$salt : string|null = null

The per-row salt; required for legacy/onion, ignored otherwise.

Tags
throws
InvalidArgumentException

when the scheme is legacy/onion and the salt is empty.

Return values
Verification —

Never a bool; read it via isCorrect().

verifyLegacy()

Legacy or onion (the shim detects which); any match self-heals to native.

private static verifyLegacy(string $password, string $salt, string $stored) : Verification
Parameters
$password : string
$salt : string
$stored : string
Return values
Verification —

verifyNative()

Native Argon2id: matches, and self-heals when below the current cost.

private static verifyNative(string $password, string $stored) : Verification
Parameters
$password : string
$stored : string
Return values
Verification —

verifyWordPress()

WordPress import, `$wp$` (6.8+) or `$P$` (phpass); the shims pick by prefix. Any match self-heals to native.

private static verifyWordPress(string $password, string $stored) : Verification
Parameters
$password : string
$stored : string
Return values
Verification —

Search results