From f5722408938d53150e5d7c9f7a6965d4e1d1edd2 Mon Sep 17 00:00:00 2001
From: insign <1113045+insign@users.noreply.github.com>
Date: Sat, 7 Feb 2026 03:07:55 +0000
Subject: [PATCH] Add mergeMetadata method to Progressable trait

This commit introduces a `mergeMetadata` method to the `Progressable` trait.
This allows users to merge an array of metadata into the existing metadata
in a single operation, which is more efficient than calling `addMetadata`
multiple times as it triggers only one storage update.

- Added `mergeMetadata` method to `src/Progressable.php`
- Added `test_merge_metadata` to `tests/ProgressableTest.php`
---
 src/Progressable.php       | 16 ++++++++++++++++
 tests/ProgressableTest.php | 16 ++++++++++++++++
 2 files changed, 32 insertions(+)

diff --git a/src/Progressable.php b/src/Progressable.php
index a12076c..0997237 100644
--- a/src/Progressable.php
+++ b/src/Progressable.php
@@ -428,6 +428,22 @@ public function setStatusMessage(?string $message): static {
         return $this;
     }
 
+    /**
+     * Merge metadata for this progress instance.
+     *
+     * @param  array<string, mixed>  $metadata
+     */
+    public function mergeMetadata(array $metadata): static {
+        $this->metadata = array_merge($this->metadata, $metadata);
+
+        // Update storage with new metadata if we have a unique name
+        if (isset($this->overallUniqueName)) {
+            $this->updateLocalProgressData($this->progress);
+        }
+
+        return $this;
+    }
+
     /**
      * Get the status message for this progress instance.
      */
diff --git a/tests/ProgressableTest.php b/tests/ProgressableTest.php
index 2a21740..40f5003 100644
--- a/tests/ProgressableTest.php
+++ b/tests/ProgressableTest.php
@@ -469,4 +469,20 @@ public function test_metadata_and_message_stored_together(): void {
         $this->assertEquals('Processing...', $localData['message']);
         $this->assertEquals(['step' => 1], $localData['metadata']);
     }
+
+    public function test_merge_metadata(): void {
+        $this->setOverallUniqueName('test_merge_metadata_'.$this->testId);
+        $this->setMetadata(['key1' => 'value1']);
+
+        $this->mergeMetadata(['key2' => 'value2', 'key1' => 'new_value1']);
+
+        $this->assertEquals('new_value1', $this->getMetadataValue('key1'));
+        $this->assertEquals('value2', $this->getMetadataValue('key2'));
+
+        // Verify storage
+        $progressData = $this->getOverallProgressData();
+        $storedMetadata = $progressData[$this->getLocalKey()]['metadata'];
+        $this->assertEquals('new_value1', $storedMetadata['key1']);
+        $this->assertEquals('value2', $storedMetadata['key2']);
+    }
 }