5 files changed, 172 insertions, 12 deletions

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);
+    }
+}