UPGRADING.md

Updating swisnl/laravel-encrypted-data

To 3.x from 2.x

Laravel Encrypted Casting

The main difference between EncryptedModel provided by version 2.x of this package and Laravel Encrypted Casting, is that the EncryptedModel serialized the data before encrypting it, while Laravel Encrypted Casting encrypts the data directly. This means that the data is not compatible between the two. In order to migrate from EncryptedModel to Laravel Encrypted Casting, you will need to decrypt the data and then re-encrypt it using Laravel Encrypted Casting. Here is a step-by-step guide on how to do this:

1. Make sure you're running on Laravel 12.20 or higher.
2. Remove the Swis\Laravel\Encrypted\EncryptedModel from your models and replace it with Illuminate\Database\Eloquent\Model:

- use Swis\Laravel\Encrypted\EncryptedModel
+ use Illuminate\Database\Eloquent\Model

- class YourEncryptedModel extends EncryptedModel
+ class YourEncryptedModel extends Model

3. Set up Encrypted Casting:

- protected $encrypted = [
-     'secret',
-     'secret_array',
- ];
-
- protected $casts = [
-     'secret_array' => 'array',
- ];
+ protected $casts = [
+     'secret' => 'encrypted',
+     'secret_array' => 'encrypted:array',
+ ];

4. If you're using encrypted booleans, date(time)s, floats or integers, use the custom casts provided by this package:

- protected $encrypted = [
-     'secret_boolean',
-     'secret_datetime',
-     'secret_float',
-     'secret_integer',
- ];
-
- protected $casts = [
-     'secret_boolean' => 'bool',
-     'secret_datetime' => 'datetime',
-     'secret_float' => 'float',
-     'secret_integer' => 'int',
- ];
+ protected $casts = [
+     'secret_boolean' => \Swis\Laravel\Encrypted\Casts\AsEncryptedBoolean::class,
+     'secret_datetime' => \Swis\Laravel\Encrypted\Casts\AsEncryptedDateTime::class,
+     'secret_float' => \Swis\Laravel\Encrypted\Casts\AsEncryptedFloat::class,
+     'secret_integer' => \Swis\Laravel\Encrypted\Casts\AsEncryptedInteger::class,
+ ];

5. If you're using other casts for encrypted attributes, or you need serialization support, you should create custom casts yourself, as this package does not provide casts for every situation. Please see Custom Casts for more information on how to create custom casts. You can use any of the casts provided by this package as a reference.
6. Set up our custom model encrypter in your AppServiceProvider:

public function boot(): void
{
    $modelEncrypter = new \Swis\Laravel\Encrypted\ModelEncrypter();
    YourEncryptedModel::encryptUsing($modelEncrypter);
    // ... all your other models that used to extend \Swis\Laravel\Encrypted\EncryptedModel
}

This custom model encrypter is backward compatible with the old EncryptedModel and will handle the deserialization of the data before casts kick in. Data will not be serialized when re-encrypting, so it will be compatible with Laravel Encrypted Casting. This makes sure your application can keep running and the data is not lost during the migration process.

7. Run our re-encryption command:

php artisan encrypted-data:re-encrypt:models --quietly --no-touch

N.B. See README or use --help to see all available options and modify as needed!

8. Remove our custom model encrypter from your AppServiceProvider (step 6).

Filesystem

If you're using the encrypted filesystem, make sure to update your configuration in config/filesystems.php as shown below:

Before:

'disks' => [
    'local' => [
        'driver' => 'local-encrypted',
        'root' => storage_path('app'),
    ],
],

After:

'disks' => [
    'local' => [
        'driver' => 'encrypted',
        'disk' => [
            'driver' => 'local',
            'root' => storage_path('app'),
        ],
    ],
],