Routes API (#249)

* Add initial (empty) Routes PHP Unit Test file

We still need to provide the automated tests

* Add initial Routes file

* Describe API Methods

* Inherit method from TestCase - adding @inheritdoc annotation

* Add new DTOs to map API responses to known objects

* Add new Response to manage the Routes list

* Implement method to retrieve a list of Routes

* Add new Response to manage a single Route resource

* Implement method to retrieve a single Route

* Set ShowResponse as final

* Add new Response to manage the Create process

* Implement method to create a new Route

* Fix missing annotation

* Add new Response to manage the Delete Route process

* Implement method to delete a Route based on the ID

* Add new Response to manage the Update Route process

This response is based on Domain API docs due there are no examples on
Routes API docs. We may need to update the response.

* Implement method to update a Route based on the ID

* Require a $limit value greater than 0

* Require a $skip value greater than or equal to 0

* Set UpdateResponse as final

* Add new (empty) public methods to test the Routes API

* Provide method to get the Routes API from Mailgun Client

* Add missed annotation

* Update ShowResponse to return an instance of ApiResponse instead of the DTO

* Update annotation

* Fix annotation

* Update array $actions to provide an empty array by default

* Update parameters to make sure the last arg always is a DateTime (or null)

* Use empty()

* Remove DTO suffix

* Move DTOs to the parent folder/namespace

* Fix annotations

src/Mailgun/Api/Routes.php

@@ -0,0 +1,157 @@
+<?php
+
+/*
+ * Copyright (C) 2013-2016 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Api;
+
+use Mailgun\Assert;
+use Mailgun\Resource\Api\Routes\Response\CreateResponse;
+use Mailgun\Resource\Api\Routes\Response\DeleteResponse;
+use Mailgun\Resource\Api\Routes\Response\IndexResponse;
+use Mailgun\Resource\Api\Routes\Response\ShowResponse;
+use Mailgun\Resource\Api\Routes\Response\UpdateResponse;
+
+/**
+ * {@link https://documentation.mailgun.com/api-routes.html}.
+ *
+ * @author David Garcia <me@davidgarcia.cat>
+ */
+class Routes extends HttpApi
+{
+    /**
+     * Fetches the list of Routes.
+     *
+     * @param int $limit Maximum number of records to return. (100 by default)
+     * @param int $skip  Number of records to skip. (0 by default)
+     *
+     * @return IndexResponse
+     */
+    public function index($limit = 100, $skip = 0)
+    {
+        Assert::integer($limit);
+        Assert::integer($skip);
+        Assert::greaterThan($limit, 0);
+        Assert::greaterThanEq($skip, 0);
+
+        $params = [
+            'limit' => $limit,
+            'skip' => $skip,
+        ];
+
+        $response = $this->httpGet('/v3/routes', $params);
+
+        return $this->safeDeserialize($response, IndexResponse::class);
+    }
+
+    /**
+     * Returns a single Route object based on its ID.
+     *
+     * @param string $routeId Route ID returned by the Routes::index() method
+     *
+     * @return ShowResponse
+     */
+    public function show($routeId)
+    {
+        Assert::stringNotEmpty($routeId);
+
+        $response = $this->httpGet(sprintf('/v3/routes/%s', $routeId));
+
+        return $this->safeDeserialize($response, ShowResponse::class);
+    }
+
+    /**
+     * Creates a new Route.
+     *
+     * @param string $expression  A filter expression like "match_recipient('.*@gmail.com')"
+     * @param array  $actions     Route action. This action is executed when the expression evaluates to True. Example: "forward('alice@example.com')"
+     * @param string $description An arbitrary string
+     * @param int    $priority    Integer: smaller number indicates higher priority. Higher priority routes are handled first. Defaults to 0.
+     *
+     * @return CreateResponse
+     */
+    public function create($expression, array $actions, $description, $priority = 0)
+    {
+        Assert::string($expression);
+        Assert::isArray($actions);
+        Assert::string($description);
+        Assert::integer($priority);
+
+        $params = [
+            'priority' => $priority,
+            'expression' => $expression,
+            'action' => $actions,
+            'description' => $description,
+        ];
+
+        $response = $this->httpPost('/v3/routes', $params);
+
+        return $this->safeDeserialize($response, CreateResponse::class);
+    }
+
+    /**
+     * Updates a given Route by ID. All parameters are optional.
+     * This API call only updates the specified fields leaving others unchanged.
+     *
+     * @param string      $routeId     Route ID returned by the Routes::index() method
+     * @param string|null $expression  A filter expression like "match_recipient('.*@gmail.com')"
+     * @param array|null  $actions     Route action. This action is executed when the expression evaluates to True. Example: "forward('alice@example.com')"
+     * @param string|null $description An arbitrary string
+     * @param int|null    $priority    Integer: smaller number indicates higher priority. Higher priority routes are handled first. Defaults to 0.
+     *
+     * @return UpdateResponse
+     */
+    public function update($routeId, $expression = null, array $actions = [], $description = null, $priority = null)
+    {
+        Assert::stringNotEmpty($routeId);
+        Assert::nullOrString($expression);
+        Assert::isArray($actions);
+        Assert::nullOrString($description);
+        Assert::nullOrInteger($priority);
+
+        $params = [];
+
+        if (!empty($expression)) {
+            $params['expression'] = trim($expression);
+        }
+
+        foreach ($actions as $action) {
+            Assert::stringNotEmpty($action);
+
+            $params['action'] = isset($params['action']) ? $params['action'] : [];
+            $params['action'][] = $action;
+        }
+
+        if (!empty($description)) {
+            $params['description'] = trim($description);
+        }
+
+        if (!empty($priority)) {
+            $params['priority'] = $priority;
+        }
+
+        $response = $this->httpPut(sprintf('/v3/routes/%s', $routeId), $params);
+
+        return $this->safeDeserialize($response, UpdateResponse::class);
+    }
+
+    /**
+     * Deletes a Route based on the ID.
+     *
+     * @param string $routeId Route ID returned by the Routes::index() method
+     *
+     * @return DeleteResponse
+     */
+    public function delete($routeId)
+    {
+        Assert::stringNotEmpty($routeId);
+
+        $response = $this->httpDelete(sprintf('/v3/routes/%s', $routeId));
+
+        return $this->safeDeserialize($response, DeleteResponse::class);
+    }
+}

src/Mailgun/Mailgun.php

@@ -277,6 +277,14 @@ class Mailgun
         return new Api\Event($this->httpClient, $this->requestBuilder, $this->deserializer);
     }
 
+    /**
+     * @return Api\Routes
+     */
+    public function routes()
+    {
+        return new Api\Routes($this->httpClient, $this->requestBuilder, $this->deserializer);
+    }
+
     /**
      * @return Api\Webhook
      */

src/Mailgun/Resource/Api/Domain/DeleteResponse.php

@@ -28,6 +28,7 @@ final class DeleteResponse implements ApiResponse
 
     /**
      * @param string $message
+     * @param string $error
      */
     private function __construct($message, $error)
     {

src/Mailgun/Resource/Api/Routes/Action.php

@@ -0,0 +1,57 @@
+<?php
+
+/*
+ * Copyright (C) 2013-2016 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Resource\Api\Routes;
+
+/**
+ * @author David Garcia <me@davidgarcia.cat>
+ */
+final class Action
+{
+    /**
+     * @var string
+     */
+    private $action;
+
+    /**
+     * Action Named Constructor to build several Action DTOs provided by an Array.
+     *
+     * @param array $data
+     *
+     * @return Action[]
+     */
+    public static function createMultiple(array $data)
+    {
+        $items = [];
+
+        foreach ($data as $action) {
+            $items[] = new self($action);
+        }
+
+        return $items;
+    }
+
+    /**
+     * Action Private Constructor.
+     *
+     * @param $action
+     */
+    private function __construct($action)
+    {
+        $this->action = $action;
+    }
+
+    /**
+     * @return string
+     */
+    public function getAction()
+    {
+        return $this->action;
+    }
+}

src/Mailgun/Resource/Api/Routes/Response/CreateResponse.php

@@ -0,0 +1,68 @@
+<?php
+
+/*
+ * Copyright (C) 2013-2016 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Resource\Api\Routes\Response;
+
+use Mailgun\Resource\Api\Routes\Route;
+use Mailgun\Resource\ApiResponse;
+
+/**
+ * @author David Garcia <me@davidgarcia.cat>
+ */
+final class CreateResponse implements ApiResponse
+{
+    /**
+     * @var string
+     */
+    private $message;
+
+    /**
+     * @var Route
+     */
+    private $route;
+
+    /**
+     * {@inheritdoc}
+     */
+    public static function create(array $data)
+    {
+        $message = isset($data['message']) ? $data['message'] : null;
+        $route = isset($data['route']) ? Route::create($data['route']) : null;
+
+        return new self($message, $route);
+    }
+
+    /**
+     * CreateResponse Private Constructor.
+     *
+     * @param string|null $message
+     * @param Route|null  $route
+     */
+    private function __construct($message = null, Route $route = null)
+    {
+        $this->message = $message;
+        $this->route = $route;
+    }
+
+    /**
+     * @return string
+     */
+    public function getMessage()
+    {
+        return $this->message;
+    }
+
+    /**
+     * @return Route
+     */
+    public function getRoute()
+    {
+        return $this->route;
+    }
+}

src/Mailgun/Resource/Api/Routes/Response/DeleteResponse.php

@@ -0,0 +1,67 @@
+<?php
+
+/*
+ * Copyright (C) 2013-2016 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Resource\Api\Routes\Response;
+
+use Mailgun\Resource\ApiResponse;
+
+/**
+ * @author David Garcia <me@davidgarcia.cat>
+ */
+final class DeleteResponse implements ApiResponse
+{
+    /**
+     * @var string
+     */
+    private $message;
+
+    /**
+     * @var string
+     */
+    private $error;
+
+    /**
+     * @param array $data
+     *
+     * @return self
+     */
+    public static function create(array $data)
+    {
+        return new self(
+            isset($data['message']) ? $data['message'] : null,
+            isset($data['error']) ? $data['error'] : null
+        );
+    }
+
+    /**
+     * @param string $message
+     * @param string $error
+     */
+    private function __construct($message, $error)
+    {
+        $this->message = $message;
+        $this->error = $error;
+    }
+
+    /**
+     * @return string
+     */
+    public function getMessage()
+    {
+        return $this->message;
+    }
+
+    /**
+     * @return string
+     */
+    public function getError()
+    {
+        return $this->error;
+    }
+}

src/Mailgun/Resource/Api/Routes/Response/IndexResponse.php

@@ -0,0 +1,77 @@
+<?php
+
+/*
+ * Copyright (C) 2013-2016 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Resource\Api\Routes\Response;
+
+use Mailgun\Resource\Api\Routes\Route;
+use Mailgun\Resource\ApiResponse;
+
+/**
+ * @author David Garcia <me@davidgarcia.cat>
+ */
+final class IndexResponse implements ApiResponse
+{
+    /**
+     * @var int
+     */
+    private $totalCount;
+
+    /**
+     * @var Route[]
+     */
+    private $items;
+
+    /**
+     * {@inheritdoc}
+     */
+    public static function create(array $data)
+    {
+        $items = [];
+
+        if (isset($data['items'])) {
+            foreach ($data['items'] as $item) {
+                $items[] = Route::create($item);
+            }
+        }
+
+        if (isset($data['total_count'])) {
+            $count = $data['total_count'];
+        } else {
+            $count = count($items);
+        }
+
+        return new self($count, $items);
+    }
+
+    /**
+     * @param int     $totalCount
+     * @param Route[] $items
+     */
+    private function __construct($totalCount, array $items)
+    {
+        $this->totalCount = $totalCount;
+        $this->items = $items;
+    }
+
+    /**
+     * @return int
+     */
+    public function getTotalCount()
+    {
+        return $this->totalCount;
+    }
+
+    /**
+     * @return Route[]
+     */
+    public function getRoutes()
+    {
+        return $this->items;
+    }
+}

src/Mailgun/Resource/Api/Routes/Response/ShowResponse.php

@@ -0,0 +1,54 @@
+<?php
+
+/*
+ * Copyright (C) 2013-2016 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Resource\Api\Routes\Response;
+
+use Mailgun\Resource\Api\Routes\Route;
+use Mailgun\Resource\ApiResponse;
+
+/**
+ * @author David Garcia <me@davidgarcia.cat>
+ */
+final class ShowResponse implements ApiResponse
+{
+    /**
+     * @var Route|null
+     */
+    private $route;
+
+    /**
+     * {@inheritdoc}
+     */
+    public static function create(array $data)
+    {
+        if (isset($data['route'])) {
+            return new self(Route::create($data['route']));
+        }
+
+        return new self();
+    }
+
+    /**
+     * ShowResponse constructor.
+     *
+     * @param Route|null $route
+     */
+    private function __construct(Route $route = null)
+    {
+        $this->route = $route;
+    }
+
+    /**
+     * @return Route|null
+     */
+    public function getRoute()
+    {
+        return $this->route;
+    }
+}

src/Mailgun/Resource/Api/Routes/Response/UpdateResponse.php

@@ -0,0 +1,51 @@
+<?php
+
+/*
+ * Copyright (C) 2013-2016 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Resource\Api\Routes\Response;
+
+use Mailgun\Resource\ApiResponse;
+
+/**
+ * @author David Garcia <me@davidgarcia.cat>
+ */
+final class UpdateResponse implements ApiResponse
+{
+    /**
+     * @var string
+     */
+    private $message;
+
+    /**
+     * @param array $data
+     *
+     * @return self
+     */
+    public static function create(array $data)
+    {
+        return new self(
+            isset($data['message']) ? $data['message'] : null
+        );
+    }
+
+    /**
+     * @param string $message
+     */
+    private function __construct($message)
+    {
+        $this->message = $message;
+    }
+
+    /**
+     * @return string
+     */
+    public function getMessage()
+    {
+        return $this->message;
+    }
+}

src/Mailgun/Resource/Api/Routes/Route.php

@@ -0,0 +1,133 @@
+<?php
+
+/*
+ * Copyright (C) 2013-2016 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Resource\Api\Routes;
+
+/**
+ * @author David Garcia <me@davidgarcia.cat>
+ */
+final class Route
+{
+    /**
+     * @var string
+     */
+    private $id;
+
+    /**
+     * @var int
+     */
+    private $priority;
+
+    /**
+     * @var string
+     */
+    private $filter;
+
+    /**
+     * @var Action[]
+     */
+    private $actions;
+
+    /**
+     * @var string
+     */
+    private $description;
+
+    /**
+     * @var \DateTime
+     */
+    private $createdAt;
+
+    /**
+     * Route Named Constructor.
+     *
+     * @param array $data
+     *
+     * @return Route
+     */
+    public static function create(array $data)
+    {
+        return new self(
+            isset($data['id']) ? $data['id'] : null,
+            isset($data['priority']) ? $data['priority'] : null,
+            isset($data['expression']) ? $data['expression'] : null,
+            isset($data['actions']) ? $data['actions'] : [],
+            isset($data['description']) ? $data['description'] : null,
+            isset($data['created_at']) ? new \DateTime($data['created_at']) : null
+        );
+    }
+
+    /**
+     * Route Private Constructor.
+     *
+     * @param string    $id
+     * @param int       $priority
+     * @param string    $expression
+     * @param array     $actions
+     * @param string    $description
+     * @param \DateTime $createdAt
+     */
+    private function __construct($id, $priority, $expression, $actions, $description, \DateTime $createdAt = null)
+    {
+        $this->id = $id;
+        $this->priority = $priority;
+        $this->filter = $expression;
+        $this->actions = Action::createMultiple($actions);
+        $this->description = $description;
+        $this->createdAt = $createdAt;
+    }
+
+    /**
+     * @return string
+     */
+    public function getId()
+    {
+        return $this->id;
+    }
+
+    /**
+     * @return Action[]
+     */
+    public function getActions()
+    {
+        return $this->actions;
+    }
+
+    /**
+     * @return string
+     */
+    public function getDescription()
+    {
+        return $this->description;
+    }
+
+    /**
+     * @return string
+     */
+    public function getFilter()
+    {
+        return $this->filter;
+    }
+
+    /**
+     * @return int
+     */
+    public function getPriority()
+    {
+        return $this->priority;
+    }
+
+    /**
+     * @return \DateTime
+     */
+    public function getCreatedAt()
+    {
+        return $this->createdAt;
+    }
+}

tests/Api/RoutesTest.php

@@ -0,0 +1,49 @@
+<?php
+
+/*
+ * Copyright (C) 2013-2016 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Tests\Api;
+
+/**
+ * @author David Garcia <me@davidgarcia.cat>
+ */
+class RoutesTest extends TestCase
+{
+    protected function setUp()
+    {
+        $this->markTestSkipped('Routes API tests not implemented yet.');
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    protected function getApiClass()
+    {
+        return 'Mailgun\Api\Routes';
+    }
+
+    public function testGetRoutesCollection()
+    {
+    }
+
+    public function testGetRoutesResource()
+    {
+    }
+
+    public function testPostRouteResource()
+    {
+    }
+
+    public function testUpdateRouteResource()
+    {
+    }
+
+    public function testDeleteRouteResource()
+    {
+    }
+}