Getting Started

Minimal Steps to First Use

Installation:
```
composer require phpseclib/mcrypt_compat
```
Add this to your composer.json under require to ensure it’s included in your project.

Basic Usage: Replace any mcrypt_* function calls with the polyfill’s namespace:

use phpseclib\mcrypt_compat as mcrypt;

$key = 'my-secret-key';
$iv = mcrypt_create_iv(mcrypt_get_iv_size(MCRYPT_RIJNDAEL_128, MCRYPT_MODE_CBC), MCRYPT_RAND);
$data = 'Sensitive data';

$encrypted = mcrypt_encrypt(MCRYPT_RIJNDAEL_128, $key, $data, MCRYPT_MODE_CBC, $iv);
$decrypted = mcrypt_decrypt(MCRYPT_RIJNDAEL_128, $key, $encrypted, MCRYPT_MODE_CBC, $iv);

First Use Case:

Legacy Migration: Replace mcrypt calls in a Laravel controller or service handling encrypted data (e.g., API responses, database fields).

Example:

// Before (fails in PHP 8.x without mcrypt extension)
$encrypted = mcrypt_encrypt(MCRYPT_RIJNDAEL_256, $key, $data, MCRYPT_MODE_CBC, $iv);

// After (works with polyfill)
$encrypted = \phpseclib\mcrypt_compat\mcrypt_encrypt(MCRYPT_RIJNDAEL_256, $key, $data, MCRYPT_MODE_CBC, $iv);

Verify Compatibility:
- Test with a known plaintext/ciphertext pair to ensure decryption matches the original output.
- Check for warnings in PHP logs (e.g., deprecation notices in PHP 8.2+).

Implementation Patterns

Usage Patterns

Facade Pattern for Laravel: Create a facade to abstract the polyfill and maintain consistency:

// app/Facades/McryptFacade.php
namespace App\Facades;
use Illuminate\Support\Facades\Facade;
class McryptFacade extends Facade {
    protected static function getFacadeAccessor() {
        return 'mcrypt';
    }
}

// app/Providers/AppServiceProvider.php
public function register() {
    $this->app->bind('mcrypt', function() {
        return new class {
            public function encrypt($algorithm, $key, $data, $mode, $iv) {
                return \phpseclib\mcrypt_compat\mcrypt_encrypt($algorithm, $key, $data, $mode, $iv);
            }
            // Add other mcrypt functions as needed...
        };
    });
}

Usage:

use App\Facades\McryptFacade;
$encrypted = McryptFacade::encrypt(MCRYPT_RIJNDAEL_128, $key, $data, MCRYPT_MODE_CBC, $iv);

Configuration Management:

Store encryption keys, IVs, and algorithms in Laravel’s config:

// config/mcrypt.php
return [
    'default_algorithm' => MCRYPT_RIJNDAEL_256,
    'default_mode' => MCRYPT_MODE_CBC,
    'key' => env('MCRYPT_KEY'),
];

Use the config in services:

$algorithm = config('mcrypt.default_algorithm');
$mode = config('mcrypt.default_mode');
$key = config('mcrypt.key');

Encryption Service Class: Encapsulate logic in a service for reusability:

// app/Services/EncryptionService.php
namespace App\Services;
use phpseclib\mcrypt_compat as mcrypt;
class EncryptionService {
    public function encrypt($data, $key = null) {
        $key = $key ?: config('mcrypt.key');
        $iv = mcrypt_create_iv(mcrypt_get_iv_size(config('mcrypt.default_algorithm'), config('mcrypt.default_mode')), MCRYPT_RAND);
        return mcrypt_encrypt(
            config('mcrypt.default_algorithm'),
            $key,
            $data,
            config('mcrypt.default_mode'),
            $iv
        );
    }
    public function decrypt($encrypted, $key = null) {
        $key = $key ?: config('mcrypt.key');
        return mcrypt_decrypt(
            config('mcrypt.default_algorithm'),
            $key,
            $encrypted,
            config('mcrypt.default_mode'),
            $iv // Must match the IV used during encryption
        );
    }
}

Usage:

$service = new \App\Services\EncryptionService();
$encrypted = $service->encrypt('Sensitive data');
$decrypted = $service->decrypt($encrypted);

Database Encryption: Use the polyfill to encrypt/decrypt database fields (e.g., with Laravel’s Attribute casting or accessors):

// app/Models/User.php
protected $casts = [
    'encrypted_data' => 'encrypted',
];
public function getEncryptedDataAttribute($value) {
    return \phpseclib\mcrypt_compat\mcrypt_decrypt(
        MCRYPT_RIJNDAEL_128,
        config('mcrypt.key'),
        $value,
        MCRYPT_MODE_CBC,
        $this->iv // Store IV alongside encrypted data
    );
}
public function setEncryptedDataAttribute($value) {
    $this->iv = mcrypt_create_iv(mcrypt_get_iv_size(MCRYPT_RIJNDAEL_128, MCRYPT_MODE_CBC), MCRYPT_RAND);
    $this->attributes['encrypted_data'] = mcrypt_encrypt(
        MCRYPT_RIJNDAEL_128,
        config('mcrypt.key'),
        $value,
        MCRYPT_MODE_CBC,
        $this->iv
    );
}

Workflows

Legacy System Migration:
- Step 1: Identify all mcrypt calls in the codebase using git grep or IDE search.
- Step 2: Replace each call with the polyfill (e.g., \phpseclib\mcrypt_compat\mcrypt_encrypt).
- Step 3: Test each module individually, starting with non-critical paths.
- Step 4: Update tests to account for behavioral differences (e.g., ncfb mode).

Third-Party Library Integration:

If a library expects the mcrypt extension, wrap its calls in a compatibility layer:

// app/Services/ThirdPartyLibraryService.php
public function processWithLegacyLib($data) {
    $encrypted = \phpseclib\mcrypt_compat\mcrypt_encrypt(
        MCRYPT_BLOWFISH,
        $this->key,
        $data,
        MCRYPT_MODE_CFB,
        $this->iv
    );
    return $legacyLibrary->process($encrypted); // Library expects mcrypt output
}

Performance Optimization:

Cache IVs or encrypted data where possible to reduce repeated calls to mcrypt_create_iv or encryption functions.

Example:

$cache = [];
$cacheKey = md5($data);
if (!isset($cache[$cacheKey])) {
    $cache[$cacheKey] = mcrypt_encrypt(MCRYPT_RIJNDAEL_128, $key, $data, MCRYPT_MODE_CBC, $iv);
}
return $cache[$cacheKey];

PHP Version Emulation:

For legacy systems requiring PHP 5.3 behavior, define the target version before autoloading:

// bootstrap/app.php or similar entry point
define('PHPSECLIB_MCRYPT_TARGET_VERSION', '5.3.0');
require __DIR__.'/vendor/autoload.php';

Integration Tips

Avoid Mixing with Native mcrypt:
- Ensure the polyfill is the only source of mcrypt functions. Remove extension=mcrypt from php.ini to prevent conflicts.
Handle IV Management:
- Store IVs securely alongside encrypted data (e.g., in a database or encrypted config). Never reuse IVs for the same key.
Error Handling:
- Wrap polyfill calls in try-catch blocks to handle edge cases (e.g., invalid keys, unsupported modes):
```
try {
    $decrypted = mcrypt_decrypt($algorithm, $key, $encrypted, $mode, $iv);
} catch
```

Mcrypt Compat Laravel Package