From 6abf84c712638b92e82a1544a6655b10cf523169 Mon Sep 17 00:00:00 2001
From: insign <1113045+insign@users.noreply.github.com>
Date: Fri, 6 Mar 2026 03:10:32 +0000
Subject: [PATCH] feat: add toArray() method to Progressable trait

Adds a `toArray()` method to the `Progressable` trait to export the current state (progress, steps, eta, status message, metadata) easily. This allows developers to serialize and retrieve the entire progress state efficiently. Added comprehensive PHPUnit tests to cover both scenarios with and without a unique name.
---
 src/Progressable.php       | 24 +++++++++++++++++++++++
 tests/ProgressableTest.php | 39 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 63 insertions(+)

diff --git a/src/Progressable.php b/src/Progressable.php
index 64786bf..809c0d2 100644
--- a/src/Progressable.php
+++ b/src/Progressable.php
@@ -644,4 +644,28 @@ public function incrementStep(int $amount = 1): static {
 
         return $this->setStep($current + $amount);
     }
+
+    /**
+     * Get the current state as an array.
+     *
+     * @return array<string, mixed>
+     */
+    public function toArray(): array {
+        $overallProgress = null;
+        $eta = null;
+        if (isset($this->overallUniqueName)) {
+            $overallProgress = $this->getOverallProgress();
+            $eta = $this->getEstimatedTimeRemaining();
+        }
+
+        return [
+            'progress' => $this->getLocalProgress(),
+            'overall_progress' => $overallProgress,
+            'total_steps' => $this->getTotalSteps(),
+            'current_step' => $this->getStep(),
+            'eta' => $eta,
+            'status_message' => $this->getStatusMessage(),
+            'metadata' => $this->getMetadata(),
+        ];
+    }
 }
diff --git a/tests/ProgressableTest.php b/tests/ProgressableTest.php
index 2187c6b..0aff754 100644
--- a/tests/ProgressableTest.php
+++ b/tests/ProgressableTest.php
@@ -553,4 +553,43 @@ public function test_set_step_without_total_steps(): void {
         $this->assertEquals(5, $this->getStep());
         $this->assertEquals(0, $this->getLocalProgress());
     }
+
+    public function test_to_array(): void {
+        $this->setOverallUniqueName('test_to_array_'.$this->testId);
+        $this->setTotalSteps(10);
+        $this->setStep(5);
+        $this->setStatusMessage('Processing item 5');
+        $this->setMetadata(['foo' => 'bar']);
+
+        $array = $this->toArray();
+
+        $this->assertIsArray($array);
+        $this->assertArrayHasKey('progress', $array);
+        $this->assertEquals(50, $array['progress']);
+        $this->assertArrayHasKey('overall_progress', $array);
+        $this->assertEquals(50, $array['overall_progress']);
+        $this->assertArrayHasKey('total_steps', $array);
+        $this->assertEquals(10, $array['total_steps']);
+        $this->assertArrayHasKey('current_step', $array);
+        $this->assertEquals(5, $array['current_step']);
+        $this->assertArrayHasKey('eta', $array);
+        // ETA depends on start time and elapsed time, which might be null if 0 time elapsed
+        $this->assertArrayHasKey('status_message', $array);
+        $this->assertEquals('Processing item 5', $array['status_message']);
+        $this->assertArrayHasKey('metadata', $array);
+        $this->assertEquals(['foo' => 'bar'], $array['metadata']);
+    }
+
+    public function test_to_array_without_unique_name(): void {
+        // Just checking toArray when no unique name is set
+        $array = $this->toArray();
+
+        $this->assertIsArray($array);
+        $this->assertEquals(0, $array['progress']);
+        $this->assertNull($array['overall_progress']);
+        $this->assertNull($array['total_steps']);
+        $this->assertNull($array['current_step']);
+        $this->assertNull($array['status_message']);
+        $this->assertEquals([], $array['metadata']);
+    }
 }