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         if (!$this->bookmarkService->exists($args['id'])) {
 100             throw new ApiLinkNotFoundException();
 101         }
 102         $index = index_url($this->ci['environment']);
 103         $out = ApiUtils::formatLink($this->bookmarkService->get($args['id']), $index);
 104
 105         return $response->withJson($out, 200, $this->jsonStyle);
 106     }
 107
 108     /**
 109      * Creates a new link from posted request body.
 110      *
 111      * @param Request  $request  Slim request.
 112      * @param Response $response Slim response.
 113      *
 114      * @return Response response.
 115      */
 116     public function postLink($request, $response)
 117     {
 118         $data = $request->getParsedBody();
 119         $bookmark = ApiUtils::buildLinkFromRequest($data, $this->conf->get('privacy.default_private_links'));
 120         // duplicate by URL, return 409 Conflict
 121         if (! empty($bookmark->getUrl())
 122             && ! empty($dup = $this->bookmarkService->findByUrl($bookmark->getUrl()))
 123         ) {
 124             return $response->withJson(
 125                 ApiUtils::formatLink($dup, index_url($this->ci['environment'])),
 126                 409,
 127                 $this->jsonStyle
 128             );
 129         }
 130
 131         $this->bookmarkService->add($bookmark);
 132         $out = ApiUtils::formatLink($bookmark, index_url($this->ci['environment']));
 133         $redirect = $this->ci->router->relativePathFor('getLink', ['id' => $bookmark->getId()]);
 134         return $response->withAddedHeader('Location', $redirect)
 135                         ->withJson($out, 201, $this->jsonStyle);
 136     }
 137
 138     /**
 139      * Updates an existing link from posted request body.
 140      *
 141      * @param Request  $request  Slim request.
 142      * @param Response $response Slim response.
 143      * @param array    $args     Path parameters. including the ID.
 144      *
 145      * @return Response response.
 146      *
 147      * @throws ApiLinkNotFoundException generating a 404 error.
 148      */
 149     public function putLink($request, $response, $args)
 150     {
 151         if (! $this->bookmarkService->exists($args['id'])) {
 152             throw new ApiLinkNotFoundException();
 153         }
 154
 155         $index = index_url($this->ci['environment']);
 156         $data = $request->getParsedBody();
 157
 158         $requestBookmark = ApiUtils::buildLinkFromRequest($data, $this->conf->get('privacy.default_private_links'));
 159         // duplicate URL on a different link, return 409 Conflict
 160         if (! empty($requestBookmark->getUrl())
 161             && ! empty($dup = $this->bookmarkService->findByUrl($requestBookmark->getUrl()))
 162             && $dup->getId() != $args['id']
 163         ) {
 164             return $response->withJson(
 165                 ApiUtils::formatLink($dup, $index),
 166                 409,
 167                 $this->jsonStyle
 168             );
 169         }
 170
 171         $responseBookmark = $this->bookmarkService->get($args['id']);
 172         $responseBookmark = ApiUtils::updateLink($responseBookmark, $requestBookmark);
 173         $this->bookmarkService->set($responseBookmark);
 174
 175         $out = ApiUtils::formatLink($responseBookmark, $index);
 176         return $response->withJson($out, 200, $this->jsonStyle);
 177     }
 178
 179     /**
 180      * Delete an existing link by its ID.
 181      *
 182      * @param Request  $request  Slim request.
 183      * @param Response $response Slim response.
 184      * @param array    $args     Path parameters. including the ID.
 185      *
 186      * @return Response response.
 187      *
 188      * @throws ApiLinkNotFoundException generating a 404 error.
 189      */
 190     public function deleteLink($request, $response, $args)
 191     {
 192         if (! $this->bookmarkService->exists($args['id'])) {
 193             throw new ApiLinkNotFoundException();
 194         }
 195         $bookmark = $this->bookmarkService->get($args['id']);
 196         $this->bookmarkService->remove($bookmark);
 197
 198         return $response->withStatus(204);
 199     }
 200 }