random_compat

random_compat is a PHP 5.x polyfill, created by Paragon Initiative Enterprises, that backports PHP 7’s random_bytes() and random_int() cryptographically secure random number functions. It never falls back to insecure randomness: if the underlying platform cannot produce a cryptographically strong value (e.g. /dev/urandom or CryptGenRandom are unavailable), it throws an Exception rather than silently returning predictable output — matching the fail-closed behavior PHP 7 itself guarantees natively.

For years it was the standard dependency for any PHP library or framework needing secure randomness (password reset tokens, session identifiers, CSRF tokens) while still supporting PHP 5 users, and it remains widely required transitively even now, with ECDSA-signed PHAR releases available for supply-chain verification alongside standard Composer installation.

What You Get

• Polyfilled random_bytes($length) and random_int($min, $max) functions matching PHP 7’s native signatures and behavior exactly
• Fail-closed security: throws an Exception instead of ever returning weak or predictable random data
• ECDSA-signed .phar archive releases for supply-chain-verifiable installation outside Composer
• Automatic detection and use of the strongest available OS entropy source (/dev/urandom, CryptGenRandom, mcrypt, OpenSSL) depending on platform
• Zero-config: on PHP 7+ the functions are already native, so the polyfill becomes a no-op without any code changes required

Common Use Cases

• Generating secure password-reset or email-verification tokens in a PHP 5-compatible library
• Producing cryptographically strong session identifiers or CSRF tokens without depending on mt_rand() or uniqid()
• Adding random_bytes()/random_int() calls to a codebase that must keep supporting PHP 5 users during a PHP 7 migration window
• Satisfying a transitive dependency requirement from other security-sensitive libraries (many older Composer packages still pin paragonie/random_compat)

Under The Hood

Architecture - The library is a single-purpose polyfill: lib/random.php checks whether random_bytes()/random_int() already exist natively (PHP 7+) and, if not, defines them by probing available entropy sources in priority order (/dev/urandom, mcrypt_create_iv, openssl_random_pseudo_bytes, CryptGenRandom on Windows) and wrapping whichever is found in a uniform, exception-throwing API.

Tech Stack - Pure PHP with no Composer dependencies beyond the PHP runtime itself; it deliberately avoids any autoloading magic so it can be require_once’d directly, including via a signed PHAR for environments that can’t use Composer.

Code Quality - The project carries GitHub Actions CI and Scrutinizer static-analysis badges, and as a security-critical library from Paragon Initiative Enterprises it has been publicly audited by community cryptography reviewers; commit activity has slowed to occasional maintenance releases now that PHP 5 is long past end-of-life and the native functions cover virtually all current PHP installs.

API Design - The entire public surface is two functions matching PHP 7’s built-in signatures exactly, so adopting code requires zero API learning beyond PHP’s own random_bytes/random_int documentation — the polyfill is designed to be indistinguishable from the native functions it backports.