README

A lightweight and secure PHP encryption library that provides modern AES-256-GCM authenticated encryption and decryption with optional AAD (Additional Authenticated Data) support.
It is designed to be simple, dependency-free, and compatible with any PHP application or framework.

Features

✅ AES-256-GCM authenticated encryption
✅ Optional AAD (Additional Authenticated Data)
✅ Secure key handling & memory cleanup
✅ JSON + Base64 encoded output
✅ Key derived safely from APP_KEY or custom string
✅ No framework dependency (works in plain PHP or Laravel)

Installation

Use Composer (recommended):

composer require lazervel/cryptor

Or manually include it:

require_once 'src/Cryptor.php';

⚙️ Environment Setup

Set your application key in .env or environment variables:

APP_KEY=base64:your-secret-key

Alternatively, you can provide a custom key directly when creating an instance.

🧠 Basic Usage

<?php

use Lazervel\Cryptor\Cryptor;

// Create instance (uses APP_KEY from env if not provided)
$cryptor = new Cryptor('my-secret-key');

// Encrypt a message
$encrypted = $cryptor->encrypt('Hello World!');
echo "Encrypted: " . $encrypted . PHP_EOL;

// Decrypt the message
$decrypted = $cryptor->decrypt($encrypted);
echo "Decrypted: " . $decrypted . PHP_EOL;

// Verify that data matches
if ($cryptor->verify('Hello World!', $encrypted)) {
    echo "✅ Data verified successfully!";
} else {
    echo "❌ Verification failed!";
}

🧩 With Additional Authenticated Data (AAD)

You can attach additional data (not encrypted but authenticated):

$add = 'payment#RZP123'; // example reference

$encrypted = $cryptor->encrypt('Sensitive Transaction Data', 'aes-256-gcm', $add);

// Must use same $add while decrypting
$decrypted = $cryptor->decrypt($encrypted, $add);

If the $add differs, decryption will fail — ensuring data integrity.

Security Design

Aspect	Detail
Algorithm	AES-256-GCM (Authenticated Encryption)
IV	Generated securely via `random_bytes()`
Tag	Auto-generated and verified internally
Key Derivation	`hash('sha256', $raw, true)` ensures 32-byte AES key
Memory Safety	Key wiped in destructor (`__destruct()`)
Serialization Protection	`__sleep()` prevents exposing secrets
Debug Protection	`__debugInfo()` hides the key during dumps

Error Handling

Error	Thrown when
`RuntimeException`	No key found in environment
`InvalidArgumentException`	Unsupported cipher name
`false` return	Encryption/decryption failure

You can wrap encryption/decryption calls inside try/catch if desired:

try {
    $cryptor = new Cryptor();
    $data = $cryptor->decrypt($input);
} catch (RuntimeException $e) {
    echo $e->getMessage();
}

🧰 Supported Ciphers

Cipher	Description
`aes-256-gcm`	(Default) Modern authenticated encryption
`aes-128-gcm`	Lightweight variant
`aes-256-cbc`	Legacy compatibility mode (no authentication)

GCM mode is recommended for all new applications.

Example Output Format

Encrypted data is a Base64-encoded JSON like this:

{
  "iv": "r7KfWkJcGlZcL7hYp6oJrQ==",
  "value": "J9PDpax7oMGJ6M4qYQ==",
  "cipher": "YWVzLTI1Ni1nY20=",
  "tag": "AQIDBAUGBwgJCgsMDQ=="
}

Entire JSON is Base64 encoded again to make it safe for database or URL storage.

Methods Summary

Method	Description
`__construct(?string $key = null)`	Initialize with custom or env key
`encrypt(string $data, ?string $cipher = null, string $add = '')`	Encrypt data
`decrypt(string $data, string $add = '')`	Decrypt data
`verify(string $plain, string $encrypted, string $add = '')`	Check if decrypted value matches plain text

Example Integration (with Laravel)

// config/app.php
'providers' => [
    Lazervel\Cryptor\Cryptor::class,
],

// usage
$cryptor = app(Lazervel\Cryptor\Cryptor::class);
$encrypted = $cryptor->encrypt('Secret Message');

License

This package is open-sourced software licensed under the MIT License.

Author

Indian Modassir
Developer of Lazervel — a collection of modern PHP libraries for secure, modular development.

lazervel / cryptor

Maintainers

Details