Home

InitPHP Encryption — Wiki

Welcome to the official documentation for initphp/encryption — a small, opinionated symmetric encryption library for PHP 8.1+ built on ext-openssl and ext-sodium.

The package wraps PHP's two production-grade cryptographic extensions behind a single, hard-to-misuse API. Pick a handler, pass a key, encrypt anything — the library handles key derivation, authentication, format versioning and safe serialization for you.

composer require initphp/encryption

use InitPHP\Encryption\Encrypt;
use InitPHP\Encryption\Sodium;

$handler = Encrypt::use(Sodium::class, ['key' => getenv('APP_KEY')]);

$ciphertext = $handler->encrypt(['user_id' => 42, 'role' => 'admin']);
// → "020047ae3f8c..." — hex, safe for cookies / DBs / URLs

$payload = $handler->decrypt($ciphertext);
// → ['user_id' => 42, 'role' => 'admin']

The package ships two handlers and one extension point:

Class	Purpose
OpenSSL	AES-family ciphers with HMAC authentication; configurable cipher and hash.
Sodium	libsodium's XSalsa20-Poly1305 AEAD; no tunables to get wrong.
BaseHandler	Abstract base for building your own handler around any primitive.

Both built-in handlers implement the same HandlerInterface, so swapping between them is a constructor change.

Start Here

• New to the package? Read Installation, then Quick Start.
• Picking a handler? Compare OpenSSL and Sodium side by side.
• Writing your own handler? See Custom Handlers.
• Coming from 1.x? Start with Migration from 1.x — ciphertexts produced by 1.x are not readable by 2.x.
• Looking for a specific method? The full API Reference lists every public class member.

Navigation

Getting Started

• Installation
• Quick Start

Handlers

• OpenSSL Handler
• Sodium Handler
• Custom Handlers

Reference

• Configuration Options
• Ciphertext Format
• Serialization
• Error Handling
• API Reference

Practical Guides

• Recipes
• Security Best Practices
• Testing Your Encryption
• Troubleshooting

Other

• Migration from 1.x
• FAQ

At a Glance — Handler Comparison

Capability	OpenSSL	Sodium
Authenticated encryption	✅ (HMAC, encrypt-then-MAC)	✅ (Poly1305 AEAD)
Random IV / nonce per call	✅ (random_bytes)	✅ (random_bytes)
Accepts any-length user key	✅ (HKDF)	✅ (BLAKE2b)
Configurable cipher	✅	—
Configurable hash	✅	—
Length-hiding padding	—	✅ (sodium_pad)
Self-describing format header	✅ (version + serializer flag)	✅ (version + serializer flag)
JSON serializer (default)	✅	✅
PHP serializer (opt-in, safe)	✅	✅
Single exception class for all errors	✅	✅

If you have no opinion, use the Sodium handler. It is harder to misuse, and the defaults are correct.

What You Get

• Authenticated by default. No "encrypt without authenticate" mode — tampered ciphertexts always raise an exception, never decrypt to garbage.
• Versioned wire format. Every ciphertext begins with a magic byte (0x02); future format changes will bump it and reject older ciphertexts with a clear error instead of silent corruption.
• One exception type. Every failure raises InitPHP\Encryption\Exceptions\EncryptionException. One catch covers everything — see Error Handling.
• Safe-by-default serialization. JSON is the default, so the historical unserialize()-on-attacker-bytes pitfall is closed without you having to think about it. PHP serialize stays available as an opt-in for binary payloads, with allowed_classes: false always set.
• Free key flexibility. Pass any non-empty string for key; the handler derives a key of the correct length internally.

Package Metadata

• License: MIT
• Minimum PHP: 8.1
• Required extensions (per handler): ext-openssl or ext-sodium
• Packagist: initphp/encryption
• Source: github.com/InitPHP/Encryption
• Issues: github.com/InitPHP/Encryption/issues
• Discussions: github.com/orgs/InitPHP/discussions
• Security: SECURITY.md — please do not open a public issue for vulnerabilities.

If something in this wiki is unclear, wrong, or out of date, open an issue — doc fixes are merged eagerly.