10 files changed, 227 insertions, 18 deletions

diff --git a/application/api/ApiMiddleware.php b/application/api/ApiMiddleware.php
index ff209393..66eac133 100644
--- a/application/api/ApiMiddleware.php
+++ b/application/api/ApiMiddleware.php
@@ -65,7 +65,7 @@ class ApiMiddleware
         try {
             $this->checkRequest($request);
             $response = $next($request, $response);
-        } catch(ApiException $e) {
+        } catch (ApiException $e) {
             $e->setResponse($response);
             $e->setDebug($this->conf->get('dev.debug', false));
             $response = $e->getApiResponse();
@@ -98,7 +98,8 @@ class ApiMiddleware
      *
      * @throws ApiAuthorizationException The token couldn't be validated.
      */
-    protected function checkToken($request) {
+    protected function checkToken($request)
+    {
         if (! $request->hasHeader('Authorization')) {
             throw new ApiAuthorizationException('JWT token not provided');
         }
diff --git a/application/api/ApiUtils.php b/application/api/ApiUtils.php
index f154bb52..fc5ecaf1 100644
--- a/application/api/ApiUtils.php
+++ b/application/api/ApiUtils.php
@@ -134,4 +134,20 @@ class ApiUtils
 
         return $oldLink;
     }
+
+    /**
+     * Format a Tag for the REST API.
+     *
+     * @param string $tag         Tag name
+     * @param int    $occurrences Number of links using this tag
+     *
+     * @return array Link data formatted for the REST API.
+     */
+    public static function formatTag($tag, $occurences)
+    {
+        return [
+            'name'       => $tag,
+            'occurrences' => $occurences,
+        ];
+    }
 }
diff --git a/application/api/controllers/ApiController.php b/application/api/controllers/ApiController.php
index 3be85b98..9edefcf6 100644
--- a/application/api/controllers/ApiController.php
+++ b/application/api/controllers/ApiController.php
@@ -41,7 +41,7 @@ abstract class ApiController
 
     /**
      * ApiController constructor.
-     * 
+     *
      * Note: enabling debug mode displays JSON with readable formatting.
      *
      * @param Container $ci Slim container.
diff --git a/application/api/controllers/History.php b/application/api/controllers/History.php
index 2ff9deaf..4582e8b2 100644
--- a/application/api/controllers/History.php
+++ b/application/api/controllers/History.php
@@ -35,8 +35,7 @@ class History extends ApiController
         $offset = $request->getParam('offset');
         if (empty($offset)) {
             $offset = 0;
-        }
-        else if (ctype_digit($offset)) {
+        } elseif (ctype_digit($offset)) {
             $offset = (int) $offset;
         } else {
             throw new ApiBadParametersException('Invalid offset');
@@ -46,7 +45,7 @@ class History extends ApiController
         $limit = $request->getParam('limit');
         if (empty($limit)) {
             $limit = count($history);
-        } else if (ctype_digit($limit)) {
+        } elseif (ctype_digit($limit)) {
             $limit = (int) $limit;
         } else {
             throw new ApiBadParametersException('Invalid limit');
diff --git a/application/api/controllers/Info.php b/application/api/controllers/Info.php
index 25433f72..f37dcae5 100644
--- a/application/api/controllers/Info.php
+++ b/application/api/controllers/Info.php
@@ -7,7 +7,7 @@ use Slim\Http\Response;
 
 /**
  * Class Info
- * 
+ *
  * REST API Controller: /info
  *
  * @package Api\Controllers
@@ -17,7 +17,7 @@ class Info extends ApiController
 {
     /**
      * Service providing various information about Shaarli instance.
-     * 
+     *
      * @param Request  $request  Slim request.
      * @param Response $response Slim response.
      *
diff --git a/application/api/controllers/Links.php b/application/api/controllers/Links.php
index eb78dd26..ffcfd4c7 100644
--- a/application/api/controllers/Links.php
+++ b/application/api/controllers/Links.php
@@ -59,25 +59,25 @@ class Links extends ApiController
         $limit = $request->getParam('limit');
         if (empty($limit)) {
             $limit = self::$DEFAULT_LIMIT;
-        } else if (ctype_digit($limit)) {
+        } elseif (ctype_digit($limit)) {
             $limit = intval($limit);
-        } else if ($limit === 'all') {
+        } elseif ($limit === 'all') {
             $limit = count($links);
         } else {
             throw new ApiBadParametersException('Invalid limit');
         }
 
         // 'environment' is set by Slim and encapsulate $_SERVER.
-        $index = index_url($this->ci['environment']);
+        $indexUrl = index_url($this->ci['environment']);
 
         $out = [];
-        $cpt = 0;
+        $index = 0;
         foreach ($links as $link) {
             if (count($out) >= $limit) {
                 break;
             }
-            if ($cpt++ >= $offset) {
-                $out[] = ApiUtils::formatLink($link, $index);
+            if ($index++ >= $offset) {
+                $out[] = ApiUtils::formatLink($link, $indexUrl);
             }
         }
 
diff --git a/application/api/controllers/Tags.php b/application/api/controllers/Tags.php
new file mode 100644
index 00000000..6dd78750
--- /dev/null
+++ b/application/api/controllers/Tags.php
@@ -0,0 +1,161 @@
+<?php
+
+namespace Shaarli\Api\Controllers;
+
+use Shaarli\Api\ApiUtils;
+use Shaarli\Api\Exceptions\ApiBadParametersException;
+use Shaarli\Api\Exceptions\ApiLinkNotFoundException;
+use Shaarli\Api\Exceptions\ApiTagNotFoundException;
+use Slim\Http\Request;
+use Slim\Http\Response;
+
+/**
+ * Class Tags
+ *
+ * REST API Controller: all services related to tags collection.
+ *
+ * @package Api\Controllers
+ */
+class Tags extends ApiController
+{
+    /**
+     * @var int Number of links returned if no limit is provided.
+     */
+    public static $DEFAULT_LIMIT = 'all';
+
+    /**
+     * Retrieve a list of tags, allowing different filters.
+     *
+     * @param Request  $request  Slim request.
+     * @param Response $response Slim response.
+     *
+     * @return Response response.
+     *
+     * @throws ApiBadParametersException Invalid parameters.
+     */
+    public function getTags($request, $response)
+    {
+        $visibility = $request->getParam('visibility');
+        $tags = $this->linkDb->linksCountPerTag([], $visibility);
+
+        // Return tags from the {offset}th tag, starting from 0.
+        $offset = $request->getParam('offset');
+        if (! empty($offset) && ! ctype_digit($offset)) {
+            throw new ApiBadParametersException('Invalid offset');
+        }
+        $offset = ! empty($offset) ? intval($offset) : 0;
+        if ($offset > count($tags)) {
+            return $response->withJson([], 200, $this->jsonStyle);
+        }
+
+        // limit parameter is either a number of links or 'all' for everything.
+        $limit = $request->getParam('limit');
+        if (empty($limit)) {
+            $limit = self::$DEFAULT_LIMIT;
+        }
+        if (ctype_digit($limit)) {
+            $limit = intval($limit);
+        } elseif ($limit === 'all') {
+            $limit = count($tags);
+        } else {
+            throw new ApiBadParametersException('Invalid limit');
+        }
+
+        $out = [];
+        $index = 0;
+        foreach ($tags as $tag => $occurrences) {
+            if (count($out) >= $limit) {
+                break;
+            }
+            if ($index++ >= $offset) {
+                $out[] = ApiUtils::formatTag($tag, $occurrences);
+            }
+        }
+
+        return $response->withJson($out, 200, $this->jsonStyle);
+    }
+
+    /**
+     * Return a single formatted tag by its name.
+     *
+     * @param Request  $request  Slim request.
+     * @param Response $response Slim response.
+     * @param array    $args     Path parameters. including the tag name.
+     *
+     * @return Response containing the link array.
+     *
+     * @throws ApiTagNotFoundException generating a 404 error.
+     */
+    public function getTag($request, $response, $args)
+    {
+        $tags = $this->linkDb->linksCountPerTag();
+        if (!isset($tags[$args['tagName']])) {
+            throw new ApiTagNotFoundException();
+        }
+        $out = ApiUtils::formatTag($args['tagName'], $tags[$args['tagName']]);
+
+        return $response->withJson($out, 200, $this->jsonStyle);
+    }
+
+    /**
+     * Rename a tag from the given name.
+     * If the new name provided matches an existing tag, they will be merged.
+     *
+     * @param Request  $request  Slim request.
+     * @param Response $response Slim response.
+     * @param array    $args     Path parameters. including the tag name.
+     *
+     * @return Response response.
+     *
+     * @throws ApiTagNotFoundException generating a 404 error.
+     * @throws ApiBadParametersException new tag name not provided
+     */
+    public function putTag($request, $response, $args)
+    {
+        $tags = $this->linkDb->linksCountPerTag();
+        if (! isset($tags[$args['tagName']])) {
+            throw new ApiTagNotFoundException();
+        }
+
+        $data = $request->getParsedBody();
+        if (empty($data['name'])) {
+            throw new ApiBadParametersException('New tag name is required in the request body');
+        }
+
+        $updated = $this->linkDb->renameTag($args['tagName'], $data['name']);
+        $this->linkDb->save($this->conf->get('resource.page_cache'));
+        foreach ($updated as $link) {
+            $this->history->updateLink($link);
+        }
+
+        $tags = $this->linkDb->linksCountPerTag();
+        $out = ApiUtils::formatTag($data['name'], $tags[$data['name']]);
+        return $response->withJson($out, 200, $this->jsonStyle);
+    }
+
+    /**
+     * Delete an existing tag by its name.
+     *
+     * @param Request  $request  Slim request.
+     * @param Response $response Slim response.
+     * @param array    $args     Path parameters. including the tag name.
+     *
+     * @return Response response.
+     *
+     * @throws ApiTagNotFoundException generating a 404 error.
+     */
+    public function deleteTag($request, $response, $args)
+    {
+        $tags = $this->linkDb->linksCountPerTag();
+        if (! isset($tags[$args['tagName']])) {
+            throw new ApiTagNotFoundException();
+        }
+        $updated = $this->linkDb->renameTag($args['tagName'], null);
+        $this->linkDb->save($this->conf->get('resource.page_cache'));
+        foreach ($updated as $link) {
+            $this->history->updateLink($link);
+        }
+
+        return $response->withStatus(204);
+    }
+}
diff --git a/application/api/exceptions/ApiException.php b/application/api/exceptions/ApiException.php
index c8490e0c..d6b66323 100644
--- a/application/api/exceptions/ApiException.php
+++ b/application/api/exceptions/ApiException.php
@@ -10,7 +10,8 @@ use Slim\Http\Response;
  * Parent Exception related to the API, able to generate a valid Response (ResponseInterface).
  * Also can include various information in debug mode.
  */
-abstract class ApiException extends \Exception {
+abstract class ApiException extends \Exception
+{
 
     /**
      * @var Response instance from Slim.
@@ -27,7 +28,7 @@ abstract class ApiException extends \Exception {
      *
      * @return Response Final response to give.
      */
-    public abstract function getApiResponse();
+    abstract public function getApiResponse();
 
     /**
      * Creates ApiResponse body.
@@ -36,7 +37,8 @@ abstract class ApiException extends \Exception {
      *
      * @return array|string response body
      */
-    protected function getApiResponseBody() {
+    protected function getApiResponseBody()
+    {
         if ($this->debug !== true) {
             return $this->getMessage();
         }
diff --git a/application/api/exceptions/ApiLinkNotFoundException.php b/application/api/exceptions/ApiLinkNotFoundException.php
index de7e14f5..c727f4f0 100644
--- a/application/api/exceptions/ApiLinkNotFoundException.php
+++ b/application/api/exceptions/ApiLinkNotFoundException.php
@@ -2,7 +2,6 @@
 
 namespace Shaarli\Api\Exceptions;
 
-
 use Slim\Http\Response;
 
 /**
diff --git a/application/api/exceptions/ApiTagNotFoundException.php b/application/api/exceptions/ApiTagNotFoundException.php
new file mode 100644
index 00000000..eee152fe
--- /dev/null
+++ b/application/api/exceptions/ApiTagNotFoundException.php
@@ -0,0 +1,31 @@
+<?php
+
+namespace Shaarli\Api\Exceptions;
+
+use Slim\Http\Response;
+
+/**
+ * Class ApiTagNotFoundException
+ *
+ * Tag selected by name couldn't be found in the datastore, results in a 404 error.
+ *
+ * @package Shaarli\Api\Exceptions
+ */
+class ApiTagNotFoundException extends ApiException
+{
+    /**
+     * ApiLinkNotFoundException constructor.
+     */
+    public function __construct()
+    {
+        $this->message = 'Tag not found';
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getApiResponse()
+    {
+        return $this->buildApiResponse(404);
+    }
+}