richardstyles/eloquent-aes

A Laravel Eloquent package to allow for model attribute encryption, using a seperate key

v3.0.0 2026-02-24 20:12 UTC

Requires

• php: ^8.2|^8.3|^8.4|^8.5
• illuminate/encryption: ^12.0|^13.0

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.18
• orchestra/testbench: ^10.0|^11.0
• pestphp/pest: ^3.0
• pestphp/pest-plugin-laravel: ^3.0

MIT

• Richard Styles

README

This package enables an additional layer of security when handling sensitive data. Allowing key fields of your eloquent models in the database to be encrypted at rest using AES-256-CBC.

Introduction

This package allows for your Eloquent Encryption to be encrypted using a different AES-256-CBC key. This allows for your regular app:key to be rotated. If you're looking for 4096-RSA encruption then this package RichardStyles/EloquentEncryption

Installation

This package requires Laravel 12.x or higher.

You can install the package via composer:

composer require richardstyles/eloquent-aes

If you wish to change the key cipher then you will need to publish the config.

php artisan vendor:publish --provider="RichardStyles\EloquentAES\EloquentAESServiceProvider" --tag="config"

To create an Eloquent encryption key, just as you would an app key. This will automatically add to the bottom of your .env file.

php artisan key:eloquent

⚠️ Please don't forget to back up your eloquent key

If you re-run this command, you will lose access to any encrypted data!

Graceful Key Rotation

Laravel 11+ introduced graceful encryption key rotation, and this package extends that feature! When rotating your encryption key, you can specify your previous keys to maintain access to data encrypted with old keys.

Setting Up Previous Keys

Add your previous encryption keys to your .env file as a comma-separated list:

ELOQUENT_KEY="base64:J63qRTDLub5NuZvP+kb8YIorGS6qFYHKVo6u7179stY="
ELOQUENT_PREVIOUS_KEYS="base64:2nLsGFGzyoae2ax3EF2Lyq/hH6QghBGLIq5uL+Gp8/w=,base64:oldkey123..."

How It Works

• Encryption: Always uses the current ELOQUENT_KEY
• Decryption: Tries the current key first, then falls back to previous keys in order
• No Downtime: Users can access data encrypted with any key during rotation

This allows you to rotate your encryption keys without disrupting your users or losing access to encrypted data!

Usage

This package leverages Laravel's own custom casting to encode/decode values.

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use RichardStyles\EloquentAES\Casts\AESEncrypted;
use RichardStyles\EloquentAES\Casts\AESEncryptedCollection;
use RichardStyles\EloquentAES\Casts\AESEncryptedObject;

class SalesData extends Model
{
    /**
     * The attributes that should be cast.
     *
     * @var array
     */
    protected $casts = [
        'private_data' => AESEncrypted::class,
        'private_collection' => AESEncryptedCollection::class,
        'private_object' => AESEncryptedObject::class,
    ];
}

There are additional casts which will cast the decrypted value into a specific data type. If there is not one that you need, simply make a PR including sufficient testing.

Using encryptUsing() for Model-Level Encryption

Laravel allows you to specify which encrypter instance a model should use via the encryptUsing() method. This is useful when you want all encrypted attributes on a model to use the AES encrypter instead of Laravel's default encrypter:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use RichardStyles\EloquentAES\EloquentAESFacade;

class User extends Model
{
    /**
     * The attributes that should be encrypted.
     *
     * @var array
     */
    protected $casts = [
        'ssn' => 'encrypted',
        'credit_card' => 'encrypted',
        'address' => 'encrypted:array',
        'preferences' => 'encrypted:collection',
        'metadata' => 'encrypted:object',
    ];

    /**
     * Get the encrypter instance that should be used to encrypt attributes.
     */
    public static function encryptUsing()
    {
        return EloquentAESFacade::getFacadeRoot();
    }
}

With this approach, all encrypted casts will automatically use the AES-256-CBC key instead of your app key. You can use Laravel's built-in encrypted casts without needing to specify the custom cast classes.

Testing

composer test

Code Style

This package uses Laravel Pint for code style formatting.

To automatically fix code style issues:

composer lint

To check for code style issues without fixing them:

composer lint-test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Support

If you are having general issues with this package, feel free to contact me on Twitter.

If you believe you have found an issue, please report it using the GitHub issue tracker, or better yet, fork the repository and submit a pull request with a failing test.

If you're using this package, I'd love to hear your thoughts. Thanks!

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

Credits

• Richard Styles
• All Contributors

License

The MIT License (MIT). Please see License File for more information.