Merge pull request #69 from j4m3s/ISSUE-58

Message Events

4 files changed, 77 insertions, 2 deletions

diff --git a/lib/SparkPost/APIResource.php b/lib/SparkPost/APIResource.php
index 3d0f8c1..10305f2 100644
--- a/lib/SparkPost/APIResource.php
+++ b/lib/SparkPost/APIResource.php
@@ -130,7 +130,8 @@ class APIResource {
   /**
    * assembles a URL for a request
    * @param string $resourcePath path after the initial endpoint
-   * @param array $options array with an optional value of query with values to build a querystring from.
+   * @param array $options array with an optional value of query with values to build a querystring from.  Any
+   *                        query elements that are themselves arrays will be imploded into a comma separated list. 
    * @return string the assembled URL
    */
   private function buildUrl($resourcePath, $options) {
@@ -140,6 +141,13 @@ class APIResource {
     }
 
     if( !empty($options['query'])) {
+      // check each query element - if it's an array, implode it to match the API-accepted format
+      foreach($options['query'] as &$element) {
+        if(is_array($element)) {
+          $element = implode(",", $element);
+        }
+      }
+
       $queryString = http_build_query($options['query']);
       $url .= '?'.$queryString;
     }
diff --git a/lib/SparkPost/MessageEvents.php b/lib/SparkPost/MessageEvents.php
new file mode 100644
index 0000000..788b752
--- /dev/null
+++ b/lib/SparkPost/MessageEvents.php
@@ -0,0 +1,60 @@
+<?php
+namespace SparkPost;
+
+/**
+ * SDK class for querying the Message Events API
+ *
+ * @see https://developers.sparkpost.com/api/#/reference/message-events
+ */
+class MessageEvents extends APIResource
+{
+  /**
+   * @var string
+   */
+  public $endpoint = 'message-events';
+
+  /**
+   * Method for issuing search requests to the Message Events API.
+   *
+   * The method passes-through all of the query parameters - the valid ones are listed at
+   * @link https://developers.sparkpost.com/api/#/reference/message-events/events-documentation/search-for-message-events
+   *
+   * @param array $queryParams  The query parameters.  Note that a query parameter containing an array
+   * is collapsed into a comma-separated list.
+   *
+   * @return array The result of the query.
+   */
+  public function search(Array $queryParams)
+  {
+    // check for DateTime objects & replace them with the formatted string equivalent
+    foreach(["from", "to"] as $dateTimeParam) {
+      if (isset($queryParams[$dateTimeParam]) && $queryParams[$dateTimeParam] instanceof \DateTime) {
+        // the message events API doesn't allow the seconds or GMT offset, so strip them
+        $queryParams[$dateTimeParam] = substr($queryParams[$dateTimeParam]->format(\DateTime::ATOM), 0, 16);
+      }
+    }
+
+    return $this->get(null, $queryParams);
+  }
+
+  /**
+   * List descriptions of the event fields that could be included in a response from the MessageEvent::search() method.
+   *
+   * @return array The event field descriptions.
+   */
+  public function documentation() {
+    return $this->get("events/documentation");
+  }
+
+  /**
+   * List examples of the event data that will be included in a response from the MessageEvent::search() method.
+   *
+   * @param array $events (optional) Event types for which to get a sample payload.  If not provided, samples
+   * for all events will be returned.
+   *
+   * @return array Sample events.
+   */
+  public function samples(Array $events = []) {
+    return $this->get("events/samples", ["events"=>$events]);
+  }
+}
\ No newline at end of file
diff --git a/lib/SparkPost/SparkPost.php b/lib/SparkPost/SparkPost.php
index 4cfe5b7..e5f029a 100644
--- a/lib/SparkPost/SparkPost.php
+++ b/lib/SparkPost/SparkPost.php
@@ -6,6 +6,7 @@ use Ivory\HttpAdapter\HttpAdapterInterface;
 class SparkPost {
 
   public $transmission;
+  public $messageEvents;
 
   /**
    * Connection config for making requests.
@@ -45,6 +46,7 @@ class SparkPost {
     $this->setHttpAdapter($httpAdapter);
 
     $this->transmission = new Transmission($this);
+    $this->messageEvents = new MessageEvents($this);
   }
 
   /**
diff --git a/lib/SparkPost/Transmission.php b/lib/SparkPost/Transmission.php
index d357b45..ae5d071 100644
--- a/lib/SparkPost/Transmission.php
+++ b/lib/SparkPost/Transmission.php
@@ -75,7 +75,7 @@ class Transmission extends APIResource {
    *  'replyTo': string,
    *  'rfc822': string,
    *  'sandbox': boolean,
-   *  'startTime': string,
+   *  'startTime': string | \DateTime,
    *  'subject': string,
    *  'substitutionData': array,
    *  'template': string,
@@ -89,6 +89,11 @@ class Transmission extends APIResource {
    * @return array API repsonse represented as key-value pairs
    */
   public function send( $transmissionConfig ) {
+    if(isset($transmissionConfig["startTime"]) && $transmissionConfig["startTime"] instanceof \DateTime)
+      {
+        $transmissionConfig["startTime"] = $transmissionConfig["startTime"]->format(\DateTime::ATOM);
+      }
+
     return $this->create( $transmissionConfig );
   }