Example and documentation cleanups

[Firehed]

A few small correctness and consistency problems in the example code and documentation. None affect the library itself, but the examples are meant to be copied into real integrations.

examples/functions.php — uuidv4() is not a conformant UUIDv4

$chunks[3] = '4' . substr($chunks[3], 1);

This sets the version nibble but never the variant bits: the first hex digit of $chunks[4] must be 8, 9, a or b (RFC 9562 §5.4). The value works fine as an opaque user id, so nothing is broken, but it does not match its name and would fail UUID validation elsewhere.

README and examples disagree on the credential schema

The README uses table credentials with column storage_id:

$pdo->prepare('INSERT INTO credentials (storage_id, user_id, credential) VALUES (:storage_id, :user_id, :encoded);');

The examples use table user_credentials with column id:

$pdo->prepare('INSERT INTO user_credentials (id, user_id, credential) VALUES (:id, :user_id, :encoded);');

Each is internally consistent, so both work as written. Copying between them does not.

Unchecked writes in the example step-3 scripts

readmeRegisterStep3.php and readmeLoginStep3.php both assign $result = $stmt->execute([...]) and never inspect it, then unconditionally return success. For the login example this means a failed sign-counter update is invisible.

Unguarded session read

readmeLoginStep3.php:24 reads $_SESSION['authenticating_user_id'] with no presence check; reaching step 3 without step 1 is an undefined-key warning rather than a clean error.

PHPDoc parse error

src/ChallengeLoaderInterface.php has @api: (with the above caveats), which is not valid PHPDoc. It currently sits in phpstan-baseline.neon:

'#^PHPDoc tag @api has invalid value \(\(with the above caveats\)\)\: Unexpected token "the", expected ''\)'' at offset 518 on line 11$#'

Moving the caveat text into the description body and leaving @api bare would clear the baseline entry.

---

This issue body was written by AI. The underlying findings were reviewed by a human.