Download the PHP package st-all-one/blake3 without Composer

BLAKE3 for PHP

Pure PHP 8.4 implementation of BLAKE3: fast, deterministic, framework-agnostic, and dependency-free at runtime.

• blake3_hash(string $data, int $length = 32, bool $rawOutput = false): string
• keyed hashing and key derivation
• arbitrary-length output (XOF)
• incremental hashing with Hasher::update() / Hasher::finalize()
• no extensions required; ext-blake3 is optional and never required
• verified against the official BLAKE3 test vectors on glibc and musl

Requirements

• PHP 8.4 or newer
• 64-bit PHP (php-64bit)
• no framework, no service container, no PSR dependency

Installation

The package is a library and exposes:

Import the function explicitly; there is no global blake3_hash to avoid a fatal redeclaration when ext-blake3 is loaded:

API

blake3_hash(string $data, int $length = 32, bool $rawOutput = false): string

Hashes $data. $length is the number of output bytes and must be at least 1. Returns lowercase hexadecimal by default, or raw bytes when $rawOutput is true.

blake3_keyed_hash(string $key, string $data, int $length = 32, bool $rawOutput = false): string

Keyed BLAKE3. $key must be exactly 32 bytes. Use it for MAC/PRF-style constructions where both sides share a secret key.

blake3_derive_key(string $context, string $keyMaterial, int $length = 32, bool $rawOutput = false): string

Derives key material from a globally unique, application-specific $context and the input $keyMaterial. Different contexts derive independent keys.

Hasher

finalize() does not mutate the hasher. It can be called repeatedly, and update() may continue afterwards; the result is the hash of all bytes fed so far.

Invalid key length throws InvalidArgumentException; an output length below 1 throws ValueError.

Security notes

• BLAKE3 is a general-purpose cryptographic hash, not a password hash. Use password_hash() with Argon2id for passwords.
• Keyed hashing is a PRF/MAC-style construction; keep the 32-byte key secret.
• Derivation contexts must be globally unique and application-specific. Changing the context changes the derived key.
• Compare hashes with hash_equals() when the comparison is security-sensitive.
• Keyed keys and derive-key material are marked #[\SensitiveParameter]; exception traces redact them instead of exposing key bytes.
• This is a pure PHP implementation. For very high-throughput hot paths, measure the native ext-blake3 extension and prefer it when available.

Testing and quality gates

Everything runs inside the two pinned images:

The test suite covers all 35 official vectors in the three modes (hash, keyed, derive) at 131-byte XOF, plus chunk/block boundaries, streaming splits, XOF prefixes, error paths, and state reuse.

Releasing

Releases are tag-driven and use .github/workflows/release.yml.

1. Commit and merge the release changes to main, then confirm make check is green.
2. Update CHANGELOG.md so the first version heading is exactly ## [X.Y.Z] - YYYY-MM-DD.
3. Create and push an annotated tag:

The workflow rejects lightweight tags, tags not reachable from main, and tags whose version does not match the first changelog entry. It then runs make check, make smoke and make audit on both pinned images, creates .tar.gz/.zip source archives plus SHA256SUMS, and publishes a GitHub Release. A version containing - is marked as a prerelease. Packagist picks up the tag when the repository integration is configured.

Never move or delete a published release tag; publish a new patch version instead.

Performance

This is scalar PHP; there is no SIMD. The benchmark harness measures one-shot hash, keyed hash, derive-key, streaming, and XOF on both libc variants:

Baseline on the pinned images (PHP 8.4.27, x86_64, PCOV/assertions off, OPcache CLI off): 1 MiB hash ≈ 102–113 ms (≈ 8.9–9.8 MiB/s); 1 KiB hash ≈ 9.4–10.2 MiB/s. The optimized compressor is ~2.2–3.2× faster than the initial array-based implementation across small, large and sequential scenarios; see the A/B table in BENCHMARKS.md. glibc and musl are within measurement noise for this workload.

Results are recorded in BENCHMARKS.md. Treat them as a baseline for optimization on the same machine, not as a universal throughput claim. PCOV and assertions are disabled for benchmark runs (-d pcov.enabled=0 -d zend.assertions=-1); OPcache CLI and JIT are off unless explicitly enabled.

For production, keep OPcache enabled and preload vendor/autoload.php, src/Hasher.php and src/functions.php. Do not enable JIT for this workload without measuring: CLI tracing was slower than the interpreter here, and the result is deployment-specific.

Design constraints

• one cohesive Hasher class plus three functions — no interfaces, traits, factories, or framework adapters;
• no runtime dependencies;
• 32-bit words stored in 64-bit PHP integers with explicit masking;
• chunk state and CV stack mirror the reference implementation in REF/BLAKE3;
• official test vectors are versioned and never edited.

See AGENTS.md for project rules.

License

Apache-2.0. The BLAKE3 test vectors are from the official BLAKE3 repository and retain their original licensing; see tests/fixtures/README.md.