application/LinkDB.php

   1 <?php
   2 /**
   3  * Data storage for links.
   4  *
   5  * This object behaves like an associative array.
   6  *
   7  * Example:
   8  *    $myLinks = new LinkDB();
   9  *    echo $myLinks[350]['title'];
  10  *    foreach ($myLinks as $link)
  11  *       echo $link['title'].' at url '.$link['url'].'; description:'.$link['description'];
  12  *
  13  * Available keys:
  14  *  - id:       primary key, incremental integer identifier (persistent)
  15  *  - description: description of the entry
  16  *  - created:  creation date of this entry, DateTime object.
  17  *  - updated:  last modification date of this entry, DateTime object.
  18  *  - private:  Is this link private? 0=no, other value=yes
  19  *  - tags:     tags attached to this entry (separated by spaces)
  20  *  - title     Title of the link
  21  *  - url       URL of the link. Used for displayable links (no redirector, relative, etc.).
  22  *              Can be absolute or relative.
  23  *              Relative URLs are permalinks (e.g.'?m-ukcw')
  24  *  - real_url  Absolute processed URL.
  25  *
  26  * Implements 3 interfaces:
  27  *  - ArrayAccess: behaves like an associative array;
  28  *  - Countable:   there is a count() method;
  29  *  - Iterator:    usable in foreach () loops.
  30  *
  31  * ID mechanism:
  32  *   ArrayAccess is implemented in a way that will allow to access a link
  33  *   with the unique identifier ID directly with $link[ID].
  34  *   Note that it's not the real key of the link array attribute.
  35  *   This mechanism is in place to have persistent link IDs,
  36  *   even though the internal array is reordered by date.
  37  *   Example:
  38  *     - DB: link #1 (2010-01-01) link #2 (2016-01-01)
  39  *     - Order: #2 #1
  40  *     - Import links containing: link #3 (2013-01-01)
  41  *     - New DB: link #1 (2010-01-01) link #2 (2016-01-01) link #3 (2013-01-01)
  42  *     - Real order: #2 #3 #1
  43  */
  44 class LinkDB implements Iterator, Countable, ArrayAccess
  45 {
  46     // Links are stored as a PHP serialized string
  47     private $datastore;
  48
  49     // Link date storage format
  50     const LINK_DATE_FORMAT = 'Ymd_His';
  51
  52     // Datastore PHP prefix
  53     protected static $phpPrefix = '<?php /* ';
  54
  55     // Datastore PHP suffix
  56     protected static $phpSuffix = ' */ ?>';
  57
  58     // List of links (associative array)
  59     //  - key:   link date (e.g. "20110823_124546"),
  60     //  - value: associative array (keys: title, description...)
  61     private $links;
  62
  63     // List of all recorded URLs (key=url, value=link offset)
  64     // for fast reserve search (url-->link offset)
  65     private $urls;
  66
  67     /**
  68      * @var array List of all links IDS mapped with their array offset.
  69      *            Map: id->offset.
  70      */
  71     protected $ids;
  72
  73     // List of offset keys (for the Iterator interface implementation)
  74     private $keys;
  75
  76     // Position in the $this->keys array (for the Iterator interface)
  77     private $position;
  78
  79     // Is the user logged in? (used to filter private links)
  80     private $loggedIn;
  81
  82     // Hide public links
  83     private $hidePublicLinks;
  84
  85     // link redirector set in user settings.
  86     private $redirector;
  87
  88     /**
  89      * Set this to `true` to urlencode link behind redirector link, `false` to leave it untouched.
  90      *
  91      * Example:
  92      *   anonym.to needs clean URL while dereferer.org needs urlencoded URL.
  93      *
  94      * @var boolean $redirectorEncode parameter: true or false
  95      */
  96     private $redirectorEncode;
  97
  98     /**
  99      * Creates a new LinkDB
 100      *
 101      * Checks if the datastore exists; else, attempts to create a dummy one.
 102      *
 103      * @param string  $datastore        datastore file path.
 104      * @param boolean $isLoggedIn       is the user logged in?
 105      * @param boolean $hidePublicLinks  if true all links are private.
 106      * @param string  $redirector       link redirector set in user settings.
 107      * @param boolean $redirectorEncode Enable urlencode on redirected urls (default: true).
 108      */
 109     public function __construct(
 110         $datastore,
 111         $isLoggedIn,
 112         $hidePublicLinks,
 113         $redirector = '',
 114         $redirectorEncode = true
 115     )
 116     {
 117         $this->datastore = $datastore;
 118         $this->loggedIn = $isLoggedIn;
 119         $this->hidePublicLinks = $hidePublicLinks;
 120         $this->redirector = $redirector;
 121         $this->redirectorEncode = $redirectorEncode === true;
 122         $this->check();
 123         $this->read();
 124     }
 125
 126     /**
 127      * Countable - Counts elements of an object
 128      */
 129     public function count()
 130     {
 131         return count($this->links);
 132     }
 133
 134     /**
 135      * ArrayAccess - Assigns a value to the specified offset
 136      */
 137     public function offsetSet($offset, $value)
 138     {
 139         // TODO: use exceptions instead of "die"
 140         if (!$this->loggedIn) {
 141             die('You are not authorized to add a link.');
 142         }
 143         if (!isset($value['id']) || empty($value['url'])) {
 144             die('Internal Error: A link should always have an id and URL.');
 145         }
 146         if ((! empty($offset) && ! is_int($offset)) || ! is_int($value['id'])) {
 147             die('You must specify an integer as a key.');
 148         }
 149         if (! empty($offset) && $offset !== $value['id']) {
 150             die('Array offset and link ID must be equal.');
 151         }
 152
 153         // If the link exists, we reuse the real offset, otherwise new entry
 154         $existing = $this->getLinkOffset($offset);
 155         if ($existing !== null) {
 156             $offset = $existing;
 157         } else {
 158             $offset = count($this->links);
 159         }
 160         $this->links[$offset] = $value;
 161         $this->urls[$value['url']] = $offset;
 162         $this->ids[$value['id']] = $offset;
 163     }
 164
 165     /**
 166      * ArrayAccess - Whether or not an offset exists
 167      */
 168     public function offsetExists($offset)
 169     {
 170         return array_key_exists($this->getLinkOffset($offset), $this->links);
 171     }
 172
 173     /**
 174      * ArrayAccess - Unsets an offset
 175      */
 176     public function offsetUnset($offset)
 177     {
 178         if (!$this->loggedIn) {
 179             // TODO: raise an exception
 180             die('You are not authorized to delete a link.');
 181         }
 182         $realOffset = $this->getLinkOffset($offset);
 183         $url = $this->links[$realOffset]['url'];
 184         unset($this->urls[$url]);
 185         unset($this->ids[$realOffset]);
 186         unset($this->links[$realOffset]);
 187     }
 188
 189     /**
 190      * ArrayAccess - Returns the value at specified offset
 191      */
 192     public function offsetGet($offset)
 193     {
 194         $realOffset = $this->getLinkOffset($offset);
 195         return isset($this->links[$realOffset]) ? $this->links[$realOffset] : null;
 196     }
 197
 198     /**
 199      * Iterator - Returns the current element
 200      */
 201     public function current()
 202     {
 203         return $this[$this->keys[$this->position]];
 204     }
 205
 206     /**
 207      * Iterator - Returns the key of the current element
 208      */
 209     public function key()
 210     {
 211         return $this->keys[$this->position];
 212     }
 213
 214     /**
 215      * Iterator - Moves forward to next element
 216      */
 217     public function next()
 218     {
 219         ++$this->position;
 220     }
 221
 222     /**
 223      * Iterator - Rewinds the Iterator to the first element
 224      *
 225      * Entries are sorted by date (latest first)
 226      */
 227     public function rewind()
 228     {
 229         $this->keys = array_keys($this->ids);
 230         $this->position = 0;
 231     }
 232
 233     /**
 234      * Iterator - Checks if current position is valid
 235      */
 236     public function valid()
 237     {
 238         return isset($this->keys[$this->position]);
 239     }
 240
 241     /**
 242      * Checks if the DB directory and file exist
 243      *
 244      * If no DB file is found, creates a dummy DB.
 245      */
 246     private function check()
 247     {
 248         if (file_exists($this->datastore)) {
 249             return;
 250         }
 251
 252         // Create a dummy database for example
 253         $this->links = array();
 254         $link = array(
 255             'id' => 1,
 256             'title'=>' Shaarli: the personal, minimalist, super-fast, no-database delicious clone',
 257             'url'=>'https://github.com/shaarli/Shaarli/wiki',
 258             'description'=>'Welcome to Shaarli! This is your first public bookmark. To edit or delete me, you must first login.
 259
 260 To learn how to use Shaarli, consult the link "Help/documentation" at the bottom of this page.
 261
 262 You use the community supported version of the original Shaarli project, by Sebastien Sauvage.',
 263             'private'=>0,
 264             'created'=> new DateTime(),
 265             'tags'=>'opensource software'
 266         );
 267         $this->links[1] = $link;
 268
 269         $link = array(
 270             'id' => 0,
 271             'title'=>'My secret stuff... - Pastebin.com',
 272             'url'=>'http://sebsauvage.net/paste/?8434b27936c09649#bR7XsXhoTiLcqCpQbmOpBi3rq2zzQUC5hBI7ZT1O3x8=',
 273             'description'=>'Shhhh! I\'m a private link only YOU can see. You can delete me too.',
 274             'private'=>1,
 275             'created'=> new DateTime('1 minute ago'),
 276             'tags'=>'secretstuff'
 277         );
 278         $this->links[0] = $link;
 279
 280         // Write database to disk
 281         $this->write();
 282     }
 283
 284     /**
 285      * Reads database from disk to memory
 286      */
 287     private function read()
 288     {
 289         // Public links are hidden and user not logged in => nothing to show
 290         if ($this->hidePublicLinks && !$this->loggedIn) {
 291             $this->links = array();
 292             return;
 293         }
 294
 295         // Read data
 296         // Note that gzinflate is faster than gzuncompress.
 297         // See: http://www.php.net/manual/en/function.gzdeflate.php#96439
 298         $this->links = array();
 299
 300         if (file_exists($this->datastore)) {
 301             $this->links = unserialize(gzinflate(base64_decode(
 302                 substr(file_get_contents($this->datastore),
 303                        strlen(self::$phpPrefix), -strlen(self::$phpSuffix)))));
 304         }
 305
 306         $toremove = array();
 307         foreach ($this->links as $key => &$link) {
 308             if (! $this->loggedIn && $link['private'] != 0) {
 309                 // Transition for not upgraded databases.
 310                 $toremove[] = $key;
 311                 continue;
 312             }
 313
 314             // Sanitize data fields.
 315             sanitizeLink($link);
 316
 317             // Remove private tags if the user is not logged in.
 318             if (! $this->loggedIn) {
 319                 $link['tags'] = preg_replace('/(^|\s+)\.[^($|\s)]+\s*/', ' ', $link['tags']);
 320             }
 321
 322             // Do not use the redirector for internal links (Shaarli note URL starting with a '?').
 323             if (!empty($this->redirector) && !startsWith($link['url'], '?')) {
 324                 $link['real_url'] = $this->redirector;
 325                 if ($this->redirectorEncode) {
 326                     $link['real_url'] .= urlencode(unescape($link['url']));
 327                 } else {
 328                     $link['real_url'] .= $link['url'];
 329                 }
 330             }
 331             else {
 332                 $link['real_url'] = $link['url'];
 333             }
 334
 335             // To be able to load links before running the update, and prepare the update
 336             if (! isset($link['created'])) {
 337                 $link['id'] = $link['linkdate'];
 338                 $link['created'] = DateTime::createFromFormat('Ymd_His', $link['linkdate']);
 339                 if (! empty($link['updated'])) {
 340                     $link['updated'] = DateTime::createFromFormat('Ymd_His', $link['updated']);
 341                 }
 342             }
 343         }
 344
 345         // If user is not logged in, filter private links.
 346         foreach ($toremove as $offset) {
 347             unset($this->links[$offset]);
 348         }
 349
 350         $this->reorder();
 351     }
 352
 353     /**
 354      * Saves the database from memory to disk
 355      *
 356      * @throws IOException the datastore is not writable
 357      */
 358     private function write()
 359     {
 360         if (is_file($this->datastore) && !is_writeable($this->datastore)) {
 361             // The datastore exists but is not writeable
 362             throw new IOException($this->datastore);
 363         } else if (!is_file($this->datastore) && !is_writeable(dirname($this->datastore))) {
 364             // The datastore does not exist and its parent directory is not writeable
 365             throw new IOException(dirname($this->datastore));
 366         }
 367
 368         file_put_contents(
 369             $this->datastore,
 370             self::$phpPrefix.base64_encode(gzdeflate(serialize($this->links))).self::$phpSuffix
 371         );
 372
 373     }
 374
 375     /**
 376      * Saves the database from memory to disk
 377      *
 378      * @param string $pageCacheDir page cache directory
 379      */
 380     public function save($pageCacheDir)
 381     {
 382         if (!$this->loggedIn) {
 383             // TODO: raise an Exception instead
 384             die('You are not authorized to change the database.');
 385         }
 386
 387         $this->write();
 388
 389         invalidateCaches($pageCacheDir);
 390     }
 391
 392     /**
 393      * Returns the link for a given URL, or False if it does not exist.
 394      *
 395      * @param string $url URL to search for
 396      *
 397      * @return mixed the existing link if it exists, else 'false'
 398      */
 399     public function getLinkFromUrl($url)
 400     {
 401         if (isset($this->urls[$url])) {
 402             return $this->links[$this->urls[$url]];
 403         }
 404         return false;
 405     }
 406
 407     /**
 408      * Returns the shaare corresponding to a smallHash.
 409      *
 410      * @param string $request QUERY_STRING server parameter.
 411      *
 412      * @return array $filtered array containing permalink data.
 413      *
 414      * @throws LinkNotFoundException if the smallhash is malformed or doesn't match any link.
 415      */
 416     public function filterHash($request)
 417     {
 418         $request = substr($request, 0, 6);
 419         $linkFilter = new LinkFilter($this->links);
 420         return $linkFilter->filter(LinkFilter::$FILTER_HASH, $request);
 421     }
 422
 423     /**
 424      * Returns the list of articles for a given day.
 425      *
 426      * @param string $request day to filter. Format: YYYYMMDD.
 427      *
 428      * @return array list of shaare found.
 429      */
 430     public function filterDay($request) {
 431         $linkFilter = new LinkFilter($this->links);
 432         return $linkFilter->filter(LinkFilter::$FILTER_DAY, $request);
 433     }
 434
 435     /**
 436      * Filter links according to search parameters.
 437      *
 438      * @param array  $filterRequest Search request content. Supported keys:
 439      *                                - searchtags: list of tags
 440      *                                - searchterm: term search
 441      * @param bool   $casesensitive Optional: Perform case sensitive filter
 442      * @param bool   $privateonly   Optional: Returns private links only if true.
 443      *
 444      * @return array filtered links, all links if no suitable filter was provided.
 445      */
 446     public function filterSearch($filterRequest = array(), $casesensitive = false, $privateonly = false)
 447     {
 448         // Filter link database according to parameters.
 449         $searchtags = !empty($filterRequest['searchtags']) ? escape($filterRequest['searchtags']) : '';
 450         $searchterm = !empty($filterRequest['searchterm']) ? escape($filterRequest['searchterm']) : '';
 451
 452         // Search tags + fullsearch.
 453         if (! empty($searchtags) && ! empty($searchterm)) {
 454             $type = LinkFilter::$FILTER_TAG | LinkFilter::$FILTER_TEXT;
 455             $request = array($searchtags, $searchterm);
 456         }
 457         // Search by tags.
 458         elseif (! empty($searchtags)) {
 459             $type = LinkFilter::$FILTER_TAG;
 460             $request = $searchtags;
 461         }
 462         // Fulltext search.
 463         elseif (! empty($searchterm)) {
 464             $type = LinkFilter::$FILTER_TEXT;
 465             $request = $searchterm;
 466         }
 467         // Otherwise, display without filtering.
 468         else {
 469             $type = '';
 470             $request = '';
 471         }
 472
 473         $linkFilter = new LinkFilter($this);
 474         return $linkFilter->filter($type, $request, $casesensitive, $privateonly);
 475     }
 476
 477     /**
 478      * Returns the list of all tags
 479      * Output: associative array key=tags, value=0
 480      */
 481     public function allTags()
 482     {
 483         $tags = array();
 484         $caseMapping = array();
 485         foreach ($this->links as $link) {
 486             foreach (preg_split('/\s+/', $link['tags'], 0, PREG_SPLIT_NO_EMPTY) as $tag) {
 487                 if (empty($tag)) {
 488                     continue;
 489                 }
 490                 // The first case found will be displayed.
 491                 if (!isset($caseMapping[strtolower($tag)])) {
 492                     $caseMapping[strtolower($tag)] = $tag;
 493                     $tags[$caseMapping[strtolower($tag)]] = 0;
 494                 }
 495                 $tags[$caseMapping[strtolower($tag)]]++;
 496             }
 497         }
 498         // Sort tags by usage (most used tag first)
 499         arsort($tags);
 500         return $tags;
 501     }
 502
 503     /**
 504      * Returns the list of days containing articles (oldest first)
 505      * Output: An array containing days (in format YYYYMMDD).
 506      */
 507     public function days()
 508     {
 509         $linkDays = array();
 510         foreach ($this->links as $link) {
 511             $linkDays[$link['created']->format('Ymd')] = 0;
 512         }
 513         $linkDays = array_keys($linkDays);
 514         sort($linkDays);
 515
 516         return $linkDays;
 517     }
 518
 519     /**
 520      * Reorder links by creation date (newest first).
 521      *
 522      * Also update the urls and ids mapping arrays.
 523      *
 524      * @param string $order ASC|DESC
 525      */
 526     public function reorder($order = 'DESC')
 527     {
 528         $order = $order === 'ASC' ? -1 : 1;
 529         // Reorder array by dates.
 530         usort($this->links, function($a, $b) use ($order) {
 531             return $a['created'] < $b['created'] ? 1 * $order : -1 * $order;
 532         });
 533
 534         $this->urls = array();
 535         $this->ids = array();
 536         foreach ($this->links as $key => $link) {
 537             $this->urls[$link['url']] = $key;
 538             $this->ids[$link['id']] = $key;
 539         }
 540     }
 541
 542     /**
 543      * Return the next key for link creation.
 544      * E.g. If the last ID is 597, the next will be 598.
 545      *
 546      * @return int next ID.
 547      */
 548     public function getNextId()
 549     {
 550         if (!empty($this->ids)) {
 551             return max(array_keys($this->ids)) + 1;
 552         }
 553         return 0;
 554     }
 555
 556     /**
 557      * Returns a link offset in links array from its unique ID.
 558      *
 559      * @param int $id Persistent ID of a link.
 560      *
 561      * @return int Real offset in local array, or null if doesn't exists.
 562      */
 563     protected function getLinkOffset($id)
 564     {
 565         if (isset($this->ids[$id])) {
 566             return $this->ids[$id];
 567         }
 568         return null;
 569     }
 570 }