Laravel Crypto Laravel Package

Getting Started

Install the package via Composer (check Packagist for the exact vendor/package name; the repository is MalusevDevelopment/laravel-crypto). Publish the configuration file:

php artisan vendor:publish --provider="MalusevDevelopment\LaravelCrypto\CryptoServiceProvider"

Set your encryption key(s) in .env (e.g., LARAVEL_CRYPTO_KEY) and review config/crypto.php for cipher and key settings. For the new per‑user encryption feature (v3.0.0‑alpha1), you’ll likely need to configure a user resolver or set the current user context before encrypting/decrypting.

First use case: Encrypt a model attribute using the provided cast or trait. For example, add use Encryptable; to a model and list encrypted attributes, or use the Crypto facade directly:

use MalusevDevelopment\LaravelCrypto\Facades\Crypto;

$encrypted = Crypto::encrypt('secret');
$plain = Crypto::decrypt($encrypted);

For per‑user encryption, set the user context (e.g., Crypto::forUser($user)) before calling encrypt/decrypt, so each user’s data is encrypted with a key derived from their identity.

Implementation Patterns

Attribute encryption via casts. Use the package’s encrypted cast on Eloquent models to transparently encrypt/decrypt on save and retrieve. This is the most common day‑to‑day pattern for sensitive fields like API tokens, personal data, or notes.

Per‑user encryption (v3 alpha). Isolate data per user by deriving keys from a user identifier. Typical workflow:

• Resolve the current user (e.g., via Auth::user() or an explicit forUser($id) call).
• Encrypt data with that user’s context before storage.
• Decrypt only when the same user context is active. This is useful for multi‑tenant apps, user‑specific secrets, or compliance scenarios where data must be cryptographically separated.

Key rotation and multiple keys. Configure multiple keys with version prefixes or a key ring. When encrypting, use the latest key; when decrypting, detect the key version from the ciphertext and use the corresponding key. This enables smooth rotation without downtime.

Integration with queues and jobs. Encryption/decryption that depends on the current user context must have that context restored in queued jobs. Pass the user ID (or a serializable user reference) to the job and re‑establish the context before decrypting.

Service layer usage. Wrap encryption in a dedicated service or repository so you can swap implementations, centralise key management, and add logging/auditing without scattering Crypto:: calls across controllers.

Migration strategy. When introducing encryption to existing columns, write a one‑off command that reads plaintext, encrypts it, and writes back. For per‑user encryption, ensure the user context matches the data owner during migration.

Gotchas and Tips

• Alpha stability: v3.0.0‑alpha1 is pre‑release. APIs may change, and per‑user encryption is brand new. Pin the version in composer.json and avoid using it in production without thorough testing.
• User context consistency: Per‑user encryption fails if the user identifier changes (e.g., user ID reassignment, merging accounts). Plan for key rotation or re‑encryption when user identity changes.
• Key storage: Never commit keys. Use environment variables or a secrets manager. For per‑user keys, ensure the derivation salt/pepper is stored securely and backed up.
• Performance: Encryption/decryption adds CPU overhead. For large payloads or high‑traffic endpoints, consider caching decrypted values in memory for the request lifecycle, or encrypting only the most sensitive fields.
• Debugging decryption failures: Common causes are wrong user context, missing key version, corrupted ciphertext, or a changed cipher configuration. Log the key identifier (not the key itself) with each ciphertext to simplify troubleshooting.
• Migration from v2: Review the changelog for breaking changes. The per‑user encryption feature may alter default behaviour or configuration keys. Run the test suite and test with real data in a staging environment.
• Extension points: The package likely allows custom key resolvers, cipher drivers, or user context resolvers. Use these to integrate with your existing user model or key management system rather than forking.
• Config quirks: Double‑check the default cipher and key encoding. Laravel’s own APP_KEY is separate; this package may use its own key. Ensure the config is cached correctly (php artisan config:cache) after changes.