Sodium Compat

Sodium Compat is a pure-PHP implementation of the libsodium (ext/sodium) cryptography API, letting you use modern authenticated encryption, digital signatures, key exchange, and hashing without requiring the native PHP extension. When the extension is present, it transparently defers to it for speed; otherwise it falls back to a carefully written, side-channel-resistant PHP implementation.

Maintained by Paragon Initiative Enterprises and adopted by major projects such as Joomla! and Magento, it exposes the same sodium_* function names as PHP’s built-in extension so existing libsodium code runs unchanged across virtually any PHP deployment.

What You Get

• A drop-in polyfill exposing the same sodium_* functions as PHP’s native extension
• Authenticated encryption (secretbox, AEAD ChaCha20-Poly1305, XChaCha20-Poly1305, AES-256-GCM)
• Public-key crypto: Ed25519 signatures, X25519 key exchange, and sealed boxes
• Generic hashing (BLAKE2b) and message authentication (crypto_auth)
• Transparent use of the native ext/sodium extension when it is installed

Common Use Cases

• Adding strong encryption and signatures to apps that cannot install PECL extensions
• Writing portable libraries that depend on libsodium across many PHP versions
• Encrypting data at rest or in transit with modern AEAD constructions
• Verifying software updates or tokens with Ed25519 signatures

Under The Hood

Architecture - The public surface lives in src/Compat.php (the ParagonIE_Sodium_Compat class) and a thin procedural autoload.php that defines global sodium_* functions, dispatching to the native extension when detected or to pure-PHP Core implementations otherwise. Cryptographic primitives are organized under src/Core (and 32-bit variants), with a namespaced PSR-4 API under namespaced/ for modern consumers.

Tech Stack - Pure PHP with no runtime dependencies; the v2 branch targets PHP 8.1+ (64-bit) while the v1 branch supports PHP 5.2+ including 32-bit. Development tooling includes PHPUnit, Psalm static analysis, Infection mutation testing, and a php-fuzzer harness.

Code Quality - The repository is extensively tested with unit tests, known-answer tests (KAT), and compatibility tests against the native extension, plus mutation and fuzz testing configured. Constant-time coding patterns are used deliberately for side-channel resistance.

API Design - By exactly matching PHP’s native sodium_* function names and signatures, the library is a true drop-in polyfill: existing libsodium code runs unchanged, and the ParagonIE_Sodium_Compat:: static methods provide the same API on very old PHP versions.