From 1613843c7ea4022f449e3ca94d10c6c5bdf5b23e Mon Sep 17 00:00:00 2001 From: David Garcia Date: Fri, 9 Dec 2016 22:15:06 +0000 Subject: [PATCH] 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 | 157 ++++++++++++++++++ src/Mailgun/Mailgun.php | 8 + .../Resource/Api/Domain/DeleteResponse.php | 1 + src/Mailgun/Resource/Api/Routes/Action.php | 57 +++++++ .../Api/Routes/Response/CreateResponse.php | 68 ++++++++ .../Api/Routes/Response/DeleteResponse.php | 67 ++++++++ .../Api/Routes/Response/IndexResponse.php | 77 +++++++++ .../Api/Routes/Response/ShowResponse.php | 54 ++++++ .../Api/Routes/Response/UpdateResponse.php | 51 ++++++ src/Mailgun/Resource/Api/Routes/Route.php | 133 +++++++++++++++ tests/Api/RoutesTest.php | 49 ++++++ 11 files changed, 722 insertions(+) create mode 100644 src/Mailgun/Api/Routes.php create mode 100644 src/Mailgun/Resource/Api/Routes/Action.php create mode 100644 src/Mailgun/Resource/Api/Routes/Response/CreateResponse.php create mode 100644 src/Mailgun/Resource/Api/Routes/Response/DeleteResponse.php create mode 100644 src/Mailgun/Resource/Api/Routes/Response/IndexResponse.php create mode 100644 src/Mailgun/Resource/Api/Routes/Response/ShowResponse.php create mode 100644 src/Mailgun/Resource/Api/Routes/Response/UpdateResponse.php create mode 100644 src/Mailgun/Resource/Api/Routes/Route.php create mode 100644 tests/Api/RoutesTest.php diff --git a/src/Mailgun/Api/Routes.php b/src/Mailgun/Api/Routes.php new file mode 100644 index 0000000..7ec79fa --- /dev/null +++ b/src/Mailgun/Api/Routes.php @@ -0,0 +1,157 @@ + + */ +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); + } +} diff --git a/src/Mailgun/Mailgun.php b/src/Mailgun/Mailgun.php index 29d1364..433fa9a 100644 --- a/src/Mailgun/Mailgun.php +++ b/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 */ diff --git a/src/Mailgun/Resource/Api/Domain/DeleteResponse.php b/src/Mailgun/Resource/Api/Domain/DeleteResponse.php index d830d9b..391c90d 100644 --- a/src/Mailgun/Resource/Api/Domain/DeleteResponse.php +++ b/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) { diff --git a/src/Mailgun/Resource/Api/Routes/Action.php b/src/Mailgun/Resource/Api/Routes/Action.php new file mode 100644 index 0000000..92ac073 --- /dev/null +++ b/src/Mailgun/Resource/Api/Routes/Action.php @@ -0,0 +1,57 @@ + + */ +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; + } +} diff --git a/src/Mailgun/Resource/Api/Routes/Response/CreateResponse.php b/src/Mailgun/Resource/Api/Routes/Response/CreateResponse.php new file mode 100644 index 0000000..4c8212d --- /dev/null +++ b/src/Mailgun/Resource/Api/Routes/Response/CreateResponse.php @@ -0,0 +1,68 @@ + + */ +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; + } +} diff --git a/src/Mailgun/Resource/Api/Routes/Response/DeleteResponse.php b/src/Mailgun/Resource/Api/Routes/Response/DeleteResponse.php new file mode 100644 index 0000000..fb806ff --- /dev/null +++ b/src/Mailgun/Resource/Api/Routes/Response/DeleteResponse.php @@ -0,0 +1,67 @@ + + */ +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; + } +} diff --git a/src/Mailgun/Resource/Api/Routes/Response/IndexResponse.php b/src/Mailgun/Resource/Api/Routes/Response/IndexResponse.php new file mode 100644 index 0000000..9ae92f7 --- /dev/null +++ b/src/Mailgun/Resource/Api/Routes/Response/IndexResponse.php @@ -0,0 +1,77 @@ + + */ +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; + } +} diff --git a/src/Mailgun/Resource/Api/Routes/Response/ShowResponse.php b/src/Mailgun/Resource/Api/Routes/Response/ShowResponse.php new file mode 100644 index 0000000..4110252 --- /dev/null +++ b/src/Mailgun/Resource/Api/Routes/Response/ShowResponse.php @@ -0,0 +1,54 @@ + + */ +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; + } +} diff --git a/src/Mailgun/Resource/Api/Routes/Response/UpdateResponse.php b/src/Mailgun/Resource/Api/Routes/Response/UpdateResponse.php new file mode 100644 index 0000000..39f7506 --- /dev/null +++ b/src/Mailgun/Resource/Api/Routes/Response/UpdateResponse.php @@ -0,0 +1,51 @@ + + */ +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; + } +} diff --git a/src/Mailgun/Resource/Api/Routes/Route.php b/src/Mailgun/Resource/Api/Routes/Route.php new file mode 100644 index 0000000..6f181de --- /dev/null +++ b/src/Mailgun/Resource/Api/Routes/Route.php @@ -0,0 +1,133 @@ + + */ +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; + } +} diff --git a/tests/Api/RoutesTest.php b/tests/Api/RoutesTest.php new file mode 100644 index 0000000..ea0c9f4 --- /dev/null +++ b/tests/Api/RoutesTest.php @@ -0,0 +1,49 @@ + + */ +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() + { + } +}