[12.x] Add mergeMetadata method to the Mailable class (#56376)

* Add mergeMetadata method to the Mailable class.

* Update the test case for the mergeMetadata method.

* formatting

---------

Co-authored-by: Taylor Otwell <taylor@laravel.com>

Author: kevinb1989

src/Illuminate/Mail/Mailable.php

@@ -1184,13 +1184,17 @@ public function hasTag($value)
     /**
      * Add a metadata header to the message when supported by the underlying transport.
      *
-     * @param  string  $key
-     * @param  string  $value
+     * @param  array|string  $key
+     * @param  string|null  $value
      * @return $this
      */
-    public function metadata($key, $value)
+    public function metadata($key, $value = null)
     {
-        $this->metadata[$key] = $value;
+        if (is_array($key)) {
+            $this->metadata = array_merge($this->metadata, $key);
+        } else {
+            $this->metadata[$key] = $value;
+        }
 
         return $this;
     }

tests/Mail/MailMailableTest.php

@@ -634,6 +634,45 @@ public function testMailableMetadataGetsSent()
         }
     }
 
+    public function testMailableMergeMetadata()
+    {
+        $mailable = new WelcomeMailableStub;
+        $mailable->to('hello@laravel.com');
+        $mailable->from('taylor@laravel.com');
+        $mailable->html('test content');
+
+        $mailable->metadata([
+            'template_id' => 'external-template-id',
+            'customer_id' => 101,
+            'order_id' => 1000,
+            'subtotal' => 1500,
+            'gst' => 150,
+            'shipping_fee' => 20,
+            'total' => 1670,
+        ]);
+
+        $this->assertTrue($mailable->hasMetadata('template_id', 'external-template-id'));
+        $this->assertTrue($mailable->hasMetadata('customer_id', 101));
+        $this->assertTrue($mailable->hasMetadata('order_id', 1000));
+        $this->assertTrue($mailable->hasMetadata('subtotal', 1500));
+        $this->assertTrue($mailable->hasMetadata('gst', 150));
+        $this->assertTrue($mailable->hasMetadata('shipping_fee', 20));
+        $this->assertTrue($mailable->hasMetadata('total', 1670));
+
+        $this->stubMailer();
+        $view = m::mock(Factory::class);
+        $mailer = new Mailer('array', $view, new ArrayTransport);
+
+        $sentMessage = $mailer->send($mailable);
+        $this->assertStringContainsString('X-Metadata-template_id: external-template-id', $sentMessage->toString());
+        $this->assertStringContainsString('X-Metadata-customer_id: 101', $sentMessage->toString());
+        $this->assertStringContainsString('X-Metadata-order_id: 1000', $sentMessage->toString());
+        $this->assertStringContainsString('X-Metadata-subtotal: 1500', $sentMessage->toString());
+        $this->assertStringContainsString('X-Metadata-gst: 150', $sentMessage->toString());
+        $this->assertStringContainsString('X-Metadata-shipping_fee: 20', $sentMessage->toString());
+        $this->assertStringContainsString('X-Metadata-total: 1670', $sentMessage->toString());
+    }
+
     public function testMailableTagGetsSent()
     {
         $this->stubMailer();