northrook/hasher

Crockford Base32 hashing utilities for short, URL-safe identifiers, checksums, and time-sortable prefixes

dev-main 2026-07-10 10:33 UTC

Requires

• php: >=8.4
• ext-hash: *
• ext-random: *

Requires (Dev)

• northrook/php-cs: dev-main
• phpstan/phpstan: ^2.2
• phpunit/phpunit: ^11.5

BSD-3-Clause

• Martin Nielsen

Published on Packagist.org on 2026-07-10 09:34 UTC

README

Crockford Base32 hashing utilities for short, URL-safe identifiers, checksums, and time-sortable prefixes.

Requires PHP 8.4+. No runtime Composer dependencies.

Requirements

• PHP >=8.4
• ext-hash (xxHash32 via hash('xxh32', …))
• ext-random (Random\Randomizer for crypto())

Installation

composer require northrook/hasher

Quick start

use Northrook\Hash;

Hash::checksum('hello');                  // '03XG0XZS'
Hash::time(10, seed: 1_700_000_000_000);  // '01HF7YAT00'
Hash::crypto();                           // 16-char CSPRNG token

API reference

Method	Default length	Range	Purpose
xxh32(string $value)	n/a	n/a	Raw 8-char lowercase hex digest
checksum(string $value)	8 (fixed)	n/a	Canonical Crockford Base32 checksum
value(string $value, int $length = 8)	8	4–8	Truncated Crockford Base32 digest (LSB end)
time(int $length = 10, null\|int\|float $seed = null)	10	1–16	Millisecond timestamp as sortable Base32
fast(int $length = 8)	8	1–32	Fast random (mt_rand); not for secrets
crypto(int $length = 16)	16	8–32	CSPRNG random (Random\Randomizer)

time() seed: null → current time (ms); int → milliseconds since epoch; float → seconds (fractional part included). Length 10 gives full millisecond sortability.

Examples

Checksums and digests

Hash::xxh32('hello');      // 'fb0077f9'
Hash::checksum('hello');   // '03XG0XZS'
Hash::value('hello', 4);   // '0XZS'
Hash::checksum('café');    // '00ZXTEE1'

Time-sortable prefixes

Hash::time(10, seed: 1_700_000_000_000); // '01HF7YAT00'
Hash::time(8, seed: 1_700_000_000_000);  // 'HF7YAT00' — suffix of the 10-char form

Random tokens

Hash::fast(8);    // non-cryptographic — UI keys, low-stakes nonces
Hash::crypto(16); // secrets, session tokens, API keys

Composite IDs

$id = Hash::time(10) . Hash::crypto(16);

checksum(), value(), xxh32(), and fast() are not for security-sensitive use.

Use crypto() for secrets and unguessable tokens.

Development

composer test
composer phpstan

License

BSD-3-Clause. See LICENSE.