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 a sensitive field in a Laravel Eloquent model using spatie/laravel-ciphersweet?
- Use the `UsesCipherSweet` trait in your model and define encrypted fields with `addTextField()`, `addIntegerField()`, or `addBooleanField()`. For example, `addTextField('ssn', 128)` encrypts a Social Security number with a 128-bit key. The package handles encryption/decryption automatically during model persistence.
- Can I search encrypted fields in Laravel queries with this package?
- Yes, the package generates blind indexes for encrypted fields, allowing exact-match searches via `whereEncrypted()` or `orWhereEncrypted()`. For example, `Model::whereEncrypted('ssn', '123-45-6789')->get()`. Note that partial or fuzzy searches aren’t supported—only exact matches work.
- What Laravel versions does spatie/laravel-ciphersweet support?
- The package supports Laravel 9.x and 10.x. Check the [GitHub repo](https://github.com/spatie/laravel-ciphersweet) for the latest compatibility notes. Always pin the package version in `composer.json` to avoid breaking changes, as it depends on ParagonIE’s CipherSweet library.
- How do I configure key management for production?
- Use Laravel’s `.env` to set `CIPHERSWEET_KEY` (for development) or integrate with a secure key provider like AWS KMS or HashiCorp Vault. Key rotation is manual—re-encrypt data using the `ciphersweet:encrypt` Artisan command. Store offline backups of keys with strict access controls.
- What’s the performance impact of encrypting fields in Laravel?
- Encryption/decryption adds ~10–50ms per field (faster with the `nacl` backend). Blind index searches are slower (~100–500ms) due to cryptographic operations. Optimize by pre-defining indexes for common queries and avoiding compound indexes unless necessary. Test under load before production.
- Can I migrate existing encrypted data to this package?
- No, the package requires schema changes (new encrypted columns + blind_indexes table). Use the `ciphersweet:encrypt` command to batch-migrate data during low-traffic periods. Test with a replica database first, as re-encryption is resource-intensive.
- Are there alternatives to spatie/laravel-ciphersweet for Laravel encryption?
- For basic field encryption, Laravel’s built-in `encrypt()` works but lacks searchability. For advanced use cases, consider `tightenco/ziggy` (for URL signing) or `defuse/php-encryption` (for symmetric encryption). However, none offer searchable encryption like CipherSweet—this package is unique for GDPR/HIPAA compliance.
- How do I handle NULL values in encrypted fields?
- Optional fields (e.g., `addOptionalTextField()`) skip encryption for NULL values, which may cause inconsistencies. Use nullable migrations and application logic to enforce uniform handling. Document this behavior in your model’s comments to avoid runtime surprises.
- Does this package support FIPS 140-2 compliance?
- The default backends (`nacl`, `boring`) may not meet FIPS requirements. For compliance, implement a custom backend (e.g., using OpenSSL) or consult a cryptography expert. The package provides hooks to extend backends, but validation is your responsibility.
- How do I test encrypted queries in Laravel’s testing environment?
- Use Laravel’s `DatabaseTransactions` trait to roll back changes after tests. Mock blind index searches with `Model::whereEncrypted()` and verify results. Test edge cases like NULL values, special characters, and large payloads. The package includes unit tests as a reference.
Weaver
How can I help you explore Laravel packages today?