Getting Started

Install with composer require maize-tech/laravel-encryptable. Version 4.1.0 adds support for Laravel 13 and PHP 8.5; no breaking changes from 4.0.0.
Add the package’s Encryptable trait to any Eloquent model that needs transparent attribute encryption.
Declare which attributes should be encrypted, typically via a protected $encryptable array (check the README for the exact property name in your version).
First use case: protect sensitive columns such as API tokens, national IDs, or personal data without writing manual Crypt::encryptString() / decryptString() calls in every model.
Where to look first: the package README for trait name and configuration, then your model’s existing casts/accessors to avoid conflicts. Run a quick tinker test: create a model, set an encrypted attribute, save, and inspect the raw database value to confirm ciphertext.

Implementation Patterns

Trait + attribute list: Add the trait and list encrypted columns. The package handles encryption on write and decryption on read, so your application code continues to use plain values.
Migrations: Store encrypted values in TEXT or larger columns. Ciphertext is substantially longer than plaintext; VARCHAR(255) is often too small for anything beyond short strings.
Searchable fields: Encrypted columns cannot be queried with normal where clauses because ciphertext differs per row (random IV). For lookup fields, store a deterministic hash (e.g. hash('sha256', $value)) in a separate indexed column and query that.
Factories and seeders: Assign plain values as usual; the trait encrypts on save. Be aware that ->create() followed by direct DB assertions will show ciphertext.
Serialization: Decrypted values are typically returned when the model is serialized to array/JSON. Review $hidden and $visible to avoid leaking sensitive data through APIs.
Key rotation: Encrypted attributes use Laravel’s application key. Rotating APP_KEY without re-encrypting existing rows will make old data unreadable. Plan a migration or re-save strategy if rotation is required.
Coexistence with Laravel casts: If you already use Laravel’s built-in encrypted cast, do not also include the same attribute in the package’s encryptable list—double encryption will break reads. Choose one approach per attribute.

Column length: The most common failure is a “data too long” error after enabling encryption. Always widen columns before rolling out to existing data.
No where on encrypted columns: Queries like where('ssn', $value) will silently return no results. Use a hash column for equality searches, or decrypt in PHP for small datasets.
Debugging: If a value looks like ciphertext in your app, check that the trait is applied and the attribute is listed. You can manually verify with Crypt::decryptString($raw) in tinker.
Config quirks: The package may publish a config file for custom encryptors or key handling. Publish and review it only if you need non-default behaviour; most apps work with the default Laravel encrypter.
Extension points: Look for a configurable encrypter or trait methods you can override if you need custom serialization (e.g. encrypting JSON arrays). Override carefully and keep decryption symmetrical.
Performance: Each encrypted attribute adds encryption/decryption overhead per model hydration. Avoid encrypting large text blobs or high-volume columns unless necessary.
Laravel 13 / PHP 8.5: 4.1.0 is the first release supporting these. If you are still on older Laravel/PHP versions, stay on 4.0.x until you upgrade. The Dependabot bump in this release is CI-only and does not affect runtime behaviour.