Laravel Encrypt Model Laravel Package

Getting Started

Minimal Steps

1. Installation Run composer require jetiradoro/laravel-encrypt-model in your project root. Publish the config (if needed) with php artisan vendor:publish --provider="Jetiradoro\EncryptModel\EncryptModelServiceProvider".

2. Basic Setup Add the Encryptable trait to your model and define $encryptable array with field names to encrypt:

   use Jetiradoro\EncryptModel\Encryptable;
   
   class User extends Model
   {
       use Encryptable;
   
       protected $encryptable = ['cc', 'ss', 'phone'];
   }
   

3. First Use Case Encrypt sensitive data on save:

   $user = new User();
   $user->cc = '1234567890'; // Automatically encrypted
   $user->save();
   

   Retrieve decrypted data:

   $user = User::find(1);
   $user->cc; // Automatically decrypted
   

Implementation Patterns

Usage Patterns

1. Selective Encryption Only encrypt specific fields (defined in $encryptable) while leaving others plaintext.

2. Mass Assignment Use fill() or create() with encrypted fields:

   User::create(['cc' => '1234567890', 'name' => 'John']); // 'cc' encrypted, 'name' plain
   

3. Querying Encrypted Fields Avoid querying encrypted fields directly. Use raw queries or decrypt first:

   // ❌ Avoid (encrypted values won't match)
   User::where('cc', '1234567890')->get();
   
   // ✅ Decrypt first (if needed)
   $users = User::all()->filter(fn($u) => decrypt($u->cc) === '1234567890');
   

4. API Responses Use $appends or API resources to control encrypted field exposure:

   class User extends Model
   {
       protected $encryptable = ['cc'];
       protected $appends = ['safe_cc'];
   
       public function getSafeCcAttribute()
       {
           return decrypt($this->cc); // Custom decryption logic
       }
   }
   

Workflows

1. Form Handling Use encrypt() helper in controllers/forms:

   $request->validate(['cc' => 'required']);
   $user->cc = encrypt($request->cc); // Manual override if needed
   

2. Migrations Store encrypted fields as text or longText (default) to avoid truncation:

   Schema::create('users', function (Blueprint $table) {
       $table->text('cc')->nullable(); // Recommended for encrypted data
   });
   

3. Testing Mock encryption in tests:

   $this->app->instance('encrypt', fn($value) => 'encrypted_' . $value);
   

Integration Tips

• Laravel Scout: Encrypted fields won’t work with full-text search. Exclude them from toSearchableArray().
• Laravel Cashier: Avoid encrypting card_last_four or card_brand if using Stripe.
• APIs: Document encrypted fields clearly in your API specs (e.g., Swagger/OpenAPI).

Gotchas and Tips

Pitfalls

1. Case Sensitivity $encryptable must match exactly with column names (including case) in the database.

   // ❌ Won't work (case mismatch)
   protected $encryptable = ['CC']; // Column is `cc`
   

2. Serialization Issues Encrypted fields may break serialization (e.g., Redis, cache). Exclude them:

   public function __serialize()
   {
       return [
           'data' => array_except($this->attributesToArray(), $this->encryptable),
           'encrypted' => array_only($this->attributesToArray(), $this->encryptable),
       ];
   }
   

3. Query Builder Conflicts Avoid using encrypt() in where clauses:

   // ❌ Fails (encrypt() is a helper, not a DB function)
   User::whereEncrypt('cc', '1234567890')->get();
   

4. Model Events Encryption runs during saving and retrieved. Override events carefully:

   protected static function bootEncryptable()
   {
       static::saving(function ($model) {
           // Custom logic before encryption
       });
   }
   

5. Database Indexes Encrypted fields cannot be indexed for search. Use plaintext fields for indexing.

Debugging

• Check Encryption: Log encrypted values to verify:

  dd($this->attributes['cc']); // Should show encrypted string
  

• Decryption Errors: Ensure APP_KEY is set in .env (encryption uses Laravel’s default cipher).
• Performance: Avoid encrypting large fields (e.g., description). Use text columns for encrypted data.

Tips

1. Exclude Sensitive Metadata Add encrypted fields to $hidden or $visible:

   protected $hidden = ['cc', 'ss'];
   

2. Custom Encryption Override the cipher in config/encrypt-model.php:

   'cipher' => 'AES-256-CBC',
   'key' => env('ENCRYPTION_KEY'), // Custom key
   

3. Partial Encryption Dynamically set $encryptable per instance:

   public function setEncryptable(array $fields)
   {
       $this->encryptable = $fields;
   }
   

4. Fallback for Older Laravel If using Laravel < 5.7, manually add the service provider to config/app.php:

   'providers' => [
       Jetiradoro\EncryptModel\EncryptModelServiceProvider::class,
   ],
   

5. Backup Encryption Key Store APP_KEY securely. Losing it means permanent data loss for encrypted fields.