Merge pull request #144 from nickvanderveeken/feature/sparkpost-dev

SparkPost: Add template-based message support and basic sending-domain registration functions

docs/SparkPost.md

@@ -1,10 +1,9 @@
-
 SparkPost
-
+=========
 
 This transport layer forms the coupling between Laminas\Mail and the Email Service Provider [SparkPost](http://sparkpost.com).
 The transport is a drop-in component and can be used to send email messages including Cc & Bcc addresses and attachments.
-The SparkPost api docks are here:  https://developers.sparkpost.com/api/ .
+The SparkPost API docks are here:  https://developers.sparkpost.com/api/ .
 
 
 Installation
@@ -22,6 +21,11 @@ Usage
 
 SlmMail consumes for SparkPost just the standard `Laminas\Mail\Message` object.
 
+When the SparkPostService was constructed with a DKIM-config object, the following methods let you register, verify and remove sending domains:
+
+* registerSendingDomain: Registers a new sending domain using the default DKIM keypair and selector that were configured using the constructor. If the sending domain already exists in SparkPost, the existing sending domain is preserved and the function returns successfully.
+* removeSendingDomain: Remove a sending domain. If the sending domains does not exist on SparkPost the fuction returns successfully.
+* verifySendingDomain: Requests verification of the DKIM-record of a previously registered sending domain.
 
 #### Attachments
 

src/Factory/SparkPostServiceFactory.php

@@ -58,7 +58,8 @@ public function __invoke(ContainerInterface $container, $requestedName, array $o
             );
         }
 
-        $service = new SparkPostService($config['slm_mail']['spark_post']['key']);
+        $apiKey = $config['slm_mail']['spark_post']['key'];
+        $service = new SparkPostService($apiKey);
 
         $client = $container->get('SlmMail\Http\Client');
         $service->setClient($client);

src/Mail/Message/SparkPost.php

@@ -2,18 +2,43 @@
 
 namespace SlmMail\Mail\Message;
 
+use Laminas\Mail\Address\AddressInterface;
 use Laminas\Mail\Message;
 
 class SparkPost extends Message
 {
     /**
-     * @var array
+     * Options that will be passed along with the API call when sending the message
+     * @var array $options
      */
     protected $options = [];
 
+    /**
+     * SparkPost Template ID to be rendered, if specified
+     * @var string|null $template
+     */
+    protected $template = null;
+
+    /**
+     * Array of global substitution variables for email (template) rendering
+     * @var array $globalVariables
+     */
+    protected $globalVariables = [];
+
+    /**
+     * Array of recipient-specific substitution variables for email (template) rendering
+     * @var array $variables
+     */
+    protected $variables = [];
+
     public function __construct(array $options = [])
     {
         $this->setOptions($options);
+
+        // make SparkPost message transactional by default (API defaults to non-transactional)
+        if (!array_key_exists('transactional', $options)) {
+            $this->setTransactional();
+        }
     }
 
     public function setOptions(array $options): SparkPost
@@ -27,4 +52,127 @@ public function getOptions(): array
     {
         return $this->options;
     }
+
+    /**
+     * Set the value of a single option by name
+     */
+    public function setOption(string $name, $value): SparkPost
+    {
+        $this->options[$name] = $value;
+
+        return $this;
+    }
+
+    /**
+     * Get the value of a single option by name, or null if the option is undefined
+     */
+    public function getOption(string $name)
+    {
+        if (array_key_exists($name, $this->options)) {
+            return $this->options[$name];
+        }
+
+        return null;
+    }
+
+    /**
+     * Indicate to SparkPost that this is a transactional message
+     */
+    public function setTransactional(bool $transactional = true): SparkPost
+    {
+        return $this->setOption('transactional', $transactional);
+    }
+
+    /**
+     * Returns true when this is a transactional message
+     */
+    public function isTransactional(): bool
+    {
+        return $this->getOption('transactional');
+    }
+
+    /**
+     * Set SparkPost template ID to use
+     *
+     * @param  string|null $template
+     * @return self
+     */
+    public function setTemplateId(?string $template): SparkPost
+    {
+        $this->template = $template;
+        return $this;
+    }
+
+    /**
+     * Get SparkPost template ID to use
+     *
+     * @return string|null
+     */
+    public function getTemplateId(): ?string
+    {
+        return $this->template;
+    }
+
+    /**
+     * Set the global substitution variables to use with the template
+     */
+    public function setGlobalVariables(array $globalVariables): SparkPost
+    {
+        $this->globalVariables = $globalVariables;
+        return $this;
+    }
+
+    /**
+     * Get the global substitution variables to use with the template
+     */
+    public function getGlobalVariables(): array
+    {
+        return $this->globalVariables;
+    }
+
+    /**
+     * Set the substitution variables for a given recipient as identified by its email address
+     */
+    public function setVariables(string $recipient, array $variables): SparkPost
+    {
+        $this->variables[$recipient] = $variables;
+        return $this;
+    }
+
+    /**
+     * Set the substitution variables for all recipients (indexed array where recipient's email address is the key)
+     */
+    public function setAllVariables(array $variablesPerRecipient): SparkPost
+    {
+        $this->variables = $variablesPerRecipient;
+        return $this;
+    }
+
+    /**
+     * Get the substitution variables for all recipients
+     *
+     * @return array
+     */
+    public function getVariables(): array
+    {
+        return $this->variables;
+    }
+
+    public function getSender(): ?AddressInterface
+    {
+        $sender = parent::getSender();
+
+        if (!($sender instanceof AddressInterface)) {
+            $from = parent::getFrom();
+            if (!count($from)) {
+                return null;
+            }
+
+            // get first sender from the list
+            $from->rewind();
+            $sender = $from->current();
+        }
+
+        return $sender;
+    }
 }