Merge pull request #69 from j4m3s/ISSUE-58

Message Events

10 files changed, 187 insertions, 3 deletions

diff --git a/.gitignore b/.gitignore
index dae14ef..0a84bbb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,3 +5,4 @@
 test/output/
 examples/example-config.json
 .idea
+/composer.phar
diff --git a/AUTHORS.md b/AUTHORS.md
index 3e269ef..e24ac3d 100644
--- a/AUTHORS.md
+++ b/AUTHORS.md
@@ -5,3 +5,4 @@ php-sparkpost is maintained by Message Systems.
 * Jordan Nornhold <jordan.nornhold@messagesystems.com>, @beardyman
 * Rich Leland <rich.leland@messagesystems.com>, @richleland
 * Matthew April <matthew.japril@gmail.com>
+* James Fellows <james.fellows@8-w.co.uk>
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c44abf9..395c8e5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,7 +3,8 @@ All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased][unreleased]
-- All content has been released to date.
+- Message Events API added.
+- Transmission API now accepts a DateTime object for startDate
 
 ## [1.0.3] - 2016-03-25
 ### Added
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 );
   }
 
diff --git a/test/unit/APIResourceTest.php b/test/unit/APIResourceTest.php
index 1d29c55..c2b0c2a 100644
--- a/test/unit/APIResourceTest.php
+++ b/test/unit/APIResourceTest.php
@@ -84,6 +84,25 @@ class APIResourceTest extends \PHPUnit_Framework_TestCase {
     $this->assertEquals($testBody, $this->resource->get('test'));
   }
 
+  public function testGetCommaSeparated() {
+    $testBody = ['results'=>['my'=>'test']];
+    $requestArray = [
+        "param1" => "param1val",
+        "param2" => ["param2val1", "param2val2"]
+    ];
+    $expectedGetParams = "param1=param1val&param2=" . urlencode("param2val1,param2val2");
+
+    $responseMock = Mockery::mock();
+    $this->sparkPostMock->httpAdapter->shouldReceive('send')->
+      once()->
+      with(matchesPattern("/.*\/test\?{$expectedGetParams}/"), 'GET', Mockery::type('array'), null)->
+      andReturn($responseMock);
+    $responseMock->shouldReceive('getStatusCode')->andReturn(200);
+    $responseMock->shouldReceive('getBody->getContents')->andReturn(json_encode($testBody));
+
+    $this->assertEquals($testBody, $this->resource->get('test', $requestArray));
+  }
+
   public function testDelete() {
     $responseMock = Mockery::mock();
     $this->sparkPostMock->httpAdapter->shouldReceive('send')->
diff --git a/test/unit/MessageEventTest.php b/test/unit/MessageEventTest.php
new file mode 100644
index 0000000..48657e6
--- /dev/null
+++ b/test/unit/MessageEventTest.php
@@ -0,0 +1,71 @@
+<?php
+
+namespace SparkPost;
+
+use \Mockery;
+
+
+class MessageEventTest extends \PHPUnit_Framework_TestCase
+{
+  private $sparkPostMock;
+  private $sut;
+
+  /**
+   * (non-PHPdoc)
+   * @before
+   * @see PHPUnit_Framework_TestCase::setUp()
+   */
+  public function setUp()
+  {
+    $this->sparkPostMock = Mockery::mock('SparkPost\SparkPost', function ($mock) {
+      $mock->shouldReceive('getHttpHeaders')->andReturn([]);
+    });
+    $this->sparkPostMock->httpAdapter = Mockery::mock();
+    $this->sut = new MessageEvents($this->sparkPostMock);
+  }
+
+  public function testDateTimeConversion()
+  {
+    $testBody = ['results' => ['my' => 'test']];
+    $testFrom = new \DateTime("1978-08-27 04:05:02");
+    $testFromStr = urlencode("1978-08-27T04:05");
+    $testTo = new \DateTime("2016-04-04 19:00");
+    $testToStr = urlencode("2016-04-04T19:00");
+
+    $responseMock = Mockery::mock();
+    $this->sparkPostMock->httpAdapter->shouldReceive('send')->
+      once()->
+      with("/message-events/?from={$testFromStr}&to={$testToStr}", 'GET', Mockery::type('array'), null)->
+      andReturn($responseMock);
+    $responseMock->shouldReceive('getStatusCode')->andReturn(200);
+    $responseMock->shouldReceive('getBody->getContents')->andReturn(json_encode($testBody));
+
+    $this->assertEquals($testBody, $this->sut->search(["from" => $testFrom, "to" => $testTo]));
+  }
+
+  public function testDocumentation() {
+    $testBody = ['results' => ['my' => 'test']];
+    $responseMock = Mockery::mock();
+    $this->sparkPostMock->httpAdapter->shouldReceive('send')->
+      once()->
+      with("/message-events/events/documentation", 'GET', Mockery::type('array'), null)->
+      andReturn($responseMock);
+    $responseMock->shouldReceive('getStatusCode')->andReturn(200);
+    $responseMock->shouldReceive('getBody->getContents')->andReturn(json_encode($testBody));
+
+    $this->assertEquals($testBody, $this->sut->documentation());
+  }
+
+  public function testSamples() {
+    $testBody = ['results' => ['my' => 'test']];
+    $responseMock = Mockery::mock();
+    $this->sparkPostMock->httpAdapter->shouldReceive('send')->
+      once()->
+      with("/message-events/events/samples?events=".urlencode("delivery,bounce"), 'GET', Mockery::type('array'), null)->
+      andReturn($responseMock);
+    $responseMock->shouldReceive('getStatusCode')->andReturn(200);
+    $responseMock->shouldReceive('getBody->getContents')->andReturn(json_encode($testBody));
+
+    $this->assertEquals($testBody, $this->sut->samples(["delivery", "bounce"]));
+  }
+}
\ No newline at end of file
diff --git a/test/unit/TransmissionTest.php b/test/unit/TransmissionTest.php
index a985883..ba29b3b 100644
--- a/test/unit/TransmissionTest.php
+++ b/test/unit/TransmissionTest.php
@@ -44,6 +44,22 @@ class TransmissionTest extends \PHPUnit_Framework_TestCase {
     $this->assertEquals($responseBody, $this->resource->send($body));
   }
 
+  public function testSendDateTimeConversion()
+  {
+    $testStartTime = new \DateTime("2016-08-27 13:01:02", new \DateTimeZone("UTC"));
+
+    $responseMock = Mockery::mock();
+    $responseBody = ['results'=>'yay'];
+    $this->sparkPostMock->httpAdapter->shouldReceive('send')->
+      once()->
+      with('/.*\/transmissions/', 'POST', Mockery::type('array'), matchesPattern('/"start_time":"2016-08-27T13:01:02\+00:00"/'))->
+      andReturn($responseMock);
+    $responseMock->shouldReceive('getStatusCode')->andReturn(200);
+    $responseMock->shouldReceive('getBody->getContents')->andReturn(json_encode($responseBody));
+
+    $this->assertEquals($responseBody, $this->resource->send(['startTime'=>$testStartTime]));
+  }
+
   public function testAllWithFilter() {
     $responseMock = Mockery::mock();
     $responseBody = ['results'=>'yay'];