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