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