Weave Code
Laravel Ciphersweet Laravel Package
spatie/laravel-ciphersweet
Laravel wrapper for Paragonie CipherSweet that adds searchable field-level encryption to Eloquent models. Encrypt/decrypt sensitive attributes and generate blind indexes so you can query encrypted data securely without exposing readable values in your database.
Use Ciphersweet in your Laravel project
Frequently asked questions about Laravel Ciphersweet
- How do I encrypt sensitive fields in a Laravel Eloquent model using spatie/laravel-ciphersweet?
- Use the `CipherSweet::encrypt()` macro on your model’s attributes. For example, add `use HasCipherSweet;` to your model, then define `$casts = ['email' => CipherSweet::class]` in the model. The package automatically handles encryption/decryption during save/retrieve operations.
- Does this package support Laravel 10+? What are the minimum requirements?
- Yes, it’s fully compatible with Laravel 10, 9, and 8. The package requires PHP 8.0+ and the `ciphersweet` PHP extension (not bundled with PHP). Check the [README](https://github.com/spatie/laravel-ciphersweet) for exact version constraints and installation steps.
- Can I search encrypted fields (e.g., WHERE email LIKE '%@gmail.com') without decrypting them?
- Yes, via **blind indexes**. Configure deterministic encryption for searchable fields (e.g., `CipherSweet::deterministic()`), then use Laravel’s query builder as usual. The package generates encrypted indexes that enable plaintext-like queries without exposing sensitive data.
- What databases does spatie/laravel-ciphersweet support, and are there limitations?
- It works natively with **MySQL** and **PostgreSQL** (using `pgcrypto`/`AES`). **SQLite** is partially supported but requires custom logic for encrypted queries. Complex joins or aggregations on encrypted fields may need application-layer workarounds.
- How do I configure key management for production? Can I use AWS KMS or HashiCorp Vault?
- Yes, configure keys in `config/ciphersweet.php` with options like `'key_provider' => 'aws_kms'` or `'key_provider' => 'vault'`. For self-hosted keys, use `'key_provider' => 'local'` with secure storage (e.g., HSM or encrypted files). Always rotate keys via migrations or Laravel tasks.
- What’s the performance impact of encrypting fields? Will it slow down my queries?
- Encryption adds **~10–30ms per field** (benchmark-dependent). Deterministic encryption (for searchable fields) avoids repeated hashing, minimizing overhead. Test with production-like data volumes to assess latency, especially for high-traffic models.
- How do I migrate existing unencrypted data to encrypted fields without downtime?
- Use Laravel migrations to add `encrypted_*` columns, then run a batch job to re-encrypt data incrementally. For example, loop through records with `Model::chunk(200, fn($records) => $records->each->encryptSensitiveFields())`. Avoid locking tables during migration.
- Are there alternatives to spatie/laravel-ciphersweet for field-level encryption in Laravel?
- Yes, consider **laravel-encryption** (simpler but non-searchable) or **Tomb** (application-layer encryption). For searchable encryption, **CipherSweet** is the most mature PHP solution. Evaluate based on your need for blind indexes, key management, and database support.
- How do I test encrypted models in Laravel’s testing suite (Pest/PHPUnit)?
- Mock CipherSweet’s encryption/decryption in tests using Laravel’s `Mockery` or `Pest`. For example, stub the `encrypt()` method to return predictable values: `$this->partialMock(CipherSweet::class, function ($mock) { $mock->shouldReceive('encrypt')->andReturn('encrypted_value'); });`. Avoid testing actual encryption in unit tests.
- What happens if my encryption key is lost or corrupted? Can I recover encrypted data?
- If the key is lost, **encrypted data cannot be decrypted**—this is a security feature. Always back up keys securely (e.g., AWS KMS/Vault). For key rotation, use Laravel migrations to re-encrypt data with the new key. Monitor decryption failures via Laravel’s exception handling or logging.
Weaver
How can I help you explore Laravel packages today?