Tag api (#286)

* Started on tag api

* Added TagAPI

* code style

* cs

* removed final

* Adjusting to Davids feedback.

* Added PagingProvider interface

src/Mailgun/Api/Tag.php

@@ -0,0 +1,128 @@
+<?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\Tag\DeleteResponse;
+use Mailgun\Resource\Api\Tag\IndexResponse;
+use Mailgun\Resource\Api\Tag\ShowResponse;
+use Mailgun\Resource\Api\Tag\StatisticsResponse;
+use Mailgun\Resource\Api\Tag\UpdateResponse;
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * {@link https://documentation.mailgun.com/api-tags.html#tags}.
+ *
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+class Tag extends HttpApi
+{
+    /**
+     * Returns a list of tags.
+     *
+     * @param string $domain
+     * @param int    $limit
+     *
+     * @return IndexResponse|ResponseInterface
+     */
+    public function index($domain, $limit = 100)
+    {
+        Assert::stringNotEmpty($domain);
+        Assert::integer($limit);
+
+        $params = [
+            'limit' => $limit,
+        ];
+
+        $response = $this->httpGet(sprintf('/v3/%s/tags', $domain), $params);
+
+        return $this->safeDeserialize($response, IndexResponse::class);
+    }
+
+    /**
+     * Returns a single tag.
+     *
+     * @param string $domain Name of the domain
+     * @param string $tag
+     *
+     * @return ShowResponse|ResponseInterface
+     */
+    public function show($domain, $tag)
+    {
+        Assert::stringNotEmpty($domain);
+        Assert::stringNotEmpty($tag);
+
+        $response = $this->httpGet(sprintf('/v3/%s/tags/%s', $domain, $tag));
+
+        return $this->safeDeserialize($response, ShowResponse::class);
+    }
+
+    /**
+     * Update a tag.
+     *
+     * @param string $domain
+     * @param string $tag
+     * @param string $description
+     *
+     * @return UpdateResponse|ResponseInterface
+     */
+    public function update($domain, $tag, $description)
+    {
+        Assert::stringNotEmpty($domain);
+        Assert::stringNotEmpty($tag);
+        Assert::string($description);
+
+        $params = [
+            'description' => $description,
+        ];
+
+        $response = $this->httpPut(sprintf('/v3/%s/tags/%s', $domain, $tag), $params);
+
+        return $this->safeDeserialize($response, UpdateResponse::class);
+    }
+
+    /**
+     * Returns statistics for a single tag.
+     *
+     * @param string $domain Name of the domain
+     * @param string $tag
+     * @param array  $params
+     *
+     * @return StatisticsResponse|ResponseInterface
+     */
+    public function stats($domain, $tag, array $params)
+    {
+        Assert::stringNotEmpty($domain);
+        Assert::stringNotEmpty($tag);
+        Assert::isArray($params);
+
+        $response = $this->httpGet(sprintf('/v3/%s/tags/%s/stats', $domain, $tag), $params);
+
+        return $this->safeDeserialize($response, StatisticsResponse::class);
+    }
+
+    /**
+     * Removes a tag from the account.
+     *
+     * @param string $domain Name of the domain
+     * @param string $tag
+     *
+     * @return DeleteResponse|ResponseInterface
+     */
+    public function delete($domain, $tag)
+    {
+        Assert::stringNotEmpty($domain);
+        Assert::stringNotEmpty($tag);
+
+        $response = $this->httpDelete(sprintf('/v3/%s/tags/%s', $domain, $tag));
+
+        return $this->safeDeserialize($response, DeleteResponse::class);
+    }
+}

src/Mailgun/Mailgun.php

@@ -269,6 +269,14 @@ class Mailgun
         return new Api\Domain($this->httpClient, $this->requestBuilder, $this->deserializer);
     }
 
+    /**
+     * @return Api\Tag
+     */
+    public function tag()
+    {
+        return new Api\Tag($this->httpClient, $this->requestBuilder, $this->deserializer);
+    }
+
     /**
      * @return Api\Event
      */

src/Mailgun/Resource/Api/Tag/DeleteResponse.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\Resource\Api\Tag;
+
+use Mailgun\Resource\ApiResponse;
+
+/**
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+final class DeleteResponse implements ApiResponse
+{
+    /**
+     * @var string
+     */
+    private $message;
+
+    /**
+     * @param string $message
+     */
+    private function __construct($message)
+    {
+        $this->message = $message;
+    }
+
+    /**
+     * @param array $data
+     *
+     * @return DeleteResponse
+     */
+    public static function create(array $data)
+    {
+        return new self($data['message']);
+    }
+
+    /**
+     * @return string
+     */
+    public function getMessage()
+    {
+        return $this->message;
+    }
+}

src/Mailgun/Resource/Api/Tag/IndexResponse.php

@@ -0,0 +1,60 @@
+<?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\Tag;
+
+use Mailgun\Resource\Api\PaginationResponse;
+use Mailgun\Resource\Api\PagingProvider;
+use Mailgun\Resource\ApiResponse;
+
+/**
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+final class IndexResponse implements ApiResponse, PagingProvider
+{
+    use PaginationResponse;
+
+    /**
+     * @var Tag[]
+     */
+    private $items;
+
+    /**
+     * @param Tag[] $items
+     * @param array $paging
+     */
+    public function __construct(array $items, array $paging)
+    {
+        $this->items = $items;
+        $this->paging = $paging;
+    }
+
+    /**
+     * @param array $data
+     *
+     * @return IndexResponse
+     */
+    public static function create(array $data)
+    {
+        $items = [];
+        foreach ($data['items'] as $item) {
+            $items[] = Tag::create($item);
+        }
+
+        return new self($items, $data['paging']);
+    }
+
+    /**
+     * @return Tag[]
+     */
+    public function getItems()
+    {
+        return $this->items;
+    }
+}

src/Mailgun/Resource/Api/Tag/ShowResponse.php

@@ -0,0 +1,19 @@
+<?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\Tag;
+
+use Mailgun\Resource\ApiResponse;
+
+/**
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+final class ShowResponse extends Tag implements ApiResponse
+{
+}

src/Mailgun/Resource/Api/Tag/StatisticsResponse.php

@@ -0,0 +1,131 @@
+<?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\Tag;
+
+use Mailgun\Resource\ApiResponse;
+
+/**
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+final class StatisticsResponse implements ApiResponse
+{
+    /**
+     * @var string
+     */
+    private $tag;
+
+    /**
+     * @var string
+     */
+    private $description;
+
+    /**
+     * @var string
+     */
+    private $resolution;
+
+    /**
+     * @var \DateTime
+     */
+    private $start;
+
+    /**
+     * @var \DateTime
+     */
+    private $end;
+
+    /**
+     * @var array
+     */
+    private $stats;
+
+    /**
+     * @param string    $tag
+     * @param string    $description
+     * @param \DateTime $start
+     * @param \DateTime $end
+     * @param string    $resolution
+     * @param array     $stats
+     */
+    private function __construct($tag, $description, \DateTime $start, \DateTime $end, $resolution, array $stats)
+    {
+        $this->tag = $tag;
+        $this->description = $description;
+        $this->resolution = $resolution;
+        $this->start = $start;
+        $this->end = $end;
+        $this->stats = $stats;
+    }
+
+    /**
+     * @param array $data
+     *
+     * @return StatisticsResponse
+     */
+    public static function create(array $data)
+    {
+        return new self(
+            $data['tag'],
+            $data['description'],
+            new \DateTime($data['start']),
+            new \DateTime($data['end']),
+            $data['resolution'],
+            $data['stats']
+        );
+    }
+
+    /**
+     * @return string
+     */
+    public function getTag()
+    {
+        return $this->tag;
+    }
+
+    /**
+     * @return string
+     */
+    public function getDescription()
+    {
+        return $this->description;
+    }
+
+    /**
+     * @return string
+     */
+    public function getResolution()
+    {
+        return $this->resolution;
+    }
+
+    /**
+     * @return \DateTime
+     */
+    public function getStart()
+    {
+        return $this->start;
+    }
+
+    /**
+     * @return \DateTime
+     */
+    public function getEnd()
+    {
+        return $this->end;
+    }
+
+    /**
+     * @return array
+     */
+    public function getStats()
+    {
+        return $this->stats;
+    }
+}

src/Mailgun/Resource/Api/Tag/Tag.php

@@ -0,0 +1,73 @@
+<?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\Tag;
+
+class Tag
+{
+    /**
+     * @var string
+     */
+    private $tag;
+
+    /**
+     * @var string
+     */
+    private $description;
+
+    /**
+     * @var \DateTime
+     */
+    private $firstSeen;
+
+    /**
+     * @var \DateTime
+     */
+    private $lastSeen;
+
+    /**
+     * @param string    $tag
+     * @param string    $description
+     * @param \DateTime $firstSeen
+     * @param \DateTime $lastSeen
+     */
+    public function __construct($tag, $description, \DateTime $firstSeen, \DateTime $lastSeen)
+    {
+        $this->tag = $tag;
+        $this->description = $description;
+        $this->firstSeen = $firstSeen;
+        $this->lastSeen = $lastSeen;
+    }
+
+    /**
+     * @param array $data
+     *
+     * @return Tag
+     */
+    public static function create(array $data)
+    {
+        return new self($data['tag'], $data['description'], $data['first-seen'], $data['last-seen']);
+    }
+
+    /**
+     * @return string
+     */
+    public function getTag()
+    {
+        return $this->tag;
+    }
+
+    /**
+     * @return string
+     */
+    public function getDescription()
+    {
+        return $this->description;
+    }
+}

src/Mailgun/Resource/Api/Tag/UpdateResponse.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\Resource\Api\Tag;
+
+use Mailgun\Resource\ApiResponse;
+
+/**
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+final class UpdateResponse implements ApiResponse
+{
+    /**
+     * @var string
+     */
+    private $message;
+
+    /**
+     * @param string $message
+     */
+    private function __construct($message)
+    {
+        $this->message = $message;
+    }
+
+    /**
+     * @param array $data
+     *
+     * @return UpdateResponse
+     */
+    public static function create(array $data)
+    {
+        return new self($data['message']);
+    }
+
+    /**
+     * @return string
+     */
+    public function getMessage()
+    {
+        return $this->message;
+    }
+}

tests/Api/TagTest.php

@@ -0,0 +1,88 @@
+<?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;
+
+use GuzzleHttp\Psr7\Response;
+use Mailgun\Api\Tag;
+use Mailgun\Mailgun;
+
+/**
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+class TagTest extends TestCase
+{
+    protected function getApiClass()
+    {
+        return Tag::class;
+    }
+
+    public function testIndex()
+    {
+        $data = [
+            'limit' => 10,
+        ];
+
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('httpGet')
+            ->with('/v3/domain/tags', $data)
+            ->willReturn(new Response());
+
+        $api->index('domain', 10);
+    }
+
+    public function testShow()
+    {
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('httpGet')
+            ->with('/v3/domain/tags/foo')
+            ->willReturn(new Response());
+
+        $api->show('domain', 'foo');
+    }
+
+    public function testUpdate()
+    {
+        $data = [
+            'description' => 'desc',
+        ];
+
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('httpPut')
+            ->with('/v3/domain/tags/foo', $data)
+            ->willReturn(new Response());
+
+        $api->update('domain', 'foo', 'desc');
+    }
+
+    public function testStats()
+    {
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('httpGet')
+            ->with('/v3/domain/tags/foo/stats', ['event' => 'foo'])
+            ->willReturn(new Response());
+
+        $api->stats('domain', 'foo', ['event' => 'foo']);
+    }
+
+    public function testDelete()
+    {
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('httpDelete')
+            ->with('/v3/domain/tags/foo')
+            ->willReturn(new Response());
+
+        $api->delete('domain', 'foo');
+    }
+}

tests/Api/TestCase.php

@@ -63,7 +63,7 @@ abstract class TestCase extends \PHPUnit_Framework_TestCase
             ->getMock();
 
         return $this->getMockBuilder($this->getApiClass())
-            ->setMethods(['httpGet', 'httpPost', 'httpPostRaw', 'httpDelete', 'httPut'])
+            ->setMethods(['httpGet', 'httpPost', 'httpPostRaw', 'httpDelete', 'httpPut'])
             ->setConstructorArgs([$httpClient, $requestClient, $deserializer])
             ->getMock();
     }