Migrate actions add option --dry-run and doc (#146)

Author: cesargb

README.md

@@ -1,4 +1,3 @@
-
 # MagicLink for Laravels App
 
 Through the `MagicLink` class we can create a secure link that later
@@ -11,6 +10,9 @@ offer secure content and even log in to the application.
 [![Quality Score](https://img.shields.io/scrutinizer/g/cesargb/laravel-magiclink.svg?style=flat-square)](https://scrutinizer-ci.com/g/cesargb/laravel-magiclink)
 [![Total Downloads](https://img.shields.io/packagist/dt/cesargb/laravel-magiclink.svg?style=flat-square)](https://packagist.org/packages/cesargb/laravel-magiclink)
 
+> [!WARNING]
+> Migrate actions is required if you are upgrading from version 2.24.2 or earlier. Please see the [Migrate actions](#migrate-actions) section for detailed instructions.
+
 ## Contents
 
 - [Installation](#installation)
@@ -28,6 +30,7 @@ offer secure content and even log in to the application.
 - [Events](#events)
 - [Customization](#customization)
 - [Rate limiting](#rate-limiting)
+- [Migrate actions](#migrate-actions)
 - [Testing](#testing)
 - [Contributing](#contributing)
 - [Security](#security)
@@ -450,6 +453,26 @@ to limit the requests. For example, to limit the requests to 100 per minute, set
 MAGICLINK_RATE_LIMIT=100
 ```
 
+## Migrate actions
+
+> [!WARNING]
+> The action storage mechanism changed from PHP serialization to HMAC-signed JSON format for improved security.
+> If you're upgrading from version 2.24.2, you need to migrate existing MagicLinks.
+
+To migrate legacy serialized actions to the new format, run:
+
+```bash
+php artisan magiclink:migrate --dry-run
+```
+
+This command will simulate the migration and display the number of legacy MagicLinks found.
+
+If everything looks good, run the migration for real with:
+
+```bash
+php artisan magiclink:migrate
+```
+
 ## Testing
 
 Run the tests with:

src/Commands/MigrateLegacyActionsCommand.php

@@ -12,16 +12,24 @@
 class MigrateLegacyActionsCommand extends Command
 {
     protected $signature = 'magiclink:migrate
-                                {--force : Force the operation to run without confirmation}';
+                                {--force : Force the operation to run without confirmation}
+                                {--dry-run : Show what would be migrated without actually migrating}';
 
     protected $description = 'Migrate legacy serialized actions to the new HMAC-signed format';
 
     private int $migrated = 0;
     private array $errors = [];
     private ProgressBar $progressBar;
+    private bool $dryRun = false;
 
     public function handle()
     {
+        $this->dryRun = $this->option('dry-run');
+
+        if ($this->dryRun) {
+            $this->warn('Running in DRY-RUN mode - no changes will be made');
+        }
+
         $this->info('Checking for legacy MagicLinks...');
 
         $legacyCount = $this->getLegacyBuilder()->count();
@@ -67,7 +75,7 @@ public function handle()
 
     private function canContinue(int $legacyCount): bool
     {
-        if ($this->option('force')) {
+        if ($this->option('force') || $this->dryRun) {
             return true;
         }
 
@@ -78,8 +86,13 @@ private function printSummary(): void
     {
         $this->newLine(2);
 
-        $this->info("Migration completed!");
-        $this->info("Successfully migrated: {$this->migrated}");
+        if ($this->dryRun) {
+            $this->info("Dry-run completed!");
+            $this->info("Would migrate: {$this->migrated}");
+        } else {
+            $this->info("Migration completed!");
+            $this->info("Successfully migrated: {$this->migrated}");
+        }
 
         if ($failed = count($this->errors) > 0) {
             $this->error("Failed to migrate: {$failed}");
@@ -118,11 +131,13 @@ private function migrateRecord(int|string $id, string $action): array
             ];
         }
 
-        $magicLink->action = (new MagicLink())->getConnection()->getDriverName() === 'pgsql'
-            ? unserialize(base64_decode($action))
-            : unserialize($action);
+        if (! $this->dryRun) {
+            $magicLink->action = (new MagicLink())->getConnection()->getDriverName() === 'pgsql'
+                ? unserialize(base64_decode($action))
+                : unserialize($action);
 
-        $magicLink->saveQuietly();
+            $magicLink->saveQuietly();
+        }
 
         return [
             'status' => 'success',

tests/Commands/MigrateLegacyActionsCommandTest.php

@@ -19,7 +19,7 @@ public function test_controller()
     {
         $action = new ControllerAction(MyController::class);
 
-        [$id, $magiclinkUrl] = $this->generateMagicLink($action);
+        [$id, $magiclinkUrl] = $this->generateLegacyMagicLink($action);
 
         $this->get($magiclinkUrl)
             ->assertStatus(200)
@@ -39,7 +39,7 @@ public function test_controller()
 
     public function test_download_file()
     {
-        [$id, $magiclinkUrl] = $this->generateMagicLink(new DownloadFileAction('text.txt'));
+        [$id, $magiclinkUrl] = $this->generateLegacyMagicLink(new DownloadFileAction('text.txt'));
 
         $this->get($magiclinkUrl)
             ->assertStatus(200)
@@ -65,7 +65,7 @@ public function test_download_file()
 
     public function test_auth()
     {
-        [$id, $magiclinkUrl] = $this->generateMagicLink(new LoginAction(User::first()));
+        [$id, $magiclinkUrl] = $this->generateLegacyMagicLink(new LoginAction(User::first()));
 
         $this->artisan('magiclink:migrate', ['--force' => true])
             ->assertSuccessful();
@@ -83,7 +83,7 @@ public function test_auth()
 
     public function test_response_callable()
     {
-        [$id, $magiclinkUrl] = $this->generateMagicLink(new ResponseAction(
+        [$id, $magiclinkUrl] = $this->generateLegacyMagicLink(new ResponseAction(
             function () {
                 return 'callback called';
             }
@@ -107,7 +107,7 @@ function () {
 
     public function test_view()
     {
-        [$id, $magiclinkUrl] = $this->generateMagicLink(new ViewAction('view'));
+        [$id, $magiclinkUrl] = $this->generateLegacyMagicLink(new ViewAction('view'));
 
         $this->get($magiclinkUrl)
             ->assertStatus(200)
@@ -125,7 +125,29 @@ public function test_view()
             ->assertSeeText('This is a tests view');
     }
 
-    private function generateMagicLink($action): array
+    public function test_dry_run()
+    {
+        $action = new ControllerAction(MyController::class);
+
+        [$id, $magiclinkUrl] = $this->generateLegacyMagicLink($action);
+
+        $this->get($magiclinkUrl)
+            ->assertStatus(200)
+            ->assertSeeText('im a controller invoke');
+
+        $actionLegacy = DB::table('magic_links')->where('id', $id)->first()->action;
+
+        $this->artisan('magiclink:migrate', ['--dry-run' => true])
+            ->assertSuccessful();
+
+        $this->assertEquals($actionLegacy, DB::table('magic_links')->where('id', $id)->first()->action);
+
+        $this->get($magiclinkUrl)
+            ->assertStatus(200)
+            ->assertSeeText('im a controller invoke');
+    }
+
+    private function generateLegacyMagicLink($action): array
     {
         $id = (string) \Illuminate\Support\Str::uuid();
         $token = 'toktok';