erikwang2013/encryptable

Languages: English (this page) | 简体中文

Encryptable (erikwang2013/encryptable)

On PHP 8.0+ (dev toolchain: 8.2+), this package helps you anonymize / encrypt sensitive attributes in a query-friendly way: values are encrypted before persistence and decrypted when read through Eloquent (or manual APIs). It can also emit MySQL / PostgreSQL-compatible SQL fragments so you can compare or search against encrypted columns in raw queries. Frameworks are optional — the same two crypto paths run in plain native PHP via Encryption::configure() or environment variables.

This repository evolves from the ideas and behaviour of laravel-encryptable (Maize Tech). For the original design, issues, and releases, refer to that upstream project.

Project overview

What this package solves

Applications that handle personally identifiable information (PII), health records, financial data, or secrets often need to store those values encrypted at rest — not just hashed or masked — while keeping the ability to query by the original value (unique checks, existence lookups). Pure-encryption libraries leave you to implement the persistence layer yourself; ORM-only solutions lock you into one framework. This package bridges both gaps.

Core design

• Dual crypto path — Encryption::php() for application-level encrypt/decrypt (OpenSSL, the same path Eloquent casts use), and Encryption::db() for generating SQL fragments that decrypt inside the database engine. The two paths share the same key and cipher config.
• Authenticated encryption by default — the default cipher aes-256-gcm provides confidentiality and integrity via AEAD. If deterministic encryption is needed (required for UniqueEncrypted / ExistsEncrypted validation rules), switch to aes-128-ecb (identical plaintext → identical ciphertext) or another non-AEAD cipher.
• Container-agnostic resolution — Encryption::resolve() probes Hyperf, Laravel, and a user-supplied PSR-11 container; when none is available it falls back to Encryption::configure([...]), then to the ENCRYPTION_KEY / ENCRYPTION_CIPHER env vars. Framework bridges exist for Laravel 10–12, Webman (Illuminate), Hyperf 2–3, and ThinkPHP 6–8; plain PHP needs no bridge at all.
• Zero-downtime key rotation — a primary key + previous_keys ring lets you rotate secrets without a big-bang re-encrypt. rotateToCurrentKey() provides gradual ciphertext migration under live traffic.

What this fork adds (beyond upstream laravel-encryptable)

When to use (and when not to)

Project pet: Locky · 小锁灵

Locky is the pet of this package, and it is drawn from the design rather than bolted onto it: the amber key on its ring is the current primary key, and the two grey keys are previous_keys — still on the ring, still able to decrypt old ciphertext, until you retire them. That is the key-rotation model below, as a mascot.

It ships as part of the code, not only as documentation:

use Erikwang2013\Encryptable\Encryption;

echo Encryption::mascot();   // SVG markup for an admin page or error screen

Purely decorative: no pet method touches keys, ciphers or payloads.

Features

• Eloquent custom cast: use Encryptable::class in $casts for transparent encrypt/decrypt on attributes.
• PHP-side crypto: Encryption::php()->encrypt() / decrypt() for CLI, queues, or non-model code paths.
• DB expressions: Encryption::db()->decrypt() returns a SQL snippet (MySQL vs Postgres branches) suitable for whereRaw-style comparisons against stored ciphertext.
• Validation: UniqueEncrypted, ExistsEncrypted, and Rule::uniqueEncrypted() / Rule::existsEncrypted() macros (requires illuminate/validation).
• Multi-runtime bridges + native PHP: Laravel 10–12, Illuminate-based Webman, Hyperf 2–3, and ThinkPHP 6–8 each register container/config in their own way. With no framework at all, Encryption::configure(['key' => …]) or the env vars ENCRYPTION_KEY, ENCRYPTION_CIPHER, optional ENCRYPTION_PREVIOUS_KEYS and ENCRYPTION_DB_DRIVER drive both Encryption::php() and Encryption::db() (see Supported frameworks → Native PHP).
• Composer install hook: this package is a Composer plugin; on composer require / composer update, it inspects vendor/composer/installed.php, lock, manifest, and project layout to publish config for the stack in use (see Installation → Composer plugin).
• Key rotation (Encryption::php() only): primary + previous_keys / ENCRYPTION_PREVIOUS_KEYS decryption ring, optional rotateToCurrentKey() for gradual re-encryption — full behavior and rollout are documented under Configuration → Key rotation.

Architecture

Every entry point — the Eloquent cast, a validation rule, or a manual Encryption::php() call — goes through the same static facade. The facade resolves a PHPEncrypter (application-level AEAD) or a DBEncrypter (deterministic ciphertext plus SQL decrypt fragments) from the framework container, or from environment variables when no container is available. Bridges only provide config and container bindings: the crypto core itself has no framework dependency (runtime require is just php, ext-openssl, psr/container).

Lifecycle

• Data — write and read are strictly symmetric: serialize → dirty bit → random IV + AEAD → HMAC → base64 on the way in, and the exact reverse on the way out. Any key still on the ring can decrypt.
• Query — only deterministic ciphers (aes-*-ecb) can be compared inside the database engine; fuzzy and range lookups never work against ciphertext, whatever the cipher.
• Key rotation — a key walks pending → primary → previous_keys → retired. Rollback is safe at any step while the old key is still on the ring.

Project structure

encryptable/
├── src/
│   ├── Encryption.php                  # static facade: php() · db() · isEncrypted() · rotateToCurrentKey() · mascot()
│   ├── Encrypter.php                   # abstract base: key/cipher validation, decryption key ring
│   ├── PHPEncrypter.php                # application path: AEAD + HMAC, random IV, \x01/\x02 payload formats
│   ├── DBEncrypter.php                 # DB path: deterministic AES-ECB + SQL decrypt fragments
│   ├── Encryptable.php                 # Eloquent cast (CastsAttributes)
│   ├── EncryptableServiceProvider.php  # Laravel/Webman provider: publishes config, registers validation macros
│   ├── Config/                         # ArrayEncryptableConfig · EnvEncryptableConfig · EnvDbDriverDetector (native PHP)
│   ├── Contracts/                      # EncryptableConfigContract · DbDriverDetector
│   ├── Exceptions/                     # Decrypt · Encrypt · MissingKey · MissingCipher · (Un)Serialization
│   ├── Rules/                          # UniqueEncrypted · ExistsEncrypted
│   ├── Support/                        # PackagePluginPaths · PreviousKeysParser · Mascot (the pet)
│   ├── Utils/Serializer.php            # serialization envelope shared by both encrypters
│   ├── Bridge/
│   │   ├── Laravel/                    # Illuminate config + DB driver detector
│   │   ├── Webman/                     # native Webman plugin config reader
│   │   ├── Hyperf/                     # ConfigProvider, config, DB driver detector
│   │   └── ThinkPHP/                   # ThinkphpEncryptable::register(), config, PSR-11 adapter
│   └── Composer/Plugin.php             # install/update hook: publishes config for the detected stack
├── config/
│   ├── encryptable.php                 # legacy flat config (still merged)
│   └── stubs/                          # plugin-app · webman-plugin-app · hyperf-plugin-autoload · hyperf-autoload-encryptable
├── docs/
│   ├── pet.svg                         # Locky · 小锁灵 — the project pet
│   ├── architecture.svg                # architecture diagram
│   ├── features.svg                    # feature design
│   ├── lifecycle.svg                   # value / query / key-rotation lifecycles
│   └── README.zh-CN.md                 # Chinese README
├── tests/                              # 19 PHPUnit test classes (cast, encrypters, key ring, bridges, native PHP, rules, config)
├── .github/workflows/                  # ci.yml (PHP 8.2–8.4 + PHP 8.0 syntax check) · release.yml
├── composer.json                       # composer-plugin entry point + framework metadata
├── phpstan.neon.dist · phpunit.xml
└── README.md

Requirements

Packagist: erikwang2013/encryptable (name in composer.json).

Supported frameworks

The table below summarizes expected compatibility, how to wire the package, and which features are Laravel-specific (Eloquent cast, illuminate/validation rules). Pin versions in your own project as needed. Config files are installed automatically by the Composer plugin when allowed (see Installation); you can still copy or vendor:publish manually if you prefer.

Legend: ✓ = supported for this stack out of the box; — = not provided; integrate in your own layer.

Native PHP (no framework, no container)

The package has no runtime dependency on any framework: require is only php, ext-openssl and psr/container. Point it at a key and it works — either from the environment or from an array.

use Erikwang2013\Encryptable\Encryption;

// Option A — environment (12-factor style), nothing to configure in code:
//   ENCRYPTION_KEY=<32 bytes for aes-256-*>
//   ENCRYPTION_CIPHER=aes-256-gcm
//   ENCRYPTION_PREVIOUS_KEYS='old-key-1,old-key-2'   # optional
//   ENCRYPTION_DB_DRIVER=mysql|pgsql                 # optional, for Encryption::db()

// Option B — one array, no env vars, no config file:
Encryption::configure([
    'key' => $_ENV['APP_KEY'],              // 32 bytes for aes-256-*, 16 bytes for aes-128-*
    'cipher' => 'aes-256-gcm',              // default when omitted
    'previous_keys' => ['2025-key'],        // optional decryption ring
    'db_driver' => 'pgsql',                 // optional: MySQL/PostgreSQL SQL fragment dialect
]);

$ciphertext = Encryption::php()->encrypt($value);      // application path (AEAD + HMAC)
$plain      = Encryption::php()->decrypt($ciphertext);
$sql        = Encryption::db()->decrypt('phone');      // SQL fragment, dialect from db_driver/PDO/env

Notes for the native path:

• Encryption::configure() only fills the fallback slot. Container bindings and Encryption::setResolver() still win, so calling it inside Laravel/Hyperf changes nothing.
• Encryption::db() probes the dialect in this order: db_driver from configure() → ENCRYPTION_DB_DRIVER → a PDO connection you pass to new EnvDbDriverDetector(null, $pdo) → MySQL as the default.
• Payload types follow the serialization envelope: string, int, float, bool, null ($serialize = true, the default). With $serialize = false pass a scalar or a Stringable — arrays and objects throw SerializationException instead of a raw TypeError.
• Encryption::isEncrypted() recognises the application-level payload format only (\x01/\x02 prefix); DB-format ciphertext is checked by the DB encrypter internally.
• Failed decryption is not fatal by default: decrypt() returns the input unchanged unless you pass $strict = true (rotateToCurrentKey() is always strict).

Installation

composer require erikwang2013/encryptable

Composer plugin (auto-publish config)

This package has "type": "composer-plugin" and registers Erikwang2013\Encryptable\Composer\Plugin. After install or update of erikwang2013/encryptable, Composer runs the plugin, which:

1. Collects Composer package names (lowercased) from, in order: vendor/composer/installed.php (and installed.json if present), composer.lock, then root composer.json require / require-dev. This matches what is actually installed in vendor/, including transitive Webman / Hyperf packages that never appear in your root composer.json.
2. Adds filesystem hints when needed (e.g. Webman: support/bootstrap.php, start.php, or windows.php plus config/; Laravel: artisan + bootstrap/app.php or app/Http/Kernel.php; Hyperf: bin/hyperf.php or config/autoload/server.php; ThinkPHP: executable think file in the project root).
3. Publishes files only when a supported framework is detected (see table). Existing target files are never overwritten.
4. If nothing matches, it prints a skip notice so plain PHP projects are not modified.

Laravel / Lumen / ThinkPHP / Webman share the same config/plugin/erikwang2013/encryptable/app.php template (config/stubs/plugin-app.php). Hyperf uses config/autoload/plugins/erikwang2013/encryptable.php when neither that file nor the legacy config/autoload/encryptable.php exists yet (legacy installs keep working; HyperfEncryptableConfig reads the plugin path first, then encryptable.*). If multiple stacks match (e.g. a monorepo), every applicable file is created when missing.

Composer 2.2+ may block plugins until you allow them. Add this to your application composer.json (once), then run composer require again if needed:

"config": {
    "allow-plugins": {
        "erikwang2013/encryptable": true
    }
}

Or approve the prompt Composer shows when requiring the package.

Configuration files (manual copy, optional)

If the plugin is blocked or you manage config in VCS templates yourself, copy the matching template from this package into the path your framework expects, then adjust .env as needed.

Note: plugin-app.php is the shared stub (top-level key, cipher). Webman reads it natively as plugin.erikwang2013.encryptable.app.*. Laravel / Lumen merge it into encryptable.*. ThinkPHP loads it in ThinkphpEncryptable::register into encryptable.*. Hyperf autoload files are keyed by path: the recommended file maps to plugins.erikwang2013.encryptable.*; the legacy filename encryptable.php maps to encryptable.*.

Shell examples:

# Laravel / Lumen / ThinkPHP / Webman (shared plugin layout)
mkdir -p config/plugin/erikwang2013/encryptable
cp vendor/erikwang2013/encryptable/config/stubs/plugin-app.php config/plugin/erikwang2013/encryptable/app.php

# Hyperf (recommended)
mkdir -p config/autoload/plugins/erikwang2013
cp vendor/erikwang2013/encryptable/config/stubs/hyperf-plugin-autoload.php config/autoload/plugins/erikwang2013/encryptable.php

Laravel alternative (vendor:publish publishes the plugin file, optional legacy flat file, and the Hyperf stub path for convenience):

php artisan vendor:publish --provider="Erikwang2013\Encryptable\EncryptableServiceProvider" --tag="encryptable-config"

Laravel (remaining steps)

With package auto-discovery enabled, Erikwang2013\Encryptable\EncryptableServiceProvider is registered. Ensure config/plugin/erikwang2013/encryptable/app.php exists (Composer plugin or Laravel row / vendor:publish), or keep a legacy config/encryptable.php only.

Webman (with Illuminate)

Install illuminate/database, illuminate/support, illuminate/validation, etc. as needed. Ensure the plugin config exists at config/plugin/erikwang2013/encryptable/app.php (the Composer plugin or vendor:publish creates it). Then register:

Erikwang2013\Encryptable\EncryptableServiceProvider

in your plugin/bootstrap code. Runtime reads config('plugin.erikwang2013.encryptable.app.key') and .cipher, per Webman plugin config rules.

Hyperf

1. Copy or auto-install config per the Hyperf row (config/autoload/plugins/erikwang2013/encryptable.php, or legacy config/autoload/encryptable.php). Values are read as plugins.erikwang2013.encryptable.key / .cipher, with fallback to encryptable.*.
2. This package declares Erikwang2013\Encryptable\Bridge\Hyperf\ConfigProvider under composer.json → extra.hyperf.config for Hyperf to merge.
3. For Encryption::db(), install hyperf/db-connection.

ThinkPHP

1. Prefer config/plugin/erikwang2013/encryptable/app.php (same stub as Webman/Laravel). Legacy config/encryptable.php still works if you do not use the plugin path.
2. During application bootstrap (e.g. service registration), call:

\Erikwang2013\Encryptable\Bridge\ThinkPHP\ThinkphpEncryptable::register($app);

Configuration

After copying or publishing config/plugin/erikwang2013/encryptable/app.php, legacy config/encryptable.php, or Hyperf’s config/autoload/plugins/erikwang2013/encryptable.php / config/autoload/encryptable.php, the main keys are:

Without Laravel / bindings, Encryption::php() can still read ENCRYPTION_KEY, ENCRYPTION_CIPHER, and ENCRYPTION_PREVIOUS_KEYS via EnvEncryptableConfig.

Key rotation (elegant zero-downtime)

You can change the primary encryption key without taking the app offline for a big-bang re-encrypt: new data is sealed with the new primary; existing rows keep decrypting as long as the key that produced them still appears in the configured ring (primary or previous_keys).

Behavior summary (what this package implements)

Recommended rollout (operations)

1. Set the new secret as ENCRYPTION_KEY (primary). Move the old primary into ENCRYPTION_PREVIOUS_KEYS (or previous_keys in config). Prefer listing the most recently retired key first among several retirees.
2. Deploy — reads succeed because decrypt walks the ring until a key yields valid package plaintext.
3. Optionally run a background job that loads each encrypted field and calls Encryption::php()->rotateToCurrentKey($ciphertext) (with the same $serialize flag your data used) so ciphertext gradually moves to the new primary; then traffic no longer depends on old keys.
4. Remove an entry from previous_keys only after you are sure no row still encrypted with that key remains (or you accept those rows becoming unreadable).

Configuration surface

Multiple previous keys (how to configure)

Decrypt order is always: current primary ENCRYPTION_KEY first, then previous_keys in list order (put the key you retired most recently before older ones, so the common “last rotation” case is tried early).

1 — Environment variable (several retirees)

• Comma-separated (no spaces required, but trims are applied):

ENCRYPTION_PREVIOUS_KEYS=oldKeyOne16bytes!!,olderKeyTwo16byte,ancientKeyThree16b

• JSON array (one line in .env; use this if a key might contain a comma):

ENCRYPTION_PREVIOUS_KEYS=["oldKeyOne16bytes!!","olderKeyTwo16byte","ancientKeyThree16b"]

2 — Laravel / ThinkPHP merged config (encryptable.previous_keys)

PHP array (same order semantics as above). Each string must match the same length OpenSSL expects for your cipher (e.g. aes-256-gcm typically uses a 32-byte secret string).

'previous_keys' => [
    'oldKeyOne16bytes!!',
    'olderKeyTwo16byte',
    'ancientKeyThree16b',
],

Or reuse the parser from env in config/encryptable.php / plugin app.php (already the default): PreviousKeysParser::parse(env('ENCRYPTION_PREVIOUS_KEYS')).

3 — Webman plugin app.php / Hyperf autoload

Use the same previous_keys key as in the stubs: either a PHP array as above, or PreviousKeysParser::parse(env('ENCRYPTION_PREVIOUS_KEYS')).

Usage

1. Model cast (Laravel / Webman with Eloquent)

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Erikwang2013\Encryptable\Encryptable;

class User extends Model
{
    protected $fillable = ['name', 'email'];

    protected $casts = [
        'name' => Encryptable::class,
        'email' => Encryptable::class,
    ];
}

Attributes are encrypted/decrypted automatically on read/write.

2. Manual encrypt/decrypt (PHP)

use Erikwang2013\Encryptable\Encryption;

$plain = 'value to protect';
$cipher = Encryption::php()->encrypt($plain);

$restored = Encryption::php()->decrypt($cipher);

3. SQL decrypt expression (DB)

use Erikwang2013\Encryptable\Encryption;

// Fragment usable in SELECT / WHERE (syntax differs for MySQL vs Postgres)
$expr = Encryption::db()->decrypt($encryptedPayloadFromDb);

DBEncrypter::encrypt() throws “not supported”; this path targets SQL-side decrypt/compare scenarios.

4. Custom validation rules

use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rule;
use Erikwang2013\Encryptable\Rules\ExistsEncrypted;
use Erikwang2013\Encryptable\Rules\UniqueEncrypted;

Validator::make($data, [
    'email' => [
        'required',
        'email',
        new ExistsEncrypted('users'),
        // or Rule::existsEncrypted('users')
    ],
]);

Validator::make($data, [
    'email' => [
        'required',
        'email',
        new UniqueEncrypted('users'),
        // or Rule::uniqueEncrypted('users')
    ],
]);

Composer / dependencies

• Runtime require: only php, ext-openssl, and psr/container, so Hyperf projects are not forced to pull all of Illuminate.
• Laravel / Webman (Illuminate): satisfy EncryptableServiceProvider, casts, and rules via laravel/framework or the suggested illuminate/* packages (see composer.json → suggest).

Development

composer install
composer test        # Pest
composer analyse     # PHPStan (requires local config)
composer format      # Laravel Pint

References & credits

• Upstream reference: maize-tech/laravel-encryptable — canonical design, issues, and community discussion for the original Laravel package.
• This fork extends multi-framework bridges, Composer metadata, and config/container resolution; compare CHANGELOG and config when migrating from upstream.

开源不易，欢迎支持

License

MIT. See LICENSE.md.