3 namespace Shaarli\Api\Controllers
;
5 use Shaarli\Api\ApiUtils
;
6 use Shaarli\Api\Exceptions\ApiBadParametersException
;
7 use Shaarli\Api\Exceptions\ApiTagNotFoundException
;
8 use Shaarli\Bookmark\BookmarkFilter
;
10 use Slim\Http\Response
;
15 * REST API Controller: all services related to tags collection.
17 * @package Api\Controllers
19 class Tags
extends ApiController
22 * @var int Number of bookmarks returned if no limit is provided.
24 public static $DEFAULT_LIMIT = 'all';
27 * Retrieve a list of tags, allowing different filters.
29 * @param Request $request Slim request.
30 * @param Response $response Slim response.
32 * @return Response response.
34 * @throws ApiBadParametersException Invalid parameters.
36 public function getTags($request, $response)
38 $visibility = $request->getParam('visibility');
39 $tags = $this->bookmarkService
->bookmarksCountPerTag([], $visibility);
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');
46 $offset = ! empty($offset) ? intval($offset) : 0;
47 if ($offset > count($tags)) {
48 return $response->withJson([], 200, $this->jsonStyle
);
51 // limit parameter is either a number of bookmarks or 'all' for everything.
52 $limit = $request->getParam('limit');
54 $limit = self
::$DEFAULT_LIMIT;
56 if (ctype_digit($limit)) {
57 $limit = intval($limit);
58 } elseif ($limit === 'all') {
59 $limit = count($tags);
61 throw new ApiBadParametersException('Invalid limit');
66 foreach ($tags as $tag => $occurrences) {
67 if (count($out) >= $limit) {
70 if ($index++
>= $offset) {
71 $out[] = ApiUtils
::formatTag($tag, $occurrences);
75 return $response->withJson($out, 200, $this->jsonStyle
);
79 * Return a single formatted tag by its name.
81 * @param Request $request Slim request.
82 * @param Response $response Slim response.
83 * @param array $args Path parameters. including the tag name.
85 * @return Response containing the link array.
87 * @throws ApiTagNotFoundException generating a 404 error.
89 public function getTag($request, $response, $args)
91 $tags = $this->bookmarkService
->bookmarksCountPerTag();
92 if (!isset($tags[$args['tagName']])) {
93 throw new ApiTagNotFoundException();
95 $out = ApiUtils
::formatTag($args['tagName'], $tags[$args['tagName']]);
97 return $response->withJson($out, 200, $this->jsonStyle
);
101 * Rename a tag from the given name.
102 * If the new name provided matches an existing tag, they will be merged.
104 * @param Request $request Slim request.
105 * @param Response $response Slim response.
106 * @param array $args Path parameters. including the tag name.
108 * @return Response response.
110 * @throws ApiTagNotFoundException generating a 404 error.
111 * @throws ApiBadParametersException new tag name not provided
113 public function putTag($request, $response, $args)
115 $tags = $this->bookmarkService
->bookmarksCountPerTag();
116 if (! isset($tags[$args['tagName']])) {
117 throw new ApiTagNotFoundException();
120 $data = $request->getParsedBody();
121 if (empty($data['name'])) {
122 throw new ApiBadParametersException('New tag name is required in the request body');
125 $bookmarks = $this->bookmarkService
->search(
126 ['searchtags' => $args['tagName']],
127 BookmarkFilter
::$ALL,
130 foreach ($bookmarks as $bookmark) {
131 $bookmark->renameTag($args['tagName'], $data['name']);
132 $this->bookmarkService
->set($bookmark, false);
133 $this->history
->updateLink($bookmark);
135 $this->bookmarkService
->save();
137 $tags = $this->bookmarkService
->bookmarksCountPerTag();
138 $out = ApiUtils
::formatTag($data['name'], $tags[$data['name']]);
139 return $response->withJson($out, 200, $this->jsonStyle
);
143 * Delete an existing tag by its name.
145 * @param Request $request Slim request.
146 * @param Response $response Slim response.
147 * @param array $args Path parameters. including the tag name.
149 * @return Response response.
151 * @throws ApiTagNotFoundException generating a 404 error.
153 public function deleteTag($request, $response, $args)
155 $tags = $this->bookmarkService
->bookmarksCountPerTag();
156 if (! isset($tags[$args['tagName']])) {
157 throw new ApiTagNotFoundException();
160 $bookmarks = $this->bookmarkService
->search(
161 ['searchtags' => $args['tagName']],
162 BookmarkFilter
::$ALL,
165 foreach ($bookmarks as $bookmark) {
166 $bookmark->deleteTag($args['tagName']);
167 $this->bookmarkService
->set($bookmark, false);
168 $this->history
->updateLink($bookmark);
170 $this->bookmarkService
->save();
172 return $response->withStatus(204);