Add customize feature (#15)

* add customize feature

* clean up

* update github workflow

.github/workflows/main.yml

@@ -3,10 +3,10 @@ name: run-tests
 on:
   push:
     branches:
-      - master
+      - main
   pull_request:
     branches:
-      - master
+      - main
       - dev
 
 jobs:

README.md

@@ -135,6 +135,33 @@ You can attach or embed (inline attachment) files to your messages. `SendGridMes
 -   You can use the `as` key in the options to change the filename to appears in the email. (e.g. `attach($file, ['as' => 'invoice-3252.pdf'])`)
 -   `embed` and `embedData` methods will return the ContentID with `cid:` in front (e.g. `embed('avatar.jpg') -> "cid:avatar.jpg"`).
 
+### Full Access to the Sendgrid Mail Object
+
+If you need more customization options, you can work directly with the underlying Sendgrid Mail object.
+To utilize this, simply pass a callback using the `customize` method.
+
+```php
+use SendGrid\Mail\Mail;
+
+return (new SendGridMessage('Your SendGrid template ID'))
+    ->payload([
+        'template_var_1' => 'template_value_1',
+        'template_var_2' => [
+            'value_1',
+            'value_2',
+            'value_3',
+        ],
+    ])
+    ->customize(function (Mail $mail) {
+        // Send a carbon copy (cc) to another address
+        $mail->addCc('[email protected]');
+        // Send a blind carbon copy (bcc) to another address
+        $mail->addBcc('[email protected]');
+    });
+```
+
+For all the options, you can see Sendgrid's Mail class [here](https://github.com/sendgrid/sendgrid-php/blob/main/lib/mail/Mail.php).
+
 ## Changelog
 
 Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.

src/SendGridMessage.php

@@ -20,7 +20,7 @@ class SendGridMessage
     public $from;
 
     /**
-     * The "tos" for the message.
+     * Recipients of the message.
      *
      * @var array
      */
@@ -59,6 +59,13 @@ class SendGridMessage
      */
     public $sandboxMode = false;
 
+    /**
+     * The customizations callbacks for SendGrid Mail object.
+     *
+     * @var array
+     */
+    private $customizeCallbacks = [];
+
     /**
      * Create a new SendGrid channel instance.
      *
@@ -248,6 +255,11 @@ public function build(): Mail
             $email->addAttachment($attachment);
         }
 
+        if (count($this->customizeCallbacks)) {
+            foreach ($this->customizeCallbacks as $callback) {
+                $callback($email);
+            }
+        }
 
         return $email;
     }
@@ -274,4 +286,15 @@ public function enableSandboxMode()
     {
         return $this->setSandboxMode(true);
     }
+
+    /**
+     * Pass a callback that will be called with the SendGrid message
+     * before it is sent. This allows you to fully customize the message using the SendGrid library's API.
+     */
+    public function customize($callback)
+    {
+        $this->customizeCallbacks[] = $callback;
+
+        return $this;
+    }
 }

tests/SendGridMessageTest.php

@@ -164,4 +164,17 @@ public function testEmbeddingFromData()
         $this->assertEquals('inline', $attachment->getDisposition());
         $this->assertEquals('blank.png', $attachment->getContentID());
     }
+
+    public function testCustomizeCallback()
+    {
+        $message = new SendGridMessage('template-id');
+        $mailRef = null;
+
+        $message->customize(function ($mail) use (&$mailRef) {
+            $mailRef = $mail;
+        });
+
+        $message->build();
+        $this->assertInstanceOf(\SendGrid\Mail\Mail::class, $mailRef);
+    }
 }