PHPackages                             phpnomad/sodium-integration - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Security](/categories/security)
4. /
5. phpnomad/sodium-integration

ActiveLibrary[Security](/categories/security)

phpnomad/sodium-integration
===========================

libsodium encryption strategy (XChaCha20-Poly1305 AEAD) for phpnomad/encryption — the default cipher integration, plus a secretbox migration strategy.

v1.0.1(yesterday)011↑2627.3%MITPHP >=8.2

Since Jul 19Compare

[ Source](https://github.com/phpnomad/sodium-integration)[ Packagist](https://packagist.org/packages/phpnomad/sodium-integration)[ Docs](https://github.com/phpnomad/sodium-integration)[ RSS](/packages/phpnomad-sodium-integration/feed)WikiDiscussions Synced today

READMEChangelogDependencies (2)Versions (3)Used By (0)

phpnomad/sodium-integration
===========================

[](#phpnomadsodium-integration)

The default [libsodium](https://www.php.net/manual/en/book.sodium.php) cipher integration for [`phpnomad/encryption`](https://github.com/phpnomad/encryption). It ships the concrete `EncryptionStrategy` implementations; the contract package holds only interfaces, value objects, and the framework-agnostic field-level helpers.

- **`SodiumEncryptionStrategy`** — authenticated encryption with XChaCha20-Poly1305 IETF AEAD (the default). Tampering is detected on decrypt, and the caller's context is authenticated so a value can't be replayed into a different row, column, or tenant. Optionally reads legacy `sodium_crypto_secretbox` data during a migration.
- **`LegacySecretboxEncryptionStrategy`** — read/write `sodium_crypto_secretbox`(XSalsa20-Poly1305) for backward compatibility with an older secretbox corpus.

Requirements
------------

[](#requirements)

- PHP >= 8.2
- `ext-sodium` (bundled with PHP 7.2+)
- `phpnomad/encryption` (the contracts)

Install
-------

[](#install)

```
composer require phpnomad/encryption phpnomad/sodium-integration
```

Usage
-----

[](#usage)

Wire `SodiumEncryptionStrategy` as your `EncryptionStrategy`. Everything else — the key providers, the `EncryptedValue` model — comes from `phpnomad/encryption`and is cipher-agnostic. How you persist the sealed value is your call; the contract imposes no format.

```
use PHPNomad\Encryption\Providers\ArrayKeyProvider;
use PHPNomad\Encryption\Models\EncryptedValue;
use PHPNomad\Sodium\EncryptionIntegration\Strategies\SodiumEncryptionStrategy;

// A key ring holding one 32-byte key at version 1.
$keys = new ArrayKeyProvider([1 => sodium_crypto_aead_xchacha20poly1305_ietf_keygen()]);

$encryption = new SodiumEncryptionStrategy($keys);

$sealed = $encryption->encrypt('sk-live-super-secret', 'tenant:42:column:token');

// Persist $sealed however you like — e.g. across columns:
$ciphertext = base64_encode($sealed->getCiphertext());
$nonce      = base64_encode($sealed->getNonce());
$version    = $sealed->getKeyVersion();

// Later — rebuild and decrypt with the same context:
$restored  = new EncryptedValue(base64_decode($ciphertext), base64_decode($nonce), $version, SodiumEncryptionStrategy::CIPHER);
$plaintext = $encryption->decrypt($restored, 'tenant:42:column:token');
// => "sk-live-super-secret"
```

### Reading legacy `secretbox` data

[](#reading-legacy-secretbox-data)

If you're adopting this over data previously encrypted with `sodium_crypto_secretbox`, enable the fallback so unmarked values are tried as AEAD first and then as secretbox:

```
$encryption = new SodiumEncryptionStrategy($keys, allowLegacySecretboxFallback: true);
```

New writes are always AEAD; old secretbox values keep decrypting until you re-encrypt them. `LegacySecretboxEncryptionStrategy` is also provided for read-only or explicit secretbox handling.

Security notes
--------------

[](#security-notes)

- **XChaCha20-Poly1305** is used because its 24-byte nonce is large enough to pick at random per message without collision worries — no nonce counter to persist. Keys are 32 bytes.
- Keys are wiped from memory with `sodium_memzero` after each operation.
- Decryption failure (wrong key, wrong context, or tampering) always raises `DecryptionFailedException` — never a partial or forged plaintext.
- Associated data is authenticated, **not** encrypted. Don't put secrets in the context.

Testing
-------

[](#testing)

```
composer install
composer test
```

License
-------

[](#license)

MIT © Novatorius / Alex Standiford

###  Health Score

42

—

FairBetter than 88% of packages

Maintenance100

Actively maintained with recent releases

Popularity7

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity47

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

1d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/9e6206223bd6f2a57b8ac80605b1b5c3521faaec18ad3f20f25fb728a9a13784?d=identicon)[tstandiford](/maintainers/tstandiford)

---

Tags

cryptographyencryptionlibsodiumaeadintegrationsodiumphpnomadxchacha20poly1305

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/phpnomad-sodium-integration/health.svg)

```
[![Health](https://phpackages.com/badges/phpnomad-sodium-integration/health.svg)](https://phpackages.com/packages/phpnomad-sodium-integration)
```

###  Alternatives

[phpseclib/phpseclib

PHP Secure Communications Library - Pure-PHP implementations of RSA, AES, SSH2, SFTP, X.509 etc.

5.6k465.6M1.6k](/packages/phpseclib-phpseclib)[defuse/php-encryption

Secure PHP Encryption Library

3.9k175.2M257](/packages/defuse-php-encryption)[paragonie/sodium_compat

Pure PHP implementation of libsodium; uses the PHP extension if it exists

931145.2M185](/packages/paragonie-sodium-compat)[paragonie/halite

High-level cryptography interface powered by libsodium

1.2k10.6M85](/packages/paragonie-halite)[paragonie/ciphersweet

Searchable field-level encryption library for relational databases

4671.4M24](/packages/paragonie-ciphersweet)[vlucas/pikirasa

PKI public/private RSA key encryption using the OpenSSL extension

107105.0k1](/packages/vlucas-pikirasa)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)