Weave Code
Sodium Compat Laravel Package
paragonie/sodium_compat
Pure PHP polyfill for libsodium (Sodium crypto), transparently using the PHP extension when installed. Supports PHP 5.2.4+ and 32-bit integers in v1.x, with v2.x targeting PHP 8.1+.
Sodium Compat is a pure PHP polyfill for the Sodium cryptography library (libsodium), which is a core extension in PHP 7.2+ and otherwise available via PECL. It provides a drop-in replacement for the sodium_* functions, so your code works even when the native extension is missing—and it transparently delegates to the extension when present for maximum performance.
- Broad compatibility: supports PHP 5.2.4+ in v1.x, including 32-bit integers
- Automatic acceleration: uses libsodium opportunistically when installed
- Complete API: key exchange, signatures, secret-key and public-key encryption, hashing
- Battle-tested: maintained by Paragon Initiative Enterprises, widely used across the ecosystem
Frequently asked questions about Sodium Compat
- What is paragonie/sodium_compat used for in a Laravel application?
- It is a pure PHP implementation of libsodium that provides sodium_* functions when the native sodium extension is unavailable. In Laravel it is usually an invisible transitive dependency behind JWT, encryption, or signing packages rather than a first-party API. Use native sodium functions in your own application code and keep sodium_compat as a compatibility layer.
- How do I install paragonie/sodium_compat in Laravel?
- Install it with composer require paragonie/sodium_compat, or let Composer pull it in transitively through a package that requires it. Laravel's standard Composer autoloader handles it with no extra wiring. There is no service provider, facade, config file, or migration to publish.
- Do I need a service provider or configuration for sodium_compat in Laravel?
- No. Sodium Compat is a low-level cryptography library, not a Laravel package, so it has no framework coupling and no configuration surface. It exposes sodium_* functions only when ext/sodium is unavailable and also provides ParagonIE_Sodium_Compat for explicit use. Your only setup concerns are Composer constraints and PHP extension availability.
- Which PHP versions and architectures does sodium_compat support?
- The v1.x branch supports PHP 5.2.4 and later, including 32-bit environments. The v2.x branch requires PHP 8.1 or later and 64-bit integers, so it does not support 32-bit PHP. Choose v2.x for modern Laravel stacks on 64-bit PHP 8.1+ and pin v1.x only for legacy or 32-bit targets.
- Does sodium_compat require the PHP sodium extension?
- No, it works without ext/sodium by using its pure PHP implementation. If the native sodium extension is installed, sodium_compat opportunistically and transparently delegates to it, which is faster and lowers crypto risk. You can require ext-sodium in production and keep the polyfill only where a dependency still declares it.
- Is paragonie/sodium_compat safe for production cryptography in Laravel?
- The README states the library has not been formally audited by an independent cryptography specialist, so your organization owns the residual risk if it is used as the actual crypto path. The pure PHP path is slower and must trade speed for constant-time behavior unless fast multiplication is enabled, which is unsafe on some processors. Risk is materially lower when ext/sodium is present because sodium_compat delegates to the native extension.
- How do I find out why paragonie/sodium_compat is in my Laravel project and can I remove it?
- Run composer why paragonie/sodium_compat or inspect composer.lock to identify direct versus transitive consumers. It is commonly pulled in by JWT, encryption, or signing libraries as a fallback. Remove it only after updating or replacing the packages that declare it and after verifying that your production runtime has ext-sodium enabled.
- How should I test sodium_compat in Laravel CI and deployment?
- Run CI across your supported PHP versions and architectures, testing both with and without ext-sodium enabled. Benchmark JWT signing and verification, encryption, and signature paths, and verify that Docker, Forge, Heroku, or other runtime images enable the sodium extension. Keep config.platform.php aligned with production and check logs or health checks for crypto failures.
- What are alternatives to paragonie/sodium_compat for Laravel cryptography?
- The preferred alternative is the native ext/sodium extension and its sodium_* functions, which modern PHP includes but runtime images may not enable. For application-level needs, use Laravel's Crypt and Hash facades or dedicated libraries appropriate to the use case. Sodium Compat exists mainly for compatibility with dependencies, not as a recommended foundation for new first-party crypto features.
- How is paragonie/sodium_compat maintained and is commercial support available?
- Paragon Initiative actively maintains two branches: v1.x for legacy PHP and 32-bit systems, and v2.x for modern 64-bit PHP. Community support runs through GitHub issues, and commercial support is available from Paragon Initiative. Internally, document that first-party crypto uses native sodium and that sodium_compat is only a fallback, then track dependency upgrades and extension availability.
Weaver
How can I help you explore Laravel packages today?