Added action operation type handling

Author: fulopattila122

Changelog.md

@@ -1,5 +1,12 @@
 # Eloquent History Changelog
 
+## Unreleased
+##### 2024-XX-YY
+
+- Added the `action` Operation type
+- Added the `details` field to the model history table/model
+- Added the `logActionSuccess()` and `logActionFailure()` factory methods to the `History` class
+
 ## 1.4.0
 ##### 2024-03-12
 

src/Contracts/ModelHistoryEvent.php

@@ -24,6 +24,11 @@ public function summary(): string;
 
     public function comment(): ?string;
 
+    /**
+     * @todo V2 interface candidates
+     * public function details(): ?string;
+     */
+
     public function isASingleFieldChange(): bool;
 
     public function isNoFieldChangeEntry(): bool;

src/History.php

@@ -88,6 +88,16 @@ public static function addComment(Model $model, string $comment): ModelHistoryEv
         ], static::commonFields($model)));
     }
 
+    public static function logActionSuccess(Model $model, ?string $details = null): ModelHistoryEvent
+    {
+        return static::logAction($model, true, $details);
+    }
+
+    public static function logActionFailure(Model $model, ?string $details = null): ModelHistoryEvent
+    {
+        return static::logAction($model, false, $details);
+    }
+
     public static function logDeletion(Model $model, ?string $comment = null): ModelHistoryEvent
     {
         return ModelHistoryEventProxy::create(array_merge([
@@ -150,4 +160,16 @@ protected static function sceneResolver(): SceneResolver
 
         return static::$sceneResolver;
     }
+
+    protected static function logAction(Model $model, bool $wasSuccessful, ?string $details = null): ModelHistoryEvent
+    {
+        return ModelHistoryEventProxy::create(array_merge([
+            'happened_at' => now(),
+            'comment' => null,
+            'details' => $details,
+            'operation' => Operation::ACTION,
+            'was_successful' => $wasSuccessful,
+            'diff' => [],
+        ], static::commonFields($model)));
+    }
 }

src/Models/ModelHistoryEvent.php

@@ -37,6 +37,8 @@
  * @property string $model_type
  * @property array $diff;
  * @property string|null $comment
+ * @property bool|null $was_successful
+ * @property string|null $details
  * @property Carbon $happened_at
  * @property Carbon $created_at
  * @property Carbon $updated_at
@@ -99,6 +101,7 @@ public function summary(): string
             Operation::COMMENT => __('Comment has been added'),
             Operation::DELETE => __('Has been deleted'),
             Operation::RETRIEVE => __('Was retrieved'),
+            Operation::ACTION => $this->was_successful ? __('Executed successfully') : __('Execution failed'),
             default => '',
         };
     }
@@ -108,6 +111,11 @@ public function comment(): ?string
         return $this->comment;
     }
 
+    public function details(): ?string
+    {
+        return $this->details;
+    }
+
     public function isASingleFieldChange(): bool
     {
         return 1 === $this->diff()->changeCount();
@@ -122,4 +130,9 @@ public function isACommentOnlyEntry(): bool
     {
         return 0 === $this->diff()->changeCount() && !is_null($this->comment);
     }
+
+    public function isAnActionEvent(): bool
+    {
+        return $this->operation->is_action;
+    }
 }

src/Models/Operation.php

@@ -24,6 +24,15 @@
  * @method static self DELETE()
  * @method static self RETRIEVE()
  * @method static self COMMENT()
+ * @method static self ACTION()
+ *
+ * @property-read bool $is_undefined
+ * @property-read bool $is_create
+ * @property-read bool $is_update
+ * @property-read bool $is_delete
+ * @property-read bool $is_retrieve
+ * @property-read bool $is_comment
+ * @property-read bool $is_action
  */
 class Operation extends Enum implements OperationContract
 {
@@ -34,4 +43,6 @@ class Operation extends Enum implements OperationContract
     public const DELETE = 'delete';
     public const RETRIEVE = 'retrieve';
     public const COMMENT = 'comment';
+
+    public const ACTION = 'action';
 }

src/resources/database/migrations/2024_11_01_092014_add_action_fields_to_model_history_table.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class () extends Migration {
+    public function up(): void
+    {
+        Schema::table('model_history', function (Blueprint $table) {
+            $table->boolean('was_successful')->nullable();
+            $table->text('details')->nullable();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('model_history', function (Blueprint $table) {
+            $table->dropColumn('was_successful');
+            $table->dropColumn('details');
+        });
+    }
+};

tests/HistoryTest.php

@@ -43,6 +43,7 @@ public function it_can_record_if_a_model_was_created()
         $this->assertInstanceOf(ModelHistoryEvent::class, $event);
         $this->assertCount(3, $event->diff()->changes());
         $this->assertEquals(Operation::CREATE, $event->operation->value());
+        $this->assertNull($event->comment());
     }
 
     /** @test */
@@ -56,6 +57,7 @@ public function a_recent_update_can_be_recorded()
 
         $this->assertTrue($event->isASingleFieldChange());
         $this->assertTrue($event->diff()->hasChanged('status'));
+        $this->assertNull($event->comment());
         $this->assertEquals(Operation::UPDATE, $event->operation->value());
     }
 
@@ -91,6 +93,62 @@ public function non_diff_changes_can_be_manually_recorded()
         $this->assertEquals('Has timed out waiting', $event->comment());
     }
 
+    /** @test */
+    public function it_can_record_a_successful_action()
+    {
+        $task = SampleTask::create(['title' => 'Hello', 'description' => 'Make me', 'status' => 'todo']);
+
+        $event = History::logActionSuccess($task);
+
+        $this->assertEquals(Operation::ACTION, $event->operation->value());
+        $this->assertTrue($event->was_successful);
+        $this->assertTrue($event->diff()->isEmpty());
+        $this->assertEmpty($event->diff()->changes());
+        $this->assertNull($event->comment());
+        $this->assertNull($event->details());
+    }
+
+    /** @test */
+    public function it_can_record_a_successful_action_with_details()
+    {
+        $task = SampleTask::create(['title' => 'Hello', 'description' => 'Make me', 'status' => 'todo']);
+
+        $event = History::logActionSuccess($task, '124 entries updated');
+
+        $this->assertEquals(Operation::ACTION, $event->operation->value());
+        $this->assertTrue($event->was_successful);
+        $this->assertEquals('124 entries updated', $event->details());
+        $this->assertNull($event->comment());
+    }
+
+    /** @test */
+    public function it_can_record_a_failed_action()
+    {
+        $task = SampleTask::create(['title' => 'Hello', 'description' => 'Make me', 'status' => 'todo']);
+
+        $event = History::logActionFailure($task);
+
+        $this->assertEquals(Operation::ACTION, $event->operation->value());
+        $this->assertFalse($event->was_successful);
+        $this->assertTrue($event->diff()->isEmpty());
+        $this->assertEmpty($event->diff()->changes());
+        $this->assertNull($event->comment());
+        $this->assertNull($event->details());
+    }
+
+    /** @test */
+    public function it_can_record_a_failed_action_with_details()
+    {
+        $task = SampleTask::create(['title' => 'Hello', 'description' => 'Make me', 'status' => 'todo']);
+
+        $event = History::logActionFailure($task, 'Error connecting to the Remote API');
+
+        $this->assertEquals(Operation::ACTION, $event->operation->value());
+        $this->assertFalse($event->was_successful);
+        $this->assertEquals('Error connecting to the Remote API', $event->details());
+        $this->assertNull($event->comment());
+    }
+
     /** @test */
     public function deletion_can_be_recorded()
     {