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 links 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 links returned if no limit is provided.
  23      */
  24     public static $DEFAULT_LIMIT = 20;
  25
  26     /**
  27      * Retrieve a list of links, 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         $links = $this->linkDb->filterSearch(
  40             [
  41                 'searchtags' => $request->getParam('searchtags', ''),
  42                 'searchterm' => $request->getParam('searchterm', ''),
  43             ],
  44             false,
  45             $private
  46         );
  47
  48         // Return links from the {offset}th link, starting from 0.
  49         $offset = $request->getParam('offset');
  50         if (! empty($offset) && ! ctype_digit($offset)) {
  51             throw new ApiBadParametersException('Invalid offset');
  52         }
  53         $offset = ! empty($offset) ? intval($offset) : 0;
  54         if ($offset > count($links)) {
  55             return $response->withJson([], 200, $this->jsonStyle);
  56         }
  57
  58         // limit parameter is either a number of links or 'all' for everything.
  59         $limit = $request->getParam('limit');
  60         if (empty($limit)) {
  61             $limit = self::$DEFAULT_LIMIT;
  62         } else if (ctype_digit($limit)) {
  63             $limit = intval($limit);
  64         } else if ($limit === 'all') {
  65             $limit = count($links);
  66         } else {
  67             throw new ApiBadParametersException('Invalid limit');
  68         }
  69
  70         // 'environment' is set by Slim and encapsulate $_SERVER.
  71         $index = index_url($this->ci['environment']);
  72
  73         $out = [];
  74         $cpt = 0;
  75         foreach ($links as $link) {
  76             if (count($out) >= $limit) {
  77                 break;
  78             }
  79             if ($cpt++ >= $offset) {
  80                 $out[] = ApiUtils::formatLink($link, $index);
  81             }
  82         }
  83
  84         return $response->withJson($out, 200, $this->jsonStyle);
  85     }
  86
  87     /**
  88      * Return a single formatted link by its ID.
  89      *
  90      * @param Request  $request  Slim request.
  91      * @param Response $response Slim response.
  92      * @param array    $args     Path parameters. including the ID.
  93      *
  94      * @return Response containing the link array.
  95      *
  96      * @throws ApiLinkNotFoundException generating a 404 error.
  97      */
  98     public function getLink($request, $response, $args)
  99     {
 100         if (!isset($this->linkDb[$args['id']])) {
 101             throw new ApiLinkNotFoundException();
 102         }
 103         $index = index_url($this->ci['environment']);
 104         $out = ApiUtils::formatLink($this->linkDb[$args['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 = $request->getParsedBody();
 120         $link = ApiUtils::buildLinkFromRequest($data, $this->conf->get('privacy.default_private_links'));
 121         // duplicate by URL, return 409 Conflict
 122         if (! empty($link['url']) && ! empty($dup = $this->linkDb->getLinkFromUrl($link['url']))) {
 123             return $response->withJson(
 124                 ApiUtils::formatLink($dup, index_url($this->ci['environment'])),
 125                 409,
 126                 $this->jsonStyle
 127             );
 128         }
 129
 130         $link['id'] = $this->linkDb->getNextId();
 131         $link['shorturl'] = link_small_hash($link['created'], $link['id']);
 132
 133         // note: general relative URL
 134         if (empty($link['url'])) {
 135             $link['url'] = '?' . $link['shorturl'];
 136         }
 137
 138         if (empty($link['title'])) {
 139             $link['title'] = $link['url'];
 140         }
 141
 142         $this->linkDb[$link['id']] = $link;
 143         $this->linkDb->save($this->conf->get('resource.page_cache'));
 144         $out = ApiUtils::formatLink($link, index_url($this->ci['environment']));
 145         $redirect = $this->ci->router->relativePathFor('getLink', ['id' => $link['id']]);
 146         return $response->withAddedHeader('Location', $redirect)
 147                         ->withJson($out, 201, $this->jsonStyle);
 148     }
 149
 150     /**
 151      * Updates an existing link from posted request body.
 152      *
 153      * @param Request  $request  Slim request.
 154      * @param Response $response Slim response.
 155      * @param array    $args     Path parameters. including the ID.
 156      *
 157      * @return Response response.
 158      *
 159      * @throws ApiLinkNotFoundException generating a 404 error.
 160      */
 161     public function putLink($request, $response, $args)
 162     {
 163         if (! isset($this->linkDb[$args['id']])) {
 164             throw new ApiLinkNotFoundException();
 165         }
 166
 167         $index = index_url($this->ci['environment']);
 168         $data = $request->getParsedBody();
 169
 170         $requestLink = ApiUtils::buildLinkFromRequest($data, $this->conf->get('privacy.default_private_links'));
 171         // duplicate URL on a different link, return 409 Conflict
 172         if (! empty($requestLink['url'])
 173             && ! empty($dup = $this->linkDb->getLinkFromUrl($requestLink['url']))
 174             && $dup['id'] != $args['id']
 175         ) {
 176             return $response->withJson(
 177                 ApiUtils::formatLink($dup, $index),
 178                 409,
 179                 $this->jsonStyle
 180             );
 181         }
 182
 183         $responseLink = $this->linkDb[$args['id']];
 184         $responseLink = ApiUtils::updateLink($responseLink, $requestLink);
 185         $this->linkDb[$responseLink['id']] = $responseLink;
 186         $this->linkDb->save($this->conf->get('resource.page_cache'));
 187
 188         $out = ApiUtils::formatLink($responseLink, $index);
 189         return $response->withJson($out, 200, $this->jsonStyle);
 190     }
 191
 192     /**
 193      * Delete an existing link by its ID.
 194      *
 195      * @param Request  $request  Slim request.
 196      * @param Response $response Slim response.
 197      * @param array    $args     Path parameters. including the ID.
 198      *
 199      * @return Response response.
 200      *
 201      * @throws ApiLinkNotFoundException generating a 404 error.
 202      */
 203     public function deleteLink($request, $response, $args)
 204     {
 205         if (! isset($this->linkDb[$args['id']])) {
 206             throw new ApiLinkNotFoundException();
 207         }
 208
 209         unset($this->linkDb[(int) $args['id']]);
 210         $this->linkDb->save($this->conf->get('resource.page_cache'));
 211
 212         return $response->withStatus(204);
 213     }
 214 }