Weave Code
Laravel Ciphersweet Laravel Package
spatie/laravel-ciphersweet
A Laravel wrapper for CipherSweet that brings searchable field-level encryption to Eloquent models. Encrypt sensitive personal data so unauthorized DB access reveals nothing, while blind indexes let you search encrypted values securely.
Spatie Laravel CipherSweet wraps CipherSweet, Paragon Initiative's library for searchable field-level encryption, in a package purpose-built for Laravel. It lets you encrypt sensitive Eloquent attributes securely, so your application can still read them while an unauthorized person with database access cannot.
- Field-level encryption for sensitive model attributes
- Blind indexes enabling searches over encrypted data
- Indexes are unreadable by humans
- Easy integration with Laravel Eloquent models
Frequently asked questions about Laravel Ciphersweet
- How do I install spatie/laravel-ciphersweet in a Laravel application?
- Install it with composer require spatie/laravel-ciphersweet, then publish and run the blind_indexes migration and publish the package config file. Generate a key with php artisan ciphersweet:generate-key, add the CipherSweetEncrypted interface and UsesCipherSweet trait to your model, and implement configureCipherSweet. A pilot on one model is typically a one-to-two-day task plus review.
- How do I configure which Eloquent attributes are encrypted with CipherSweet?
- On each model, implement the CipherSweetEncrypted interface, use the UsesCipherSweet trait, and define a static configureCipherSweet(EncryptedRow $row) method. Inside that method you call the CipherSweet EncryptedRow API to add encrypted fields and any blind indexes. The package applies encryption and maintains blind indexes automatically when the model is saved.
- How do blind indexes work and how do I search encrypted columns with whereBlind?
- CipherSweet creates deterministic blind indexes that let you perform exact-match lookups without decrypting values or exposing plaintext. The package exposes whereBlind and orWhereBlind query scopes so you can filter encrypted columns through Eloquent instead of raw SQL. Indexes are unreadable by humans but leak equality by design, so choose indexed fields deliberately.
- Which Laravel and PHP versions does spatie/laravel-ciphersweet support?
- The package is a Laravel wrapper around paragonie/ciphersweet, so its exact Laravel and PHP constraints are defined in composer.json and can change between releases. Check Packagist or the repository for the current requirements before upgrading. Version 1.9.0 is additive and non-breaking over 1.8.x, so upgrading from 1.8.x is effectively zero-cost.
- How should I generate, store, and rotate the CipherSweet encryption key?
- Generate a key with php artisan ciphersweet:generate-key and avoid relying on the default string provider reading from .env for regulated production data. Key loss means irreversible data loss for encrypted columns, and key leakage means full plaintext exposure. For enterprise use, plug in a custom key provider backed by a KMS or HSM; rotation uses ciphersweet:encrypt with a new key and is a restartable per-model full-table rewrite, not an online re-key.
- Can I do partial matches, range queries, or sorting on encrypted columns?
- No. CipherSweet blind indexes are exact-match only, so there is no partial or LIKE search, no range query, no ordering, and no sorting by an encrypted column. If a roadmap item requires partial name search or sorting by date of birth, you need a separate derived or plaintext index with its own risk posture. Plan which fields you index and the index bit length deliberately.
- How do I validate unique encrypted values like email addresses?
- The package ships an EncryptedUniqueRule and a Rule::encryptedUnique() macro, which closes the common gap of unique email validation on encrypted columns. Use it in form requests or validators wherever you would normally use Laravel's unique rule. This avoids writing custom blind-index lookup code for the most common uniqueness case.
- How do I backfill and encrypt existing production data safely?
- Run the published blind_indexes migration, change encrypted columns to a text type where needed, and use php artisan ciphersweet:encrypt <Model> <key> to encrypt existing rows. The real work is rewriting every query path that filters on plaintext and coordinating the backfill on production data. Treat it as a planned migration with review, not just a Composer install.
- How do I test Eloquent models that use CipherSweet encryption?
- Use a test-only key with the string provider in your testing environment and run the blind_indexes migration in the test database. Because encryption is applied through the model trait, normal Eloquent factories and assertions still work, and you can add coverage for whereBlind query scopes. Keep production key custody out of tests so test runs never depend on a KMS or HSM.
- How does spatie/laravel-ciphersweet compare with Laravel's built-in encryption or other alternatives?
- Laravel's built-in encryption and encrypted casts protect values at rest but do not provide searchable blind indexes, so you cannot query encrypted columns efficiently. spatie/laravel-ciphersweet adds field-level searchable encryption on top of Paragonie CipherSweet, with Eloquent integration and exact-match blind indexes. It is a PII column hardening tool, not a replacement for full-database or at-rest encryption, and it does not protect against a compromised application server that holds the key.
Weaver
How can I help you explore Laravel packages today?