feat: add support for encrypted date(time)

Author: JaZo

MIGRATING.md

@@ -3,7 +3,7 @@
 ## To Laravel Encrypted Casting
 The main difference between this package and [Laravel Encrypted Casting](https://laravel.com/docs/10.x/eloquent-mutators#encrypted-casting) is that this package serializes the data before encrypting it, while Laravel Encrypted Casting encrypts the data directly. This means that the data is not compatible between the two packages. In order to migrate from this package 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:
 
-[//]: # (TODO: What to do when you need serialized data or encrypted dates?)
+[//]: # (TODO: What to do when you need encrypted serialized data?)
 
 1. Make sure you're running on Laravel 11 or higher.
 2. Remove the `Swis\Laravel\Encrypted\EncryptedModel` from your models and replace it with `Illuminate\Database\Eloquent\Model`:
@@ -23,7 +23,20 @@ The main difference between this package and [Laravel Encrypted Casting](https:/
 +     'secret' => 'encrypted',
 + ];
 ```
-4. Set up our custom model encrypter in your `AppServiceProvider`:
+4. If you're using encrypted date(time)s, use the custom casts provided by this package:
+```diff
+- protected $encrypted = [
+-     'secret',
+- ];
+-
+- protected $casts = [
+-     'secret' => 'datetime',
+- ];
++ protected $casts = [
++     'secret' => \Swis\Laravel\Encrypted\Casts\AsEncryptedDateTime::class,
++ ];
+```
+5. Set up our custom model encrypter in your `AppServiceProvider`:
 ```php
 public function boot(): void
 {
@@ -32,9 +45,9 @@ public function boot(): void
     // ... all your other models that used to extend \Swis\Laravel\Encrypted\EncryptedModel
 }
 ```
-5. Run our re-encryption command:
+6. Run our re-encryption command:
 ```bash
 php artisan encrypted-data:re-encrypt:models --quietly --no-touch
 ```
 N.B. Use `--help` to see all available options and modify as needed!
-6. Remove our custom model encrypter from your `AppServiceProvider` (step 4).
+7. Remove our custom model encrypter from your `AppServiceProvider` (step 5).

README.md

@@ -21,24 +21,26 @@ composer require swisnl/laravel-encrypted-data
 
 ## Usage
 
-### Models
+### Eloquent casts
 
 > [!WARNING]
-> Laravel supports [encrypted casts](https://laravel.com/docs/10.x/eloquent-mutators#encrypted-casting) since version 8.12, so new projects should use that instead of the models provided by this package.
->
-> Please see [MIGRATING](MIGRATING.md) for a step-by-step guide on how to migrate.
+> Older versions of this package needed a custom model class to encrypt data. This is now deprecated in favor of custom casts. Please see [MIGRATING](MIGRATING.md) for a step-by-step guide on how to migrate.
 >
 
-Extend `\Swis\Laravel\Encrypted\EncryptedModel` in your model and define the encrypted fields. Make sure your database columns are long enough, so your data isn't truncated!
+You can use the Eloquent casts provided by this package and everything will be encrypted/decrypted under the hood!
+
+#### Datetime
 
 ```php
-protected $encrypted = [
-    'secret',
+protected $casts = [
+    'date' => \Swis\Laravel\Encrypted\Casts\AsEncryptedDate::class,
+    'datetime' => \Swis\Laravel\Encrypted\Casts\AsEncryptedDateTime::class,
+    'immutable_date' => \Swis\Laravel\Encrypted\Casts\AsEncryptedImmutableDate::class,
+    'immutable_datetime' => \Swis\Laravel\Encrypted\Casts\AsEncryptedImmutableDateTime::class,
+    'date_with_custom_format' => \Swis\Laravel\Encrypted\Casts\AsEncryptedDate::format('Y-m-d'),
 ];
 ```
 
-You can now simply use the model properties as usual and everything will be encrypted/decrypted under the hood!
-
 ### Filesystem
 
 Configure the storage driver in `config/filesystems.php`.
@@ -60,10 +62,9 @@ Due to the encryption, some issues/limitations apply:
 
 1. Encrypted data is — depending on what you encrypt — roughly 30-40% bigger.
 
-### Models
+### Casts
 
-1. You can't query or order columns that are encrypted in your SQL-statements, but you can query or sort the results using collection methods;
-2. All data is being serialized before it is encrypted — and unserialized after it is decrypted — so everything is stored exactly as how Laravel would insert it into the database. You can use [Eloquent Mutators](https://laravel.com/docs/9.x/eloquent-mutators) as you normally would.
+1. You can't query or order columns that are encrypted in your SQL-statements, but you can query or sort the results using collection methods.
 
 ### Filesystem
 

src/Casts/AsEncryptedDate.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Swis\Laravel\Encrypted\Casts;
+
+use Carbon\CarbonImmutable;
+use Illuminate\Contracts\Database\Eloquent\Castable;
+use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
+use Illuminate\Support\Carbon;
+
+class AsEncryptedDate implements Castable
+{
+    /**
+     * @param string[] $arguments
+     */
+    public static function castUsing(array $arguments): CastsAttributes
+    {
+        return new EncryptedDateTime($arguments, fn (#[\SensitiveParameter] Carbon|CarbonImmutable|null $value) => $value?->startOfDay());
+    }
+
+    /**
+     * Specify the format to use when the model is serialized to an array or JSON.
+     */
+    public static function format(string $format): string
+    {
+        return static::class.':'.$format;
+    }
+}

src/Casts/AsEncryptedDateTime.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Swis\Laravel\Encrypted\Casts;
+
+use Illuminate\Contracts\Database\Eloquent\Castable;
+use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
+
+class AsEncryptedDateTime implements Castable
+{
+    /**
+     * @param string[] $arguments
+     */
+    public static function castUsing(array $arguments): CastsAttributes
+    {
+        return new EncryptedDateTime($arguments);
+    }
+
+    /**
+     * Specify the format to use when the model is serialized to an array or JSON.
+     */
+    public static function format(string $format): string
+    {
+        return static::class.':'.$format;
+    }
+}

src/Casts/AsEncryptedImmutableDate.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Swis\Laravel\Encrypted\Casts;
+
+use Carbon\CarbonImmutable;
+use Illuminate\Contracts\Database\Eloquent\Castable;
+use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
+use Illuminate\Support\Carbon;
+
+class AsEncryptedImmutableDate implements Castable
+{
+    /**
+     * @param string[] $arguments
+     */
+    public static function castUsing(array $arguments): CastsAttributes
+    {
+        return new EncryptedDateTime($arguments, fn (#[\SensitiveParameter] Carbon|CarbonImmutable|null $value) => $value?->startOfDay()->toImmutable());
+    }
+
+    /**
+     * Specify the format to use when the model is serialized to an array or JSON.
+     */
+    public static function format(string $format): string
+    {
+        return static::class.':'.$format;
+    }
+}

src/Casts/AsEncryptedImmutableDateTime.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Swis\Laravel\Encrypted\Casts;
+
+use Carbon\CarbonImmutable;
+use Illuminate\Contracts\Database\Eloquent\Castable;
+use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
+use Illuminate\Support\Carbon;
+
+class AsEncryptedImmutableDateTime implements Castable
+{
+    /**
+     * @param string[] $arguments
+     */
+    public static function castUsing(array $arguments): CastsAttributes
+    {
+        return new EncryptedDateTime($arguments, fn (#[\SensitiveParameter] Carbon|CarbonImmutable|null $value) => $value?->toImmutable());
+    }
+
+    /**
+     * Specify the format to use when the model is serialized to an array or JSON.
+     */
+    public static function format(string $format): string
+    {
+        return static::class.':'.$format;
+    }
+}

src/Casts/EncryptedDateTime.php

@@ -0,0 +1,120 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Swis\Laravel\Encrypted\Casts;
+
+use Carbon\CarbonImmutable;
+use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Facades\Crypt;
+use Illuminate\Support\Facades\Date;
+
+/**
+ * @internal
+ *
+ * @implements \Illuminate\Contracts\Database\Eloquent\CastsAttributes<\Illuminate\Support\Carbon|\Carbon\CarbonImmutable, string|\Illuminate\Support\Carbon|\Carbon\CarbonImmutable>
+ */
+class EncryptedDateTime implements CastsAttributes
+{
+    /**
+     * @param array<int, string>                                                        $arguments
+     * @param \Closure(Carbon|CarbonImmutable|null): (Carbon|CarbonImmutable|null)|null $modifier
+     */
+    public function __construct(protected array $arguments, protected ?\Closure $modifier = null)
+    {
+    }
+
+    /**
+     * @param array<string, mixed> $attributes
+     */
+    public function get(Model $model, string $key, mixed $value, array $attributes): Carbon|CarbonImmutable|null
+    {
+        if ($value === null) {
+            return null;
+        }
+
+        $value = ($model::$encrypter ?? Crypt::getFacadeRoot())->decrypt($value, false);
+
+        return with($this->parse($model, $key, $value, $attributes), $this->modifier);
+    }
+
+    /**
+     * @param \Illuminate\Support\Carbon|\Carbon\CarbonImmutable|string|null $value
+     * @param array<string, mixed>                                           $attributes
+     */
+    public function set(Model $model, string $key, #[\SensitiveParameter] mixed $value, array $attributes): ?string
+    {
+        if ($value === null) {
+            return null;
+        }
+
+        $value = is_string($value) ? $value : $value->format($model->getDateFormat());
+
+        return ($model::$encrypter ?? Crypt::getFacadeRoot())->encrypt($value, false);
+    }
+
+    /**
+     * @param string|null          $value
+     * @param array<string, mixed> $attributes
+     */
+    public function serialize(Model $model, string $key, #[\SensitiveParameter] mixed $value, array $attributes): ?string
+    {
+        if ($value === null) {
+            return null;
+        }
+
+        return !empty($this->arguments[0]) ? Date::parse($value)->format($this->arguments[0]) : $value;
+    }
+
+    /**
+     * @param string|null $original
+     * @param string|null $value
+     */
+    public function compare(Model $model, string $key, mixed $original, mixed $value): bool
+    {
+        if (!empty(($model::$encrypter ?? Crypt::getFacadeRoot())->getPreviousKeys())) {
+            return false;
+        }
+
+        $original = $this->get($model, $key, $original, []);
+        $value = $this->get($model, $key, $value, []);
+
+        if ($original === $value) {
+            return true;
+        }
+
+        if ($original === null || $value === null) {
+            return false;
+        }
+
+        return $original->equalTo($value);
+    }
+
+    /**
+     * @param string|int           $value
+     * @param array<string, mixed> $attributes
+     */
+    protected function parse(Model $model, string $key, #[\SensitiveParameter] mixed $value, array $attributes): Carbon|CarbonImmutable|null
+    {
+        if (is_numeric($value)) {
+            return Date::createFromTimestamp($value, date_default_timezone_get());
+        }
+
+        if ($this->isStandardDateFormat($value)) {
+            return Date::instance(Carbon::createFromFormat('Y-m-d', $value)->startOfDay());
+        }
+
+        try {
+            return Date::createFromFormat($model->getDateFormat(), $value);
+        } catch (\InvalidArgumentException) {
+            return Date::parse($value);
+        }
+    }
+
+    protected function isStandardDateFormat(#[\SensitiveParameter] string $value): bool
+    {
+        return (bool) preg_match('/^(\d{4})-(\d{1,2})-(\d{1,2})$/', $value);
+    }
+}

src/Commands/ReEncryptModels.php

@@ -1,5 +1,7 @@
 <?php
 
+declare(strict_types=1);
+
 namespace Swis\Laravel\Encrypted\Commands;
 
 use Illuminate\Console\Command;

tests/Casts/AsEncryptedDateTest.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace Swis\Laravel\Encrypted\Tests\Casts;
+
+use Illuminate\Support\Carbon;
+use PHPUnit\Framework\TestCase;
+use Swis\Laravel\Encrypted\Casts\AsEncryptedDate;
+use Swis\Laravel\Encrypted\Tests\_mocks\DummyEncrypter;
+use Swis\Laravel\Encrypted\Tests\_mocks\Model;
+
+class AsEncryptedDateTest extends TestCase
+{
+    protected function setUp(): void
+    {
+        parent::setUp();
+        Model::$encrypter = new DummyEncrypter();
+    }
+
+    public function testGetReturnsNullForNull(): void
+    {
+        $cast = AsEncryptedDate::castUsing([]);
+        $model = new Model();
+
+        $result = $cast->get($model, 'date', null, []);
+
+        $this->assertNull($result);
+    }
+
+    public function testGetAppliesStartOfDayClosure(): void
+    {
+        $cast = AsEncryptedDate::castUsing([]);
+        $model = new Model();
+        $date = '2024-07-02 15:30:45';
+
+        $result = $cast->get($model, 'date', $date, []);
+
+        $this->assertInstanceOf(Carbon::class, $result);
+        $this->assertEquals('2024-07-02 00:00:00', $result->toDateTimeString());
+    }
+
+    public function testFormatReturnsExpectedString(): void
+    {
+        $this->assertEquals(AsEncryptedDate::class.':Y-m-d', AsEncryptedDate::format('Y-m-d'));
+    }
+}