3 namespace Shaarli\Api\Controllers
;
5 use Shaarli\Api\ApiUtils
;
6 use Shaarli\Api\Exceptions\ApiBadParametersException
;
7 use Shaarli\Api\Exceptions\ApiTagNotFoundException
;
9 use Slim\Http\Response
;
14 * REST API Controller: all services related to tags collection.
16 * @package Api\Controllers
18 class Tags
extends ApiController
21 * @var int Number of links returned if no limit is provided.
23 public static $DEFAULT_LIMIT = 'all';
26 * Retrieve a list of tags, allowing different filters.
28 * @param Request $request Slim request.
29 * @param Response $response Slim response.
31 * @return Response response.
33 * @throws ApiBadParametersException Invalid parameters.
35 public function getTags($request, $response)
37 $visibility = $request->getParam('visibility');
38 $tags = $this->linkDb
->linksCountPerTag([], $visibility);
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');
45 $offset = ! empty($offset) ? intval($offset) : 0;
46 if ($offset > count($tags)) {
47 return $response->withJson([], 200, $this->jsonStyle
);
50 // limit parameter is either a number of links or 'all' for everything.
51 $limit = $request->getParam('limit');
53 $limit = self
::$DEFAULT_LIMIT;
55 if (ctype_digit($limit)) {
56 $limit = intval($limit);
57 } elseif ($limit === 'all') {
58 $limit = count($tags);
60 throw new ApiBadParametersException('Invalid limit');
65 foreach ($tags as $tag => $occurrences) {
66 if (count($out) >= $limit) {
69 if ($index++
>= $offset) {
70 $out[] = ApiUtils
::formatTag($tag, $occurrences);
74 return $response->withJson($out, 200, $this->jsonStyle
);
78 * Return a single formatted tag by its name.
80 * @param Request $request Slim request.
81 * @param Response $response Slim response.
82 * @param array $args Path parameters. including the tag name.
84 * @return Response containing the link array.
86 * @throws ApiTagNotFoundException generating a 404 error.
88 public function getTag($request, $response, $args)
90 $tags = $this->linkDb
->linksCountPerTag();
91 if (!isset($tags[$args['tagName']])) {
92 throw new ApiTagNotFoundException();
94 $out = ApiUtils
::formatTag($args['tagName'], $tags[$args['tagName']]);
96 return $response->withJson($out, 200, $this->jsonStyle
);
100 * Rename a tag from the given name.
101 * If the new name provided matches an existing tag, they will be merged.
103 * @param Request $request Slim request.
104 * @param Response $response Slim response.
105 * @param array $args Path parameters. including the tag name.
107 * @return Response response.
109 * @throws ApiTagNotFoundException generating a 404 error.
110 * @throws ApiBadParametersException new tag name not provided
112 public function putTag($request, $response, $args)
114 $tags = $this->linkDb
->linksCountPerTag();
115 if (! isset($tags[$args['tagName']])) {
116 throw new ApiTagNotFoundException();
119 $data = $request->getParsedBody();
120 if (empty($data['name'])) {
121 throw new ApiBadParametersException('New tag name is required in the request body');
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);
130 $tags = $this->linkDb
->linksCountPerTag();
131 $out = ApiUtils
::formatTag($data['name'], $tags[$data['name']]);
132 return $response->withJson($out, 200, $this->jsonStyle
);
136 * Delete an existing tag by its name.
138 * @param Request $request Slim request.
139 * @param Response $response Slim response.
140 * @param array $args Path parameters. including the tag name.
142 * @return Response response.
144 * @throws ApiTagNotFoundException generating a 404 error.
146 public function deleteTag($request, $response, $args)
148 $tags = $this->linkDb
->linksCountPerTag();
149 if (! isset($tags[$args['tagName']])) {
150 throw new ApiTagNotFoundException();
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);
158 return $response->withStatus(204);