3 namespace Shaarli\Api\Controllers
;
5 use Shaarli\Api\ApiUtils
;
6 use Shaarli\Api\Exceptions\ApiBadParametersException
;
7 use Shaarli\Api\Exceptions\ApiLinkNotFoundException
;
9 use Slim\Http\Response
;
14 * REST API Controller: all services related to bookmarks collection.
16 * @package Api\Controllers
17 * @see http://shaarli.github.io/api-documentation/#links-links-collection
19 class Links
extends ApiController
22 * @var int Number of bookmarks returned if no limit is provided.
24 public static $DEFAULT_LIMIT = 20;
27 * Retrieve a list of bookmarks, 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 getLinks($request, $response)
38 $private = $request->getParam('visibility');
39 $bookmarks = $this->bookmarkService
->search(
41 'searchtags' => $request->getParam('searchtags', ''),
42 'searchterm' => $request->getParam('searchterm', ''),
47 // Return bookmarks from the {offset}th link, starting from 0.
48 $offset = $request->getParam('offset');
49 if (! empty($offset) && ! ctype_digit($offset)) {
50 throw new ApiBadParametersException('Invalid offset');
52 $offset = ! empty($offset) ? intval($offset) : 0;
53 if ($offset > count($bookmarks)) {
54 return $response->withJson([], 200, $this->jsonStyle
);
57 // limit parameter is either a number of bookmarks or 'all' for everything.
58 $limit = $request->getParam('limit');
60 $limit = self
::$DEFAULT_LIMIT;
61 } elseif (ctype_digit($limit)) {
62 $limit = intval($limit);
63 } elseif ($limit === 'all') {
64 $limit = count($bookmarks);
66 throw new ApiBadParametersException('Invalid limit');
69 // 'environment' is set by Slim and encapsulate $_SERVER.
70 $indexUrl = index_url($this->ci
['environment']);
74 foreach ($bookmarks as $bookmark) {
75 if (count($out) >= $limit) {
78 if ($index++
>= $offset) {
79 $out[] = ApiUtils
::formatLink($bookmark, $indexUrl);
83 return $response->withJson($out, 200, $this->jsonStyle
);
87 * Return a single formatted link by its ID.
89 * @param Request $request Slim request.
90 * @param Response $response Slim response.
91 * @param array $args Path parameters. including the ID.
93 * @return Response containing the link array.
95 * @throws ApiLinkNotFoundException generating a 404 error.
97 public function getLink($request, $response, $args)
99 $id = is_integer_mixed($args['id']) ? (int) $args['id'] : null;
100 if ($id === null || ! $this->bookmarkService
->exists($id)) {
101 throw new ApiLinkNotFoundException();
103 $index = index_url($this->ci
['environment']);
104 $out = ApiUtils
::formatLink($this->bookmarkService
->get($id), $index);
106 return $response->withJson($out, 200, $this->jsonStyle
);
110 * Creates a new link from posted request body.
112 * @param Request $request Slim request.
113 * @param Response $response Slim response.
115 * @return Response response.
117 public function postLink($request, $response)
119 $data = (array) ($request->getParsedBody() ?? []);
120 $bookmark = ApiUtils
::buildBookmarkFromRequest($data, $this->conf
->get('privacy.default_private_links'));
121 // duplicate by URL, return 409 Conflict
122 if (! empty($bookmark->getUrl())
123 && ! empty($dup = $this->bookmarkService
->findByUrl($bookmark->getUrl()))
125 return $response->withJson(
126 ApiUtils
::formatLink($dup, index_url($this->ci
['environment'])),
132 $this->bookmarkService
->add($bookmark);
133 $out = ApiUtils
::formatLink($bookmark, index_url($this->ci
['environment']));
134 $redirect = $this->ci
->router
->relativePathFor('getLink', ['id' => $bookmark->getId()]);
135 return $response->withAddedHeader('Location', $redirect)
136 ->withJson($out, 201, $this->jsonStyle
);
140 * Updates an existing link from posted request body.
142 * @param Request $request Slim request.
143 * @param Response $response Slim response.
144 * @param array $args Path parameters. including the ID.
146 * @return Response response.
148 * @throws ApiLinkNotFoundException generating a 404 error.
150 public function putLink($request, $response, $args)
152 $id = is_integer_mixed($args['id']) ? (int) $args['id'] : null;
153 if ($id === null || !$this->bookmarkService
->exists($id)) {
154 throw new ApiLinkNotFoundException();
157 $index = index_url($this->ci
['environment']);
158 $data = $request->getParsedBody();
160 $requestBookmark = ApiUtils
::buildBookmarkFromRequest($data, $this->conf
->get('privacy.default_private_links'));
161 // duplicate URL on a different link, return 409 Conflict
162 if (! empty($requestBookmark->getUrl())
163 && ! empty($dup = $this->bookmarkService
->findByUrl($requestBookmark->getUrl()))
164 && $dup->getId() != $id
166 return $response->withJson(
167 ApiUtils
::formatLink($dup, $index),
173 $responseBookmark = $this->bookmarkService
->get($id);
174 $responseBookmark = ApiUtils
::updateLink($responseBookmark, $requestBookmark);
175 $this->bookmarkService
->set($responseBookmark);
177 $out = ApiUtils
::formatLink($responseBookmark, $index);
178 return $response->withJson($out, 200, $this->jsonStyle
);
182 * Delete an existing link by its ID.
184 * @param Request $request Slim request.
185 * @param Response $response Slim response.
186 * @param array $args Path parameters. including the ID.
188 * @return Response response.
190 * @throws ApiLinkNotFoundException generating a 404 error.
192 public function deleteLink($request, $response, $args)
194 $id = is_integer_mixed($args['id']) ? (int) $args['id'] : null;
195 if ($id === null || !$this->bookmarkService
->exists($id)) {
196 throw new ApiLinkNotFoundException();
198 $bookmark = $this->bookmarkService
->get($id);
199 $this->bookmarkService
->remove($bookmark);
201 return $response->withStatus(204);