Legacy Encrypter Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laravel/legacy-encrypter
   

   Add to config/app.php under providers:

   Laravel\LegacyEncrypter\LegacyEncrypterServiceProvider::class,
   

2. Configuration: Update config/app.php to use the legacy encrypter in encrypter:

   'encrypter' => \Laravel\LegacyEncrypter\LegacyEncrypter::class,
   

   Ensure APP_KEY in .env is set to a 32-character base64-encoded string (legacy mcrypt requirement).

3. First Use Case: Encrypt/decrypt legacy data during migrations or legacy system integration:

   use Laravel\LegacyEncrypter\LegacyEncrypter;
   
   $legacyEncrypter = new LegacyEncrypter(config('app.key'));
   $encrypted = $legacyEncrypter->encrypt('sensitive_data');
   $decrypted = $legacyEncrypter->decrypt($encrypted);
   

Implementation Patterns

Legacy Data Migration

• Workflow:
  1. Use LegacyEncrypter to decrypt old mcrypt-encrypted data during database migrations.
  2. Re-encrypt with Laravel’s default encrypter (Illuminate\Encryption\Encrypter) for future compatibility.

  public function up()
  {
      DB::table('legacy_data')->each(function ($item) {
          $legacyEncrypter = new LegacyEncrypter(config('app.key'));
          $decrypted = $legacyEncrypter->decrypt($item->encrypted_field);
          $newEncrypted = app('encrypter')->encrypt($decrypted);
          DB::table('legacy_data')->where('id', $item->id)->update(['encrypted_field' => $newEncrypted]);
      });
  }
  

Hybrid Encryption (Legacy + Modern)

• Pattern: Use both encrypters in tandem for systems requiring backward compatibility.

  $legacyEncrypter = new LegacyEncrypter(config('app.key'));
  $modernEncrypter = app('encrypter');
  
  // Decrypt legacy, encrypt modern
  $data = $legacyEncrypter->decrypt($legacyData);
  $modernData = $modernEncrypter->encrypt($data);
  

API Legacy Endpoints

• Use Case: Expose endpoints that accept/return legacy-encrypted payloads.

  Route::post('/legacy-api', function (Request $request) {
      $legacyEncrypter = new LegacyEncrypter(config('app.key'));
      $decrypted = $legacyEncrypter->decrypt($request->encrypted_data);
      // Process $decrypted
      return response()->json(['data' => $legacyEncrypter->encrypt($responseData)]);
  });
  

Testing

• Mock Legacy Encrypter in tests:

  $this->app->instance(
      \Laravel\LegacyEncrypter\LegacyEncrypter::class,
      Mockery::mock(LegacyEncrypter::class)
  );
  

Gotchas and Tips

Pitfalls

1. Key Length:

   • Legacy encrypter requires a 32-character base64 key (mcrypt’s MCRYPT_RIJNDAEL_256).
   • Modern Laravel keys (e.g., openssl random -base64 32) may not work. Generate a legacy-compatible key:

     openssl rand -base64 32 | cut -c1-32
     

2. Algorithm Limitations:

   • Uses mcrypt’s rijndael-256 (deprecated in PHP 7.2+). Avoid on modern PHP versions unless necessary.

3. Error Handling:

   • Decryption failures throw DecryptException. Catch explicitly:

     try {
         $legacyEncrypter->decrypt($data);
     } catch (\Laravel\LegacyEncrypter\Exceptions\DecryptException $e) {
         // Handle corrupt/legacy-incompatible data
     }
     

4. Performance:

   • Slower than Laravel’s default OpenSSL encrypter. Cache decrypted values if reused.

Tips

1. Config Override: Override the encrypter in AppServiceProvider for specific contexts:

   $this->app->bind(LegacyEncrypter::class, function () {
       return new LegacyEncrypter('custom_legacy_key');
   });
   

2. Debugging:

   • Log encrypted/decrypted pairs for verification:

     \Log::debug('Legacy Encrypt', ['input' => $data, 'output' => $encrypted]);
     

3. Extension:

   • Extend LegacyEncrypter to add custom logic (e.g., key rotation):

     class CustomLegacyEncrypter extends LegacyEncrypter {
         public function decryptWithFallback($payload) {
             try {
                 return parent::decrypt($payload);
             } catch (DecryptException $e) {
                 return $this->decryptWithOldKey($payload);
             }
         }
     }
     

4. Deprecation:

   • Mark legacy endpoints with @deprecated and set a sunset date. Use Laravel’s deprecated() helper:

     Route::get('/legacy', function () {
         deprecated('Legacy endpoint', '2024-12-31');
         // ...
     });