application/bookmark/BookmarkFilter.php

   1 <?php
   2
   3 declare(strict_types=1);
   4
   5 namespace Shaarli\Bookmark;
   6
   7 use Exception;
   8 use Shaarli\Bookmark\Exception\BookmarkNotFoundException;
   9
  10 /**
  11  * Class LinkFilter.
  12  *
  13  * Perform search and filter operation on link data list.
  14  */
  15 class BookmarkFilter
  16 {
  17     /**
  18      * @var string permalinks.
  19      */
  20     public static $FILTER_HASH = 'permalink';
  21
  22     /**
  23      * @var string text search.
  24      */
  25     public static $FILTER_TEXT = 'fulltext';
  26
  27     /**
  28      * @var string tag filter.
  29      */
  30     public static $FILTER_TAG = 'tags';
  31
  32     /**
  33      * @var string filter by day.
  34      */
  35     public static $FILTER_DAY = 'FILTER_DAY';
  36
  37     /**
  38      * @var string filter by day.
  39      */
  40     public static $DEFAULT = 'NO_FILTER';
  41
  42     /** @var string Visibility: all */
  43     public static $ALL = 'all';
  44
  45     /** @var string Visibility: public */
  46     public static $PUBLIC = 'public';
  47
  48     /** @var string Visibility: private */
  49     public static $PRIVATE = 'private';
  50
  51     /**
  52      * @var string Allowed characters for hashtags (regex syntax).
  53      */
  54     public static $HASHTAG_CHARS = '\p{Pc}\p{N}\p{L}\p{Mn}';
  55
  56     /**
  57      * @var Bookmark[] all available bookmarks.
  58      */
  59     private $bookmarks;
  60
  61     /**
  62      * @param Bookmark[] $bookmarks initialization.
  63      */
  64     public function __construct($bookmarks)
  65     {
  66         $this->bookmarks = $bookmarks;
  67     }
  68
  69     /**
  70      * Filter bookmarks according to parameters.
  71      *
  72      * @param string $type          Type of filter (eg. tags, permalink, etc.).
  73      * @param mixed  $request       Filter content.
  74      * @param bool   $casesensitive Optional: Perform case sensitive filter if true.
  75      * @param string $visibility    Optional: return only all/private/public bookmarks
  76      * @param bool   $untaggedonly  Optional: return only untagged bookmarks. Applies only if $type includes FILTER_TAG
  77      *
  78      * @return Bookmark[] filtered bookmark list.
  79      *
  80      * @throws BookmarkNotFoundException
  81      */
  82     public function filter(
  83         string $type,
  84         $request,
  85         bool $casesensitive = false,
  86         string $visibility = 'all',
  87         bool $untaggedonly = false
  88     ) {
  89         if (!in_array($visibility, ['all', 'public', 'private'])) {
  90             $visibility = 'all';
  91         }
  92
  93         switch ($type) {
  94             case self::$FILTER_HASH:
  95                 return $this->filterSmallHash($request);
  96             case self::$FILTER_TAG | self::$FILTER_TEXT: // == "vuotext"
  97                 $noRequest = empty($request) || (empty($request[0]) && empty($request[1]));
  98                 if ($noRequest) {
  99                     if ($untaggedonly) {
 100                         return $this->filterUntagged($visibility);
 101                     }
 102                     return $this->noFilter($visibility);
 103                 }
 104                 if ($untaggedonly) {
 105                     $filtered = $this->filterUntagged($visibility);
 106                 } else {
 107                     $filtered = $this->bookmarks;
 108                 }
 109                 if (!empty($request[0])) {
 110                     $filtered = (new BookmarkFilter($filtered))->filterTags($request[0], $casesensitive, $visibility);
 111                 }
 112                 if (!empty($request[1])) {
 113                     $filtered = (new BookmarkFilter($filtered))->filterFulltext($request[1], $visibility);
 114                 }
 115                 return $filtered;
 116             case self::$FILTER_TEXT:
 117                 return $this->filterFulltext($request, $visibility);
 118             case self::$FILTER_TAG:
 119                 if ($untaggedonly) {
 120                     return $this->filterUntagged($visibility);
 121                 } else {
 122                     return $this->filterTags($request, $casesensitive, $visibility);
 123                 }
 124             case self::$FILTER_DAY:
 125                 return $this->filterDay($request, $visibility);
 126             default:
 127                 return $this->noFilter($visibility);
 128         }
 129     }
 130
 131     /**
 132      * Unknown filter, but handle private only.
 133      *
 134      * @param string $visibility Optional: return only all/private/public bookmarks
 135      *
 136      * @return Bookmark[] filtered bookmarks.
 137      */
 138     private function noFilter(string $visibility = 'all')
 139     {
 140         if ($visibility === 'all') {
 141             return $this->bookmarks;
 142         }
 143
 144         $out = array();
 145         foreach ($this->bookmarks as $key => $value) {
 146             if ($value->isPrivate() && $visibility === 'private') {
 147                 $out[$key] = $value;
 148             } elseif (!$value->isPrivate() && $visibility === 'public') {
 149                 $out[$key] = $value;
 150             }
 151         }
 152
 153         return $out;
 154     }
 155
 156     /**
 157      * Returns the shaare corresponding to a smallHash.
 158      *
 159      * @param string $smallHash permalink hash.
 160      *
 161      * @return Bookmark[] $filtered array containing permalink data.
 162      *
 163      * @throws BookmarkNotFoundException if the smallhash doesn't match any link.
 164      */
 165     private function filterSmallHash(string $smallHash)
 166     {
 167         foreach ($this->bookmarks as $key => $l) {
 168             if ($smallHash == $l->getShortUrl()) {
 169                 // Yes, this is ugly and slow
 170                 return [$key => $l];
 171             }
 172         }
 173
 174         throw new BookmarkNotFoundException();
 175     }
 176
 177     /**
 178      * Returns the list of bookmarks corresponding to a full-text search
 179      *
 180      * Searches:
 181      *  - in the URLs, title and description;
 182      *  - are case-insensitive;
 183      *  - terms surrounded by quotes " are exact terms search.
 184      *  - terms starting with a dash - are excluded (except exact terms).
 185      *
 186      * Example:
 187      *    print_r($mydb->filterFulltext('hollandais'));
 188      *
 189      * mb_convert_case($val, MB_CASE_LOWER, 'UTF-8')
 190      *  - allows to perform searches on Unicode text
 191      *  - see https://github.com/shaarli/Shaarli/issues/75 for examples
 192      *
 193      * @param string $searchterms search query.
 194      * @param string $visibility  Optional: return only all/private/public bookmarks.
 195      *
 196      * @return Bookmark[] search results.
 197      */
 198     private function filterFulltext(string $searchterms, string $visibility = 'all')
 199     {
 200         if (empty($searchterms)) {
 201             return $this->noFilter($visibility);
 202         }
 203
 204         $filtered = array();
 205         $search = mb_convert_case(html_entity_decode($searchterms), MB_CASE_LOWER, 'UTF-8');
 206         $exactRegex = '/"([^"]+)"/';
 207         // Retrieve exact search terms.
 208         preg_match_all($exactRegex, $search, $exactSearch);
 209         $exactSearch = array_values(array_filter($exactSearch[1]));
 210
 211         // Remove exact search terms to get AND terms search.
 212         $explodedSearchAnd = explode(' ', trim(preg_replace($exactRegex, '', $search)));
 213         $explodedSearchAnd = array_values(array_filter($explodedSearchAnd));
 214
 215         // Filter excluding terms and update andSearch.
 216         $excludeSearch = array();
 217         $andSearch = array();
 218         foreach ($explodedSearchAnd as $needle) {
 219             if ($needle[0] == '-' && strlen($needle) > 1) {
 220                 $excludeSearch[] = substr($needle, 1);
 221             } else {
 222                 $andSearch[] = $needle;
 223             }
 224         }
 225
 226         // Iterate over every stored link.
 227         foreach ($this->bookmarks as $id => $link) {
 228             // ignore non private bookmarks when 'privatonly' is on.
 229             if ($visibility !== 'all') {
 230                 if (!$link->isPrivate() && $visibility === 'private') {
 231                     continue;
 232                 } elseif ($link->isPrivate() && $visibility === 'public') {
 233                     continue;
 234                 }
 235             }
 236
 237             // Concatenate link fields to search across fields.
 238             // Adds a '\' separator for exact search terms.
 239             $content  = mb_convert_case($link->getTitle(), MB_CASE_LOWER, 'UTF-8') .'\\';
 240             $content .= mb_convert_case($link->getDescription(), MB_CASE_LOWER, 'UTF-8') .'\\';
 241             $content .= mb_convert_case($link->getUrl(), MB_CASE_LOWER, 'UTF-8') .'\\';
 242             $content .= mb_convert_case($link->getTagsString(), MB_CASE_LOWER, 'UTF-8') .'\\';
 243
 244             // Be optimistic
 245             $found = true;
 246
 247             // First, we look for exact term search
 248             for ($i = 0; $i < count($exactSearch) && $found; $i++) {
 249                 $found = strpos($content, $exactSearch[$i]) !== false;
 250             }
 251
 252             // Iterate over keywords, if keyword is not found,
 253             // no need to check for the others. We want all or nothing.
 254             for ($i = 0; $i < count($andSearch) && $found; $i++) {
 255                 $found = strpos($content, $andSearch[$i]) !== false;
 256             }
 257
 258             // Exclude terms.
 259             for ($i = 0; $i < count($excludeSearch) && $found; $i++) {
 260                 $found = strpos($content, $excludeSearch[$i]) === false;
 261             }
 262
 263             if ($found) {
 264                 $filtered[$id] = $link;
 265             }
 266         }
 267
 268         return $filtered;
 269     }
 270
 271     /**
 272      * generate a regex fragment out of a tag
 273      *
 274      * @param string $tag to to generate regexs from. may start with '-' to negate, contain '*' as wildcard
 275      *
 276      * @return string generated regex fragment
 277      */
 278     private static function tag2regex(string $tag): string
 279     {
 280         $len = strlen($tag);
 281         if (!$len || $tag === "-" || $tag === "*") {
 282             // nothing to search, return empty regex
 283             return '';
 284         }
 285         if ($tag[0] === "-") {
 286             // query is negated
 287             $i = 1; // use offset to start after '-' character
 288             $regex = '(?!'; // create negative lookahead
 289         } else {
 290             $i = 0; // start at first character
 291             $regex = '(?='; // use positive lookahead
 292         }
 293         $regex .= '.*(?:^| )'; // before tag may only be a space or the beginning
 294         // iterate over string, separating it into placeholder and content
 295         for (; $i < $len; $i++) {
 296             if ($tag[$i] === '*') {
 297                 // placeholder found
 298                 $regex .= '[^ ]*?';
 299             } else {
 300                 // regular characters
 301                 $offset = strpos($tag, '*', $i);
 302                 if ($offset === false) {
 303                     // no placeholder found, set offset to end of string
 304                     $offset = $len;
 305                 }
 306                 // subtract one, as we want to get before the placeholder or end of string
 307                 $offset -= 1;
 308                 // we got a tag name that we want to search for. escape any regex characters to prevent conflicts.
 309                 $regex .= preg_quote(substr($tag, $i, $offset - $i + 1), '/');
 310                 // move $i on
 311                 $i = $offset;
 312             }
 313         }
 314         $regex .= '(?:$| ))'; // after the tag may only be a space or the end
 315         return $regex;
 316     }
 317
 318     /**
 319      * Returns the list of bookmarks associated with a given list of tags
 320      *
 321      * You can specify one or more tags, separated by space or a comma, e.g.
 322      *  print_r($mydb->filterTags('linux programming'));
 323      *
 324      * @param string|array $tags          list of tags, separated by commas or blank spaces if passed as string.
 325      * @param bool         $casesensitive ignore case if false.
 326      * @param string       $visibility    Optional: return only all/private/public bookmarks.
 327      *
 328      * @return Bookmark[] filtered bookmarks.
 329      */
 330     public function filterTags($tags, bool $casesensitive = false, string $visibility = 'all')
 331     {
 332         // get single tags (we may get passed an array, even though the docs say different)
 333         $inputTags = $tags;
 334         if (!is_array($tags)) {
 335             // we got an input string, split tags
 336             $inputTags = preg_split('/(?:\s+)|,/', $inputTags, -1, PREG_SPLIT_NO_EMPTY);
 337         }
 338
 339         if (!count($inputTags)) {
 340             // no input tags
 341             return $this->noFilter($visibility);
 342         }
 343
 344         // If we only have public visibility, we can't look for hidden tags
 345         if ($visibility === self::$PUBLIC) {
 346             $inputTags = array_values(array_filter($inputTags, function ($tag) {
 347                 return ! startsWith($tag, '.');
 348             }));
 349
 350             if (empty($inputTags)) {
 351                 return [];
 352             }
 353         }
 354
 355         // build regex from all tags
 356         $re = '/^' . implode(array_map("self::tag2regex", $inputTags)) . '.*$/';
 357         if (!$casesensitive) {
 358             // make regex case insensitive
 359             $re .= 'i';
 360         }
 361
 362         // create resulting array
 363         $filtered = [];
 364
 365         // iterate over each link
 366         foreach ($this->bookmarks as $key => $link) {
 367             // check level of visibility
 368             // ignore non private bookmarks when 'privateonly' is on.
 369             if ($visibility !== 'all') {
 370                 if (!$link->isPrivate() && $visibility === 'private') {
 371                     continue;
 372                 } elseif ($link->isPrivate() && $visibility === 'public') {
 373                     continue;
 374                 }
 375             }
 376             $search = $link->getTagsString(); // build search string, start with tags of current link
 377             if (strlen(trim($link->getDescription())) && strpos($link->getDescription(), '#') !== false) {
 378                 // description given and at least one possible tag found
 379                 $descTags = array();
 380                 // find all tags in the form of #tag in the description
 381                 preg_match_all(
 382                     '/(?<![' . self::$HASHTAG_CHARS . '])#([' . self::$HASHTAG_CHARS . ']+?)\b/sm',
 383                     $link->getDescription(),
 384                     $descTags
 385                 );
 386                 if (count($descTags[1])) {
 387                     // there were some tags in the description, add them to the search string
 388                     $search .= ' ' . implode(' ', $descTags[1]);
 389                 }
 390             };
 391             // match regular expression with search string
 392             if (!preg_match($re, $search)) {
 393                 // this entry does _not_ match our regex
 394                 continue;
 395             }
 396             $filtered[$key] = $link;
 397         }
 398         return $filtered;
 399     }
 400
 401     /**
 402      * Return only bookmarks without any tag.
 403      *
 404      * @param string $visibility return only all/private/public bookmarks.
 405      *
 406      * @return Bookmark[] filtered bookmarks.
 407      */
 408     public function filterUntagged(string $visibility)
 409     {
 410         $filtered = [];
 411         foreach ($this->bookmarks as $key => $link) {
 412             if ($visibility !== 'all') {
 413                 if (!$link->isPrivate() && $visibility === 'private') {
 414                     continue;
 415                 } elseif ($link->isPrivate() && $visibility === 'public') {
 416                     continue;
 417                 }
 418             }
 419
 420             if (empty(trim($link->getTagsString()))) {
 421                 $filtered[$key] = $link;
 422             }
 423         }
 424
 425         return $filtered;
 426     }
 427
 428     /**
 429      * Returns the list of articles for a given day, chronologically sorted
 430      *
 431      * Day must be in the form 'YYYYMMDD' (e.g. '20120125'), e.g.
 432      *  print_r($mydb->filterDay('20120125'));
 433      *
 434      * @param string $day day to filter.
 435      * @param string $visibility return only all/private/public bookmarks.
 436
 437      * @return Bookmark[] all link matching given day.
 438      *
 439      * @throws Exception if date format is invalid.
 440      */
 441     public function filterDay(string $day, string $visibility)
 442     {
 443         if (!checkDateFormat('Ymd', $day)) {
 444             throw new Exception('Invalid date format');
 445         }
 446
 447         $filtered = [];
 448         foreach ($this->bookmarks as $key => $bookmark) {
 449             if ($visibility === static::$PUBLIC && $bookmark->isPrivate()) {
 450                 continue;
 451             }
 452
 453             if ($bookmark->getCreated()->format('Ymd') == $day) {
 454                 $filtered[$key] = $bookmark;
 455             }
 456         }
 457
 458         // sort by date ASC
 459         return array_reverse($filtered, true);
 460     }
 461
 462     /**
 463      * Convert a list of tags (str) to an array. Also
 464      * - handle case sensitivity.
 465      * - accepts spaces commas as separator.
 466      *
 467      * @param string $tags          string containing a list of tags.
 468      * @param bool   $casesensitive will convert everything to lowercase if false.
 469      *
 470      * @return string[] filtered tags string.
 471      */
 472     public static function tagsStrToArray(string $tags, bool $casesensitive): array
 473     {
 474         // We use UTF-8 conversion to handle various graphemes (i.e. cyrillic, or greek)
 475         $tagsOut = $casesensitive ? $tags : mb_convert_case($tags, MB_CASE_LOWER, 'UTF-8');
 476         $tagsOut = str_replace(',', ' ', $tagsOut);
 477
 478         return preg_split('/\s+/', $tagsOut, -1, PREG_SPLIT_NO_EMPTY);
 479     }
 480 }