# sodium_compat: a pure PHP libsodium for installs without ext/sodium

> Sodium Compat is a pure PHP implementation of the Sodium cryptography library, used when the PHP extension is missing, and it steps aside automatically when the extension is present. It fits teams that must run identical crypto code across environments with and without ext/sodium, and it comes with the caveat that it has not been formally audited by an independent third party.

**paragonie/sodium_compat** — Pure PHP polyfill for ext/sodium

- Repository: https://github.com/paragonie/sodium_compat
- Website: https://paragonie.com
- Stars: 931 · Forks: 66
- Language: PHP
- License: ISC
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/paragonie-sodium-compat

## The same sodium_* calls without the extension

Sodium Compat is described as a pure PHP polyfill for the Sodium cryptography library, libsodium, which is a core extension in PHP 7.2.0 and later and otherwise available through PECL. The point of a polyfill in this shape is that application code calls the extension's function names and does not change.

The naming detail matters and is settled by an RFC rather than by the library. As per the second vote on the libsodium RFC, PHP 7.2 uses sodium_* instead of the older \Sodium\* names, and the polyfill follows that convention, so a call such as sodium_crypto_sign_keypair() works the same whether the extension is loaded or the polyfill is providing it.

The topic tags describe the coverage: blake2b, siphash, curve25519, x25519, ed25519, xsalsa20poly1305 and xchacha20-poly1305. Between them they cover the primitives a PHP application normally reaches for when it needs authenticated encryption, key agreement, hashing or digital signatures.

The repository layout supports the polyfill idea in a practical way. There are src/ and lib/ directories for the implementation, a namespaced/ directory, several autoload entry points named autoload.php, autoload-fast.php, autoload-pedantic.php and autoload-phpunit.php, and a separate tests/ tree. The multiple autoload files are the visible cost of the design: a polyfill has to be loaded before the extension is known to be missing, and different loaders trade startup time against strictness.

## The extension takes over the moment it exists

The behaviour that matters most in production is stated in one line: if you have the PHP extension installed, Sodium Compat will opportunistically and transparently use the PHP extension instead of its own implementation.

That single property changes the risk profile of the library. A polyfill that always shadows the extension would put a pure PHP implementation of every crypto operation on the hot path of any host that happens to have the extension, which is the opposite of what you want from a compatibility shim. This one defers to the native implementation whenever it can, so the polyfill code path is exercised on the hosts that genuinely lack the extension and nowhere else.

There is a second consequence worth planning for. Whether a given call is served by the extension or by the polyfill depends on the environment, so performance characteristics differ between hosts, and any measurement you take in development with the extension loaded does not describe the polyfilled host. If you deploy across a mixed estate, that difference is a property of your deployment, not a bug in either implementation, and it is worth knowing about before someone builds a latency budget on the wrong number.

## Two major versions split by PHP floor and integer width

The project maintains two lines with different support envelopes, and the choice between them is not a matter of taste.

Sodium Compat v1.21.0 was the last v1.x release from the master branch, and all future releases supporting PHP 5.2 through 8.0 and 32-bit integers live on the v1.x branch. Newer versions, v2.0.0 and up, stay on master. The table in the documentation makes the split explicit: v1.x.y supports PHP 5.2.4 through the latest release with 32-bit support, and v2.x.y supports PHP 8.1 through the latest release without 32-bit support.

So if you need 32-bit PHP support, where PHP_INT_SIZE is 4, you stay on v1.x. If you want improved performance and smaller dependencies, you move to v2.x. The stated goal for the v2 work is to improve code readability and performance while reducing boilerplate code.

The dependency guidance is worth quoting because it is unusual. Libraries and frameworks are asked to set a Composer constraint of >= 1, and applications are told to do the opposite and specify the actual version that matters to them and their deployments. The reasoning is straightforward once stated. A library that hard-pins a major version forces every downstream user onto that major, so the library stays permissive, while the application, which knows its own PHP floor and its own risk tolerance, pins precisely.

One wrinkle to watch in the release list. The recent releases include v2.5.2 and v2.5.1 on 2026-08-18 and v1.24.2 the same day, so both lines are still being cut, and the v1.x branch is still receiving maintenance releases rather than being frozen.

## Installing through Composer or from a signed source tarball

Composer is the ordinary route:

```bash
composer require paragonie/sodium_compat
```

Without Composer, the documentation points at a release tarball, notes that it should be signed with the project's GnuPG public key, and asks you to extract it and include the autoload script:

```php
<?php
require_once "/path/to/sodium_compat/autoload.php";
```

Since version 1.3.0 the releases also include a PHP Archive with an associated GPG signature, and the verification recipe is given explicitly, including the key fingerprint and the keyserver fetch:

```bash
# Getting our public key from the keyserver:
gpg --fingerprint 7F52D5C61D1255C731362E826B97A1C2826404DA
if [ $? -ne 0 ]; then
    echo -e "\033[33mDownloading PGP Public Key...\033[0m"
    gpg  --keyserver pgp.mit.edu --recv-keys 7F52D5C61D1255C731362E826B97A1C2826404DA
    # Security <security@paragonie.com>
    gpg --fingerprint 7F52D5C61D1255C731362E826B97A1C2826404DA
    if [ $? -ne 0 ]; then
        echo -e "\033[31mCould not download PGP public key for verification\033[0m"
        exit 1
    fi
fi

# Verifying the PHP Archive
gpg --verify sodium-compat.phar.sig sodium-compat.phar
```

Once verified, the phar is included the same way as the source tree:

```php
<?php
require_once "/path/to/sodium-compat.phar";
```

The build script build-phar.sh in the repository root is what produces that artefact, so the phar is a repository output rather than a third-party repackaging.

## No formal audit, and that is the real limitation

The documentation is direct about this, and it deserves to be quoted rather than paraphrased: the cryptography library has not been formally audited by an independent third party that specialises in cryptography or cryptanalysis. The project says that if you require such an audit before you can use it, and have the funds for it, you should open an issue or contact the maintainers so they can help get the ball rolling.

What is offered in place of an audit is adoption and review history. The project states that sodium_compat has been adopted by high profile open source projects such as Joomla and Magento, and that it was developed by Paragon Initiative Enterprises, a company that specialises in secure PHP development and PHP cryptography, and has been informally reviewed by many other security experts who also specialise in PHP. There is also a pointer to a write-up on the defensive security measures taken to prevent the library from becoming a source of vulnerability in your systems.

Set against that, the practical limitation for an adopter is a plain one. A pure PHP implementation of curve-based and stream crypto is not going to match a native extension in speed, and the constant factor matters if you are signing or decrypting on a busy request path. The library itself frames v2 as the line for improved performance and smaller dependencies, which concedes the point. And an informal review by competent PHP security people is not the same artefact as a formal cryptographic audit, so a compliance regime that demands the latter will not be satisfied by the former. If that regime applies to you, the extension is the answer and this library is not.

## Licence, releases and where the support boundary sits

The licence is ISC, which is a short permissive licence with attribution as its only substantive obligation, and the homepage is paragonie.com. For a dependency that sits in the authentication or signing path of an application, that permissiveness is convenient: there is no copyleft obligation to propagate and no obligation to publish anything about your own code that links to it.

The release record shows the project is still being worked on, with the last push on 2026-08-18 and releases v2.5.2, v2.5.1 and v1.24.2 published on that date. Both major lines moved in the same window, which is a useful signal for anyone pinning a version.

The support boundary is where most of the friction will be. Non-commercial reports are handled through GitHub issues, and the documentation is explicit that no guarantees are offered about availability to resolve integration questions for free, though it says bugs including security issues will be fixed. Commercial support for libsodium itself is offered by multiple vendors, and Paragon Initiative Enterprises sells support contracts for organisations using the library in products or services. If you are deploying this in a product with an uptime expectation, that support path is part of the cost of the decision, not an optional extra.

The upstream CI picture also matters for a cryptography library: the repository carries build and Psalm workflow badges alongside PHPUnit configuration, plus phpstan.neon.dist, psalm.xml, psalm-new.xml, infection.json.dist and a fuzzing/ directory. Static analysis and mutation testing configuration in the tree is a reasonable proxy for the care taken on a polyfill that has to reproduce another library's behaviour exactly.

## Conclusion

Adopt sodium_compat when one codebase has to run crypto identically on hosts with and without ext/sodium, and pin the major version to the PHP floor you support. Skip it if your deployments all have the extension, since the extension is faster and audited separately, or if policy requires an independent cryptographic audit, which this library does not have. Verify first which major version your PHP version can take, v1.x for PHP 5.2 through 8.0 with 32-bit integers, v2.x for PHP 8.1 and later, and confirm that a call still resolves to the extension once it is installed.

## FAQ

### What is sodium_compat and when would I use it?

It is a pure PHP polyfill for the Sodium cryptography library, libsodium, which is a core extension in PHP 7.2.0 and later and otherwise available through PECL. It lets the same sodium_* calls work on hosts where the extension is not installed.

### Does sodium_compat use the PHP extension when it is available?

Yes. The documentation states that if you have the PHP extension installed, Sodium Compat will opportunistically and transparently use the PHP extension instead of its own implementation.

### Which sodium_compat version should I use?

If you need 32-bit PHP support with PHP_INT_SIZE equal to 4, use the v1.x line, which supports PHP 5.2.4 through the latest release. If you want improved performance and smaller dependencies, use v2.x, which requires PHP 8.1 or later and is developed on the master branch.

### How do I install sodium_compat without Composer?

Download a release tarball that should be signed with the project's GnuPG public key, extract it and include the autoload script with require_once. Since version 1.3.0 the releases also include a .phar with a GPG signature, which can be verified with gpg --verify sodium-compat.phar.sig sodium-compat.phar and then included with require_once.

### Has sodium_compat been cryptographically audited?

No. The documentation states plainly that the library has not been formally audited by an independent third party specialising in cryptography or cryptanalysis, and it invites organizations that require such an audit to contact the maintainers.

## Sources

- [License: ISC](https://github.com/paragonie/sodium_compat/blob/master/LICENSE)
- [paragonie/sodium_compat on GitHub](https://github.com/paragonie/sodium_compat)
- [Project website](https://paragonie.com)
- [README](https://github.com/paragonie/sodium_compat/blob/master/README.md)
- [Releases](https://github.com/paragonie/sodium_compat/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/paragonie-sodium-compat