application/api/controllers/Links.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 Slim\Http\Request;
   9 use Slim\Http\Response;
  10
  11 /**
  12  * Class Links
  13  *
  14  * REST API Controller: all services related to bookmarks collection.
  15  *
  16  * @package Api\Controllers
  17  * @see http://shaarli.github.io/api-documentation/#links-links-collection
  18  */
  19 class Links extends ApiController
  20 {
  21     /**
  22      * @var int Number of bookmarks returned if no limit is provided.
  23      */
  24     public static $DEFAULT_LIMIT = 20;
  25
  26     /**
  27      * Retrieve a list of bookmarks, 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 getLinks($request, $response)
  37     {
  38         $private = $request->getParam('visibility');
  39         $bookmarks = $this->bookmarkService->search(
  40             [
  41                 'searchtags' => $request->getParam('searchtags', ''),
  42                 'searchterm' => $request->getParam('searchterm', ''),
  43             ],
  44             $private
  45         );
  46
  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');
  51         }
  52         $offset = ! empty($offset) ? intval($offset) : 0;
  53         if ($offset > count($bookmarks)) {
  54             return $response->withJson([], 200, $this->jsonStyle);
  55         }
  56
  57         // limit parameter is either a number of bookmarks or 'all' for everything.
  58         $limit = $request->getParam('limit');
  59         if (empty($limit)) {
  60             $limit = self::$DEFAULT_LIMIT;
  61         } elseif (ctype_digit($limit)) {
  62             $limit = intval($limit);
  63         } elseif ($limit === 'all') {
  64             $limit = count($bookmarks);
  65         } else {
  66             throw new ApiBadParametersException('Invalid limit');
  67         }
  68
  69         // 'environment' is set by Slim and encapsulate $_SERVER.
  70         $indexUrl = index_url($this->ci['environment']);
  71
  72         $out = [];
  73         $index = 0;
  74         foreach ($bookmarks as $bookmark) {
  75             if (count($out) >= $limit) {
  76                 break;
  77             }
  78             if ($index++ >= $offset) {
  79                 $out[] = ApiUtils::formatLink($bookmark, $indexUrl);
  80             }
  81         }
  82
  83         return $response->withJson($out, 200, $this->jsonStyle);
  84     }
  85
  86     /**
  87      * Return a single formatted link by its ID.
  88      *
  89      * @param Request  $request  Slim request.
  90      * @param Response $response Slim response.
  91      * @param array    $args     Path parameters. including the ID.
  92      *
  93      * @return Response containing the link array.
  94      *
  95      * @throws ApiLinkNotFoundException generating a 404 error.
  96      */
  97     public function getLink($request, $response, $args)
  98     {
  99         $id = is_integer_mixed($args['id']) ? (int) $args['id'] : null;
 100         if ($id === null || ! $this->bookmarkService->exists($id)) {
 101             throw new ApiLinkNotFoundException();
 102         }
 103         $index = index_url($this->ci['environment']);
 104         $out = ApiUtils::formatLink($this->bookmarkService->get($id), $index);
 105
 106         return $response->withJson($out, 200, $this->jsonStyle);
 107     }
 108
 109     /**
 110      * Creates a new link from posted request body.
 111      *
 112      * @param Request  $request  Slim request.
 113      * @param Response $response Slim response.
 114      *
 115      * @return Response response.
 116      */
 117     public function postLink($request, $response)
 118     {
 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()))
 124         ) {
 125             return $response->withJson(
 126                 ApiUtils::formatLink($dup, index_url($this->ci['environment'])),
 127                 409,
 128                 $this->jsonStyle
 129             );
 130         }
 131
 132         $this->bookmarkService->add($bookmark);
 133         $out = ApiUtils::formatLink($bookmark, index_url($this->ci['environment']));
 134         $redirect = $this->ci->router->pathFor('getLink', ['id' => $bookmark->getId()]);
 135         return $response->withAddedHeader('Location', $redirect)
 136                         ->withJson($out, 201, $this->jsonStyle);
 137     }
 138
 139     /**
 140      * Updates an existing link from posted request body.
 141      *
 142      * @param Request  $request  Slim request.
 143      * @param Response $response Slim response.
 144      * @param array    $args     Path parameters. including the ID.
 145      *
 146      * @return Response response.
 147      *
 148      * @throws ApiLinkNotFoundException generating a 404 error.
 149      */
 150     public function putLink($request, $response, $args)
 151     {
 152         $id = is_integer_mixed($args['id']) ? (int) $args['id'] : null;
 153         if ($id === null || !$this->bookmarkService->exists($id)) {
 154             throw new ApiLinkNotFoundException();
 155         }
 156
 157         $index = index_url($this->ci['environment']);
 158         $data = $request->getParsedBody();
 159
 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
 165         ) {
 166             return $response->withJson(
 167                 ApiUtils::formatLink($dup, $index),
 168                 409,
 169                 $this->jsonStyle
 170             );
 171         }
 172
 173         $responseBookmark = $this->bookmarkService->get($id);
 174         $responseBookmark = ApiUtils::updateLink($responseBookmark, $requestBookmark);
 175         $this->bookmarkService->set($responseBookmark);
 176
 177         $out = ApiUtils::formatLink($responseBookmark, $index);
 178         return $response->withJson($out, 200, $this->jsonStyle);
 179     }
 180
 181     /**
 182      * Delete an existing link by its ID.
 183      *
 184      * @param Request  $request  Slim request.
 185      * @param Response $response Slim response.
 186      * @param array    $args     Path parameters. including the ID.
 187      *
 188      * @return Response response.
 189      *
 190      * @throws ApiLinkNotFoundException generating a 404 error.
 191      */
 192     public function deleteLink($request, $response, $args)
 193     {
 194         $id = is_integer_mixed($args['id']) ? (int) $args['id'] : null;
 195         if ($id === null || !$this->bookmarkService->exists($id)) {
 196             throw new ApiLinkNotFoundException();
 197         }
 198         $bookmark = $this->bookmarkService->get($id);
 199         $this->bookmarkService->remove($bookmark);
 200
 201         return $response->withStatus(204);
 202     }
 203 }