3 namespace Shaarli\Bookmark
;
9 use Shaarli\Bookmark\Exception\LinkNotFoundException
;
10 use Shaarli\Exceptions\IOException
;
11 use Shaarli\FileUtils
;
14 * Data storage for links.
16 * This object behaves like an associative array.
19 * $myLinks = new LinkDB();
20 * echo $myLinks[350]['title'];
21 * foreach ($myLinks as $link)
22 * echo $link['title'].' at url '.$link['url'].'; description:'.$link['description'];
25 * - id: primary key, incremental integer identifier (persistent)
26 * - description: description of the entry
27 * - created: creation date of this entry, DateTime object.
28 * - updated: last modification date of this entry, DateTime object.
29 * - private: Is this link private? 0=no, other value=yes
30 * - tags: tags attached to this entry (separated by spaces)
31 * - title Title of the link
32 * - url URL of the link. Used for displayable links.
33 * Can be absolute or relative in the database but the relative links
34 * will be converted to absolute ones in templates.
35 * - real_url Raw URL in stored in the DB (absolute or relative).
36 * - shorturl Permalink smallhash
38 * Implements 3 interfaces:
39 * - ArrayAccess: behaves like an associative array;
40 * - Countable: there is a count() method;
41 * - Iterator: usable in foreach () loops.
44 * ArrayAccess is implemented in a way that will allow to access a link
45 * with the unique identifier ID directly with $link[ID].
46 * Note that it's not the real key of the link array attribute.
47 * This mechanism is in place to have persistent link IDs,
48 * even though the internal array is reordered by date.
50 * - DB: link #1 (2010-01-01) link #2 (2016-01-01)
52 * - Import links containing: link #3 (2013-01-01)
53 * - New DB: link #1 (2010-01-01) link #2 (2016-01-01) link #3 (2013-01-01)
54 * - Real order: #2 #3 #1
56 class LinkDB
implements Iterator
, Countable
, ArrayAccess
58 // Links are stored as a PHP serialized string
61 // Link date storage format
62 const LINK_DATE_FORMAT
= 'Ymd_His';
64 // List of links (associative array)
65 // - key: link date (e.g. "20110823_124546"),
66 // - value: associative array (keys: title, description...)
69 // List of all recorded URLs (key=url, value=link offset)
70 // for fast reserve search (url-->link offset)
74 * @var array List of all links IDS mapped with their array offset.
79 // List of offset keys (for the Iterator interface implementation)
82 // Position in the $this->keys array (for the Iterator interface)
85 // Is the user logged in? (used to filter private links)
89 private $hidePublicLinks;
92 * Creates a new LinkDB
94 * Checks if the datastore exists; else, attempts to create a dummy one.
96 * @param string $datastore datastore file path.
97 * @param boolean $isLoggedIn is the user logged in?
98 * @param boolean $hidePublicLinks if true all links are private.
100 public function __construct(
106 $this->datastore
= $datastore;
107 $this->loggedIn
= $isLoggedIn;
108 $this->hidePublicLinks
= $hidePublicLinks;
114 * Countable - Counts elements of an object
116 public function count()
118 return count($this->links
);
122 * ArrayAccess - Assigns a value to the specified offset
124 public function offsetSet($offset, $value)
126 // TODO: use exceptions instead of "die"
127 if (!$this->loggedIn
) {
128 die(t('You are not authorized to add a link.'));
130 if (!isset($value['id']) || empty($value['url'])) {
131 die(t('Internal Error: A link should always have an id and URL.'));
133 if (($offset !== null && !is_int($offset)) || !is_int($value['id'])) {
134 die(t('You must specify an integer as a key.'));
136 if ($offset !== null && $offset !== $value['id']) {
137 die(t('Array offset and link ID must be equal.'));
140 // If the link exists, we reuse the real offset, otherwise new entry
141 $existing = $this->getLinkOffset($offset);
142 if ($existing !== null) {
145 $offset = count($this->links
);
147 $this->links
[$offset] = $value;
148 $this->urls
[$value['url']] = $offset;
149 $this->ids
[$value['id']] = $offset;
153 * ArrayAccess - Whether or not an offset exists
155 public function offsetExists($offset)
157 return array_key_exists($this->getLinkOffset($offset), $this->links
);
161 * ArrayAccess - Unsets an offset
163 public function offsetUnset($offset)
165 if (!$this->loggedIn
) {
166 // TODO: raise an exception
167 die('You are not authorized to delete a link.');
169 $realOffset = $this->getLinkOffset($offset);
170 $url = $this->links
[$realOffset]['url'];
171 unset($this->urls
[$url]);
172 unset($this->ids
[$realOffset]);
173 unset($this->links
[$realOffset]);
177 * ArrayAccess - Returns the value at specified offset
179 public function offsetGet($offset)
181 $realOffset = $this->getLinkOffset($offset);
182 return isset($this->links
[$realOffset]) ? $this->links
[$realOffset] : null;
186 * Iterator - Returns the current element
188 public function current()
190 return $this[$this->keys
[$this->position
]];
194 * Iterator - Returns the key of the current element
196 public function key()
198 return $this->keys
[$this->position
];
202 * Iterator - Moves forward to next element
204 public function next()
210 * Iterator - Rewinds the Iterator to the first element
212 * Entries are sorted by date (latest first)
214 public function rewind()
216 $this->keys
= array_keys($this->ids
);
221 * Iterator - Checks if current position is valid
223 public function valid()
225 return isset($this->keys
[$this->position
]);
229 * Checks if the DB directory and file exist
231 * If no DB file is found, creates a dummy DB.
233 private function check()
235 if (file_exists($this->datastore
)) {
239 // Create a dummy database for example
240 $this->links
= array();
243 'title' => t('The personal, minimalist, super-fast, database free, bookmarking service'),
244 'url' => 'https://shaarli.readthedocs.io',
246 'Welcome to Shaarli! This is your first public bookmark. '
247 . 'To edit or delete me, you must first login.
249 To learn how to use Shaarli, consult the link "Documentation" at the bottom of this page.
251 You use the community supported version of the original Shaarli project, by Sebastien Sauvage.'
254 'created' => new DateTime(),
255 'tags' => 'opensource software',
258 $link['shorturl'] = link_small_hash($link['created'], $link['id']);
259 $this->links
[1] = $link;
263 'title' => t('My secret stuff... - Pastebin.com'),
264 'url' => 'http://sebsauvage.net/paste/?8434b27936c09649#bR7XsXhoTiLcqCpQbmOpBi3rq2zzQUC5hBI7ZT1O3x8=',
265 'description' => t('Shhhh! I\'m a private link only YOU can see. You can delete me too.'),
267 'created' => new DateTime('1 minute ago'),
268 'tags' => 'secretstuff',
271 $link['shorturl'] = link_small_hash($link['created'], $link['id']);
272 $this->links
[0] = $link;
274 // Write database to disk
279 * Reads database from disk to memory
281 private function read()
283 // Public links are hidden and user not logged in => nothing to show
284 if ($this->hidePublicLinks
&& !$this->loggedIn
) {
285 $this->links
= array();
291 $this->links
= FileUtils
::readFlatDB($this->datastore
, []);
294 foreach ($this->links
as $key => &$link) {
295 if (!$this->loggedIn
&& $link['private'] != 0) {
296 // Transition for not upgraded databases.
297 unset($this->links
[$key]);
301 // Sanitize data fields.
304 // Remove private tags if the user is not logged in.
305 if (!$this->loggedIn
) {
306 $link['tags'] = preg_replace('/(^|\s+)\.[^($|\s)]+\s*/', ' ', $link['tags']);
309 $link['real_url'] = $link['url'];
311 $link['sticky'] = isset($link['sticky']) ? $link['sticky'] : false;
313 // To be able to load links before running the update, and prepare the update
314 if (!isset($link['created'])) {
315 $link['id'] = $link['linkdate'];
316 $link['created'] = DateTime
::createFromFormat(self
::LINK_DATE_FORMAT
, $link['linkdate']);
317 if (!empty($link['updated'])) {
318 $link['updated'] = DateTime
::createFromFormat(self
::LINK_DATE_FORMAT
, $link['updated']);
320 $link['shorturl'] = smallHash($link['linkdate']);
323 $this->urls
[$link['url']] = $key;
324 $this->ids
[$link['id']] = $key;
329 * Saves the database from memory to disk
331 * @throws IOException the datastore is not writable
333 private function write()
336 FileUtils
::writeFlatDB($this->datastore
, $this->links
);
340 * Saves the database from memory to disk
342 * @param string $pageCacheDir page cache directory
344 public function save($pageCacheDir)
346 if (!$this->loggedIn
) {
347 // TODO: raise an Exception instead
348 die('You are not authorized to change the database.');
353 invalidateCaches($pageCacheDir);
357 * Returns the link for a given URL, or False if it does not exist.
359 * @param string $url URL to search for
361 * @return mixed the existing link if it exists, else 'false'
363 public function getLinkFromUrl($url)
365 if (isset($this->urls
[$url])) {
366 return $this->links
[$this->urls
[$url]];
372 * Returns the shaare corresponding to a smallHash.
374 * @param string $request QUERY_STRING server parameter.
376 * @return array $filtered array containing permalink data.
378 * @throws LinkNotFoundException if the smallhash is malformed or doesn't match any link.
380 public function filterHash($request)
382 $request = substr($request, 0, 6);
383 $linkFilter = new LinkFilter($this->links
);
384 return $linkFilter->filter(LinkFilter
::$FILTER_HASH, $request);
388 * Returns the list of articles for a given day.
390 * @param string $request day to filter. Format: YYYYMMDD.
392 * @return array list of shaare found.
394 public function filterDay($request)
396 $linkFilter = new LinkFilter($this->links
);
397 return $linkFilter->filter(LinkFilter
::$FILTER_DAY, $request);
401 * Filter links according to search parameters.
403 * @param array $filterRequest Search request content. Supported keys:
404 * - searchtags: list of tags
405 * - searchterm: term search
406 * @param bool $casesensitive Optional: Perform case sensitive filter
407 * @param string $visibility return only all/private/public links
408 * @param bool $untaggedonly return only untagged links
410 * @return array filtered links, all links if no suitable filter was provided.
412 public function filterSearch(
413 $filterRequest = array(),
414 $casesensitive = false,
416 $untaggedonly = false
419 // Filter link database according to parameters.
420 $searchtags = isset($filterRequest['searchtags']) ? escape($filterRequest['searchtags']) : '';
421 $searchterm = isset($filterRequest['searchterm']) ? escape($filterRequest['searchterm']) : '';
423 // Search tags + fullsearch - blank string parameter will return all links.
424 $type = LinkFilter
::$FILTER_TAG | LinkFilter
::$FILTER_TEXT; // == "vuotext"
425 $request = [$searchtags, $searchterm];
427 $linkFilter = new LinkFilter($this);
428 return $linkFilter->filter($type, $request, $casesensitive, $visibility, $untaggedonly);
432 * Returns the list tags appearing in the links with the given tags
434 * @param array $filteringTags tags selecting the links to consider
435 * @param string $visibility process only all/private/public links
437 * @return array tag => linksCount
439 public function linksCountPerTag($filteringTags = [], $visibility = 'all')
441 $links = $this->filterSearch(['searchtags' => $filteringTags], false, $visibility);
444 foreach ($links as $link) {
445 foreach (preg_split('/\s+/', $link['tags'], 0, PREG_SPLIT_NO_EMPTY
) as $tag) {
449 // The first case found will be displayed.
450 if (!isset($caseMapping[strtolower($tag)])) {
451 $caseMapping[strtolower($tag)] = $tag;
452 $tags[$caseMapping[strtolower($tag)]] = 0;
454 $tags[$caseMapping[strtolower($tag)]]++
;
459 * Formerly used arsort(), which doesn't define the sort behaviour for equal values.
460 * Also, this function doesn't produce the same result between PHP 5.6 and 7.
462 * So we now use array_multisort() to sort tags by DESC occurrences,
463 * then ASC alphabetically for equal values.
465 * @see https://github.com/shaarli/Shaarli/issues/1142
467 $keys = array_keys($tags);
468 $tmpTags = array_combine($keys, $keys);
469 array_multisort($tags, SORT_DESC
, $tmpTags, SORT_ASC
, $tags);
474 * Rename or delete a tag across all links.
476 * @param string $from Tag to rename
477 * @param string $to New tag. If none is provided, the from tag will be deleted
479 * @return array|bool List of altered links or false on error
481 public function renameTag($from, $to)
486 $delete = empty($to);
487 // True for case-sensitive tag search.
488 $linksToAlter = $this->filterSearch(['searchtags' => $from], true);
489 foreach ($linksToAlter as $key => &$value) {
490 $tags = preg_split('/\s+/', trim($value['tags']));
491 if (($pos = array_search($from, $tags)) !== false) {
493 unset($tags[$pos]); // Remove tag.
495 $tags[$pos] = trim($to);
497 $value['tags'] = trim(implode(' ', array_unique($tags)));
498 $this[$value['id']] = $value;
502 return $linksToAlter;
506 * Returns the list of days containing articles (oldest first)
507 * Output: An array containing days (in format YYYYMMDD).
509 public function days()
512 foreach ($this->links
as $link) {
513 $linkDays[$link['created']->format('Ymd')] = 0;
515 $linkDays = array_keys($linkDays);
522 * Reorder links by creation date (newest first).
524 * Also update the urls and ids mapping arrays.
526 * @param string $order ASC|DESC
528 public function reorder($order = 'DESC')
530 $order = $order === 'ASC' ? -1 : 1;
531 // Reorder array by dates.
532 usort($this->links
, function ($a, $b) use ($order) {
533 if (isset($a['sticky']) && isset($b['sticky']) && $a['sticky'] !== $b['sticky']) {
534 return $a['sticky'] ? -1 : 1;
536 return $a['created'] < $b['created'] ? 1 * $order : -1 * $order;
541 foreach ($this->links
as $key => $link) {
542 $this->urls
[$link['url']] = $key;
543 $this->ids
[$link['id']] = $key;
548 * Return the next key for link creation.
549 * E.g. If the last ID is 597, the next will be 598.
551 * @return int next ID.
553 public function getNextId()
555 if (!empty($this->ids
)) {
556 return max(array_keys($this->ids
)) +
1;
562 * Returns a link offset in links array from its unique ID.
564 * @param int $id Persistent ID of a link.
566 * @return int Real offset in local array, or null if doesn't exist.
568 protected function getLinkOffset($id)
570 if (isset($this->ids
[$id])) {
571 return $this->ids
[$id];