Sodium Compat Laravel Package

Product Decisions This Supports

• Build vs. buy for cryptography. The decision this package mostly serves is "do we write our own crypto, adopt libsodium primitives, or adopt a polyfill for them?" The answer for a Laravel team should always be "use a library" — this package lets you standardize on the libsodium API surface (AEAD, detached signatures, sealed boxes, key exchange, streaming encryption) without betting your release process on ext-sodium being present on every host in your fleet, including customer-managed, on-prem, or shared-hosting deployments.
• Runtime/deployment strategy as a product decision, not an infra footnote. The real choice is "require the extension in our Docker image/CI/Forge/Vapor config" vs. "ship the polyfill and tolerate variable performance." That choice drives support burden, onboarding friction for self-hosted enterprise customers, and whether you can claim "works on any PHP 7.x/8.x host." The README's polyfill_is_fast() helper is the key hook: it lets you route crypto-heavy work to a queue or cron when the fast path isn't available, which is a user-visible latency decision (e.g., synchronous file encryption on upload vs. asynchronous background processing).
• Support-matrix and upgrade roadmap. v1.x (PHP 5.2.4+, 32-bit capable) vs. v2.x (PHP 8.1+, 64-bit only, faster, leaner) is a concrete roadmap fork: it tells you when you can drop legacy-compat dependencies, and it forces an explicit answer to "what is our minimum PHP version and do we still support 32-bit installs?" That answer usually unblocks several other dependency upgrades at once.
• Feature enablement for security-adjacent capabilities. Encryption of small tenant secrets, signed/verifiable tokens and webhooks, crypto_box_seal for PII shared to a recipient's public key, crypto_secretstream for large-file envelope encryption, and Ed25519→Curve25519 conversion for mixing signing and encryption keys. These are roadmap items that become cheap if the primitives are already a dependency, and expensive (or outsourced to a KMS) if not.
• Compliance, procurement, and risk sign-off. The README explicitly states the library has not been formally audited by an independent cryptography firm. That's a decision input for security questionnaires, SOC 2/PCI scoping, and any enterprise deal with a "no unaudited crypto" clause — it determines whether you need an internal review, a support contract with Paragon, or an exception request.
• Dependency hygiene and composer why triage. Because this arrives transitively via other packages, it shows up in SBOM/vulnerability reviews and can pin your PHP floor. Owning that decision deliberately (rather than discovering it) avoids surprise upgrade blocks.
• Key management is not solved by this package. Adopting it is a crypto primitive decision, not a secrets lifecycle decision. If the roadmap requires rotation, HSM backing, or audit trails, the product decision is "library plus KMS/Vault," not "library instead of KMS."

When to Consider This Package

Adopt when:

• You distribute a library, package, or framework component that must run on unknown hosts — the README's own recommendation is a "paragonie/sodium_compat": ">= 1" constraint, which is exactly the posture a reusable Laravel package should take.
• Your deployment targets are not under your control (on-prem enterprise installs, customer-hosted Laravel apps, shared hosting, older PHP-FPM images) and ext-sodium cannot be guaranteed.
• You support PHP < 7.2 or 32-bit PHP — in which case you must stay on the v1.x branch and should plan an exit path.
• You need libsodium-specific primitives that OpenSSL/openssl_* doesn't give you cleanly: sealed boxes, detached signatures, crypto_kx session keys, secretstream for chunked file encryption, XChaCha20 variants, AEGIS AEAD, or Ristretto255 for advanced protocols.
• You need wire-format interoperability with mobile or non-PHP clients already using libsodium — using the same primitives on the server is the cheapest way to keep that contract stable.
• You're migrating a legacy codebase off mcrypt or a homegrown scheme and want a drop-in sodium_* → ParagonIE_Sodium_Compat:: translation to reduce blast radius.

Look elsewhere when:

• You control the runtime and can guarantee ext-sodium. On Laravel 9+/PHP 8.x containerized deployments, the extension is almost always available and dramatically faster; the polyfill is then dead weight and an extra supply-chain surface. Mandate the extension in your base image instead.
• You only need encrypted Eloquent fields or app-level secrets. Laravel's Crypt facade and the encrypted cast already handle this; adding a crypto dependency for that need is unjustified.
• You need password hashing. Use Laravel's Hash (Argon2id/bcrypt). This is not a password-hashing tool.
• You have regulated crypto requirements (FIPS 140, formally audited crypto only) — the README is upfront that no third-party audit exists; you'd need a different vendor or a formal engagement.
• You're doing high-volume, in-request crypto without a fast path. Pure-PHP crypto in a request cycle is a latency and CPU-cost problem; install the extension, offload to a queue, or move to a managed KMS/Vault.
• You need PKI, X.509, or TLS operations — that's OpenSSL's domain, not libsodium's.
• You need managed key storage, rotation, and audit trails — buy a KMS; a library won't get you there.

Practical verification before adopting: run composer why paragonie/sodium_compat (note: the "0 dependents" figure in the package metadata looks understated and should not be treated as an adoption signal — the README cites Joomla! and Magento, and the real installed base is much wider), confirm which major version your constraint resolves to, and check whether sodium_crypto_* functions are already available in your production image.

How to Pitch It (Stakeholders)

For executives: This is a small, ISC-licensed, well-maintained compatibility layer for the standard modern PHP encryption library. It costs us nothing, carries no vendor lock-in, and removes a class of "our app won't install on that customer's server" escalations. It does not replace our key management story, and it has not been formally audited — so it's low-cost insurance for portability, not a compliance shortcut. The alternative to adopting it is either (a) supporting only hosts where we control the PHP build, or (b) hand-rolling crypto, which is strictly worse.

For engineering: Drop-in polyfill — you write sodium_* calls (or ParagonIE_Sodium_Compat:: if you need PHP 5.2-era support) and it transparently uses ext-sodium when present, falling back to pure PHP when it isn't. Constraints: use >= 1 if we're publishing a package, pin explicitly if we're an application; v1.x if we must keep 32-bit or pre-7.2 support, v2.x (PHP 8.1+, 64-bit, faster, smaller) otherwise. Releases are GPG-signed and available as a phar for non-Composer installs. Use polyfill_is_fast() to decide sync vs. queued execution for anything crypto-heavy, and never set $fastMult = true without verifying the target CPU — the README spells out that trade-off. Don't use it for password hashing (use Hash) or for the standard encrypted cast (Crypt already covers it); reserve it for sealed boxes, detached signatures, secretstream file encryption, and cross-platform interop.