Merge pull request #27 from eileenmcnaughton/mass_mailing

Add mass mailing functions.

README.md

@@ -33,10 +33,11 @@
    - [Text Body](#email-text-body)
    - [HTML Body](#email-html-body)
    - [Attachments](#email-attachments)
-5. [Factory](#factory)
-6. [Exceptions](#exceptions)
-7. [Logging](#logging)
-8. [License](#license-section)
+5. [Mass Mailings](#mass-mailings)
+6. [Factory](#factory)
+7. [Exceptions](#exceptions)
+8. [Logging](#logging)
+9. [License](#license-section)
 
 <a name="requirements"></a>
 ## Requirements
@@ -403,6 +404,89 @@ use Omnimail\Omnimail;
 $mailer = Omnimail::create(Omnimail::AMAZONSES, ['accessKey' => $accessKey, 'secretKey' => $secretKey]);
 ```
 
+<a name="mass-mailings"></a>
+## Mass Mailings
+
+The mass mailing component is for interacting with mass mailing providers. Currently the code focusses on data retrieval, but in future it should also define creating and sending mass mailings.
+
+There are 2 functions currently described for the Mass mailings interface `getMailings` and `getRecipients`.
+
+__getMailings__
+
+```php
+    $mailer = Omnimail::create('Silverpop', array('credentials' => new Credentials(array('username' => $userName...)))->getMailings();
+    $mailer->setStartTimeStamp(strtotime('7 days ago'));
+    $mailer->setEndTimeStamp(strtotime('now'));
+    // Instead of using set methods a Credentials object can be passed in ie.
+    // Omnimail::create('Silverpop', array('credentials' => new Credentials(array('username' => $userName...)));
+    // The advantage of using the Credentials object is that the object will not disclose
+    // the credentials when var_dump or similar is called, helping to make the code
+    // more secure.
+
+    $mailings = $mailer->getResponse();
+    for ($i = 0; $i < 15; $i++) {
+      if (!$mailings->isCompleted()) {
+        sleep(15);
+      }
+      else {
+        foreach (\Omnimail\Responses\MailingsResponse $mailings as \Omnimail\Responses\Mailing $mailing) {
+
+           $detail => array(
+             'subject' => $mailing→getSubject(),
+             'external_identifier' => $mailing->getMailingIdentifier(),
+             'name' => $mailing->getName(),
+             'scheduled_date' => $mailing->getScheduledDate(),
+             'start_date' => $mailing->getSendStartDate(),
+             'number_sent' => $mailing->getNumberSent(),
+             'body_html' => $mailing->getHtmlBody(),
+             'body_text' => $mailing→getTextBody(),
+             // Note that in the case of Silverpop these statistics are not retrieved by the
+             // same api call. This is invisible to the calling function, and unless
+             // stats are requested they are not retrieved.
+             'number_bounced' => $mailing->getNumberBounces(),
+             'number_opened_total' => $mailing->getNumberOpens(),
+             'number_opened_unique' => $mailing->getNumberUniqueOpens(),
+             'number_unsubscribed' => $mailing->getNumberUnsubscribes(),
+             'number_suppressed' => $mailing->getNumberSuppressedByProvider(),
+             // 'forwarded'
+             'number_blocked' => $mailing->getNumberBlocked(),
+             // 'clicked_total' => $stats['NumGrossClick'],
+             'number_abuse_complaints' => $mailing->getNumberAbuseReports(),
+            );
+          }
+      }
+    }
+
+```    
+
+__getMailings__
+
+```php
+    $mailer = Omnimail::create('Silverpop')->getRecipients();
+    $mailer->setUserName($userName);
+    $mailer->setPassword($password);
+    $mailer->setStartTimeStamp(strtotime('7 days ago'));
+    $mailer->setEndTimeStamp(strtotime('now'));
+    $mailer->setMailingIdentifier(123);
+
+    $recipients = $mailer->getResponse();
+    if (!$recipients->isCompleted()) {
+      // sleep or exit & retry later.
+    }
+
+    foreach (\Omnimail\Responses\RecipientsResponse $recipients as \Omnimail\Responses\Recipient $$recipient) {
+
+     $detail => array(
+       'external_identifier' => $mailing->getMailingIdentifier(),
+       'email' =>  $mailing->getEmail(),
+       'provider_contact_id' => $mailing->getContactIdentifier(),
+       'contact_id' => $mailing->GetContactReference(),
+        // Const ACTION_SENT = ‘Sent’, ACTION_OPENED = ‘Open’, ...
+       'action' => $mailing->getRecipientAction(),
+       'timestamp' => getRecipientActionTimestamp(),
+     );
+```
+
 <a name="exceptions"></a>
 ## Exceptions
 

src/Common/AbstractMailer.php

@@ -3,7 +3,106 @@
 namespace Omnimail\Common;
 
 use Omnimail\MailerInterface;
+use Omnimail\Common\Requests\RequestInterface;
+use Omnimail\Common\Credentials;
 
 abstract class AbstractMailer implements MailerInterface
 {
+    /**
+     * Guzzle client, overridable with mock object in tests.
+     *
+     * @var \GuzzleHttp\Client
+     */
+    protected $client;
+
+    /**
+     * @var Credentials
+     */
+    protected $credentials;
+
+    /**
+     * @return \Omnimail\Common\Credentials
+     */
+    public function getCredentials()
+    {
+        return $this->credentials;
+    }
+
+    /**
+     * @param \Omnimail\Common\Credentials $credentials
+     */
+    public function setCredentials($credentials)
+    {
+        $this->credentials = $credentials;
+    }
+
+    /**
+     * @return \GuzzleHttp\Client
+     */
+    public function getClient()
+    {
+        return $this->client;
+    }
+
+    /**
+     * @param \GuzzleHttp\Client $client
+     */
+    public function setClient($client)
+    {
+        $this->client = $client;
+    }
+
+    /**
+     * Initialize a request object
+     *
+     * This function is usually used to initialise objects of type
+     * BaseRequest (or a non-abstract subclass of it)
+     * using existing parameters from this gateway.
+     *
+     * If a client has been set on this class it will passed through,
+     * allowing a mock guzzle client to be used for testing.
+     *
+     * Example:
+     *
+     * <code>
+     *   function myRequest($parameters) {
+     *     $this->createRequest('MyRequest', $parameters);
+     *   }
+     *   class MyRequest extends SilverpopBaseRequest {};
+     *
+     *   // Create the mailer
+     *   $mailer = Omnimail::create('Silverpop', $parameters);
+     *
+     *   // Create the request object
+     *   $myRequest = $mailer->myRequest($someParameters);
+     * </code>
+     *
+     * @param string $class The request class name
+     * @param array $parameters
+     *
+     * @return RequestInterface
+     */
+    protected function createRequest($class, array $parameters)
+    {
+        if (!isset($parameters['credentials'])) {
+            $parameters['credentials'] = new Credentials(array_intersect_key($this->getCredentialFields(), $parameters));
+        }
+        return new $class($parameters);
+    }
+
+    /**
+     * Get an array of the credential fields.
+     *
+     * @return array
+     *   Array keyed by fieldname with details as fields - eg.
+     *    array(
+     *      'username' => array('type' => 'String', 'required' => TRUE),
+     *       'password' => array('type' => 'String', 'required' => TRUE),
+     *       'engage_server' => array('type' => 'String', 'required' => FALSE, 'default' => 4),
+     *   );
+     */
+    public function getCredentialFields()
+    {
+        return array();
+    }
 }

src/Common/Credentials.php

@@ -0,0 +1,67 @@
+<?php
+/**
+ * Created by IntelliJ IDEA.
+ * User: emcnaughton
+ * Date: 6/21/17
+ * Time: 11:30 AM
+ */
+
+namespace Omnimail\Common;
+
+/**
+ * Class Credentials
+ *
+ * Object for storing credentials. This is excluded from debug output for privacy.
+ *
+ * This class has some further ideas for protecting data
+ *
+ * https://github.com/Payum/Payum/blob/master/src/Payum/Core/Security/SensitiveValue.php
+ *
+ * @package Omnimail\Common
+ */
+class Credentials implements CredentialsInterface
+{
+    private $credentials = array();
+
+    /**
+     * @return array
+     */
+    public function getCredentials()
+    {
+        return $this->credentials;
+    }
+
+    /**
+     * @param array $credentials
+     */
+    public function setCredentials($credentials)
+    {
+        $this->credentials = $credentials;
+    }
+
+    public function __construct($credentials)
+    {
+        $this->credentials = $credentials;
+    }
+
+    /**
+     * Get a single credential parameter.
+     *
+     * @param string $parameter
+     * @return mixed|null
+     */
+    public function get($parameter)
+    {
+        return isset($this->credentials[$parameter]) ? $this->credentials[$parameter] : null;
+    }
+
+    /**
+     * Magic method http://php.net/manual/en/language.oop5.magic.php#object.debuginfo
+     *
+     * We override this to ensure that the credentials are
+     * excluded from var_dump.
+     */
+    public function __debugInfo()
+    {
+    }
+}

src/Common/CredentialsInterface.php

@@ -0,0 +1,30 @@
+<?php
+/**
+ * Created by IntelliJ IDEA.
+ * User: emcnaughton
+ * Date: 5/4/17
+ * Time: 10:35 AM
+ */
+
+namespace Omnimail\Common;
+
+/**
+ * Interface CredentialsInterface
+ *
+ * @package Omnimail
+ */
+interface CredentialsInterface
+{
+    /**
+     * Set credentials.
+     *
+     * @param array $credentials
+     */
+    public function setCredentials($credentials);
+
+    /**
+     * @param $parameter
+     * @return mixed
+     */
+    public function get($parameter);
+}

src/Common/Factory.php

@@ -94,6 +94,9 @@ public function create($class, array $parameters = [])
         }
 
         $instance = new $class();
+        if (method_exists($instance, 'getCredentialFields') && !isset($parameters['credentials'])) {
+            $parameters['credentials'] = new Credentials(array_intersect_key($parameters, $instance->getCredentialFields()));
+        }
         Helper::initialize($instance, $parameters);
         return $instance;
     }