application/api/controllers/Tags.php

   1 <?php
   2
   3 namespace Shaarli\Api\Controllers;
   4
   5 use Shaarli\Api\ApiUtils;
   6 use Shaarli\Api\Exceptions\ApiBadParametersException;
   7 use Shaarli\Api\Exceptions\ApiLinkNotFoundException;
   8 use Shaarli\Api\Exceptions\ApiTagNotFoundException;
   9 use Slim\Http\Request;
  10 use Slim\Http\Response;
  11
  12 /**
  13  * Class Tags
  14  *
  15  * REST API Controller: all services related to tags collection.
  16  *
  17  * @package Api\Controllers
  18  */
  19 class Tags extends ApiController
  20 {
  21     /**
  22      * @var int Number of links returned if no limit is provided.
  23      */
  24     public static $DEFAULT_LIMIT = 'all';
  25
  26     /**
  27      * Retrieve a list of tags, allowing different filters.
  28      *
  29      * @param Request  $request  Slim request.
  30      * @param Response $response Slim response.
  31      *
  32      * @return Response response.
  33      *
  34      * @throws ApiBadParametersException Invalid parameters.
  35      */
  36     public function getTags($request, $response)
  37     {
  38         $visibility = $request->getParam('visibility');
  39         $tags = $this->linkDb->linksCountPerTag([], $visibility);
  40
  41         // Return tags from the {offset}th tag, starting from 0.
  42         $offset = $request->getParam('offset');
  43         if (! empty($offset) && ! ctype_digit($offset)) {
  44             throw new ApiBadParametersException('Invalid offset');
  45         }
  46         $offset = ! empty($offset) ? intval($offset) : 0;
  47         if ($offset > count($tags)) {
  48             return $response->withJson([], 200, $this->jsonStyle);
  49         }
  50
  51         // limit parameter is either a number of links or 'all' for everything.
  52         $limit = $request->getParam('limit');
  53         if (empty($limit)) {
  54             $limit = self::$DEFAULT_LIMIT;
  55         }
  56         if (ctype_digit($limit)) {
  57             $limit = intval($limit);
  58         } elseif ($limit === 'all') {
  59             $limit = count($tags);
  60         } else {
  61             throw new ApiBadParametersException('Invalid limit');
  62         }
  63
  64         $out = [];
  65         $index = 0;
  66         foreach ($tags as $tag => $occurrences) {
  67             if (count($out) >= $limit) {
  68                 break;
  69             }
  70             if ($index++ >= $offset) {
  71                 $out[] = ApiUtils::formatTag($tag, $occurrences);
  72             }
  73         }
  74
  75         return $response->withJson($out, 200, $this->jsonStyle);
  76     }
  77
  78     /**
  79      * Return a single formatted tag by its name.
  80      *
  81      * @param Request  $request  Slim request.
  82      * @param Response $response Slim response.
  83      * @param array    $args     Path parameters. including the tag name.
  84      *
  85      * @return Response containing the link array.
  86      *
  87      * @throws ApiTagNotFoundException generating a 404 error.
  88      */
  89     public function getTag($request, $response, $args)
  90     {
  91         $tags = $this->linkDb->linksCountPerTag();
  92         if (!isset($tags[$args['tagName']])) {
  93             throw new ApiTagNotFoundException();
  94         }
  95         $out = ApiUtils::formatTag($args['tagName'], $tags[$args['tagName']]);
  96
  97         return $response->withJson($out, 200, $this->jsonStyle);
  98     }
  99
 100     /**
 101      * Rename a tag from the given name.
 102      * If the new name provided matches an existing tag, they will be merged.
 103      *
 104      * @param Request  $request  Slim request.
 105      * @param Response $response Slim response.
 106      * @param array    $args     Path parameters. including the tag name.
 107      *
 108      * @return Response response.
 109      *
 110      * @throws ApiTagNotFoundException generating a 404 error.
 111      * @throws ApiBadParametersException new tag name not provided
 112      */
 113     public function putTag($request, $response, $args)
 114     {
 115         $tags = $this->linkDb->linksCountPerTag();
 116         if (! isset($tags[$args['tagName']])) {
 117             throw new ApiTagNotFoundException();
 118         }
 119
 120         $data = $request->getParsedBody();
 121         if (empty($data['name'])) {
 122             throw new ApiBadParametersException('New tag name is required in the request body');
 123         }
 124
 125         $updated = $this->linkDb->renameTag($args['tagName'], $data['name']);
 126         $this->linkDb->save($this->conf->get('resource.page_cache'));
 127         foreach ($updated as $link) {
 128             $this->history->updateLink($link);
 129         }
 130
 131         $tags = $this->linkDb->linksCountPerTag();
 132         $out = ApiUtils::formatTag($data['name'], $tags[$data['name']]);
 133         return $response->withJson($out, 200, $this->jsonStyle);
 134     }
 135
 136     /**
 137      * Delete an existing tag by its name.
 138      *
 139      * @param Request  $request  Slim request.
 140      * @param Response $response Slim response.
 141      * @param array    $args     Path parameters. including the tag name.
 142      *
 143      * @return Response response.
 144      *
 145      * @throws ApiTagNotFoundException generating a 404 error.
 146      */
 147     public function deleteTag($request, $response, $args)
 148     {
 149         $tags = $this->linkDb->linksCountPerTag();
 150         if (! isset($tags[$args['tagName']])) {
 151             throw new ApiTagNotFoundException();
 152         }
 153         $updated = $this->linkDb->renameTag($args['tagName'], null);
 154         $this->linkDb->save($this->conf->get('resource.page_cache'));
 155         foreach ($updated as $link) {
 156             $this->history->updateLink($link);
 157         }
 158
 159         return $response->withStatus(204);
 160     }
 161 }