Cryptor

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.

---