application/bookmark/Bookmark.php

   1 <?php
   2
   3 declare(strict_types=1);
   4
   5 namespace Shaarli\Bookmark;
   6
   7 use DateTime;
   8 use DateTimeInterface;
   9 use Shaarli\Bookmark\Exception\InvalidBookmarkException;
  10
  11 /**
  12  * Class Bookmark
  13  *
  14  * This class represent a single Bookmark with all its attributes.
  15  * Every bookmark should manipulated using this, before being formatted.
  16  *
  17  * @package Shaarli\Bookmark
  18  */
  19 class Bookmark
  20 {
  21     /** @var string Date format used in string (former ID format) */
  22     const LINK_DATE_FORMAT = 'Ymd_His';
  23
  24     /** @var int Bookmark ID */
  25     protected $id;
  26
  27     /** @var string Permalink identifier */
  28     protected $shortUrl;
  29
  30     /** @var string Bookmark's URL - $shortUrl prefixed with `?` for notes */
  31     protected $url;
  32
  33     /** @var string Bookmark's title */
  34     protected $title;
  35
  36     /** @var string Raw bookmark's description */
  37     protected $description;
  38
  39     /** @var array List of bookmark's tags */
  40     protected $tags;
  41
  42     /** @var string|bool|null Thumbnail's URL - initialized at null, false if no thumbnail could be found */
  43     protected $thumbnail;
  44
  45     /** @var bool Set to true if the bookmark is set as sticky */
  46     protected $sticky;
  47
  48     /** @var DateTimeInterface Creation datetime */
  49     protected $created;
  50
  51     /** @var DateTimeInterface datetime */
  52     protected $updated;
  53
  54     /** @var bool True if the bookmark can only be seen while logged in */
  55     protected $private;
  56
  57     /** @var mixed[] Available to store any additional content for a bookmark. Currently used for search highlight. */
  58     protected $additionalContent = [];
  59
  60     /**
  61      * Initialize a link from array data. Especially useful to create a Bookmark from former link storage format.
  62      *
  63      * @param array  $data
  64      * @param string $tagsSeparator Tags separator loaded from the config file.
  65      *                              This is a context data, and it should *never* be stored in the Bookmark object.
  66      *
  67      * @return $this
  68      */
  69     public function fromArray(array $data, string $tagsSeparator = ' '): Bookmark
  70     {
  71         $this->id = $data['id'] ?? null;
  72         $this->shortUrl = $data['shorturl'] ?? null;
  73         $this->url = $data['url'] ?? null;
  74         $this->title = $data['title'] ?? null;
  75         $this->description = $data['description'] ?? null;
  76         $this->thumbnail = $data['thumbnail'] ?? null;
  77         $this->sticky = $data['sticky'] ?? false;
  78         $this->created = $data['created'] ?? null;
  79         if (is_array($data['tags'])) {
  80             $this->tags = $data['tags'];
  81         } else {
  82             $this->tags = tags_str2array($data['tags'] ?? '', $tagsSeparator);
  83         }
  84         if (! empty($data['updated'])) {
  85             $this->updated = $data['updated'];
  86         }
  87         $this->private = ($data['private'] ?? false) ? true : false;
  88
  89         return $this;
  90     }
  91
  92     /**
  93      * Make sure that the current instance of Bookmark is valid and can be saved into the data store.
  94      * A valid link requires:
  95      *   - an integer ID
  96      *   - a short URL (for permalinks)
  97      *   - a creation date
  98      *
  99      * This function also initialize optional empty fields:
 100      *   - the URL with the permalink
 101      *   - the title with the URL
 102      *
 103      * Also make sure that we do not save search highlights in the datastore.
 104      *
 105      * @throws InvalidBookmarkException
 106      */
 107     public function validate(): void
 108     {
 109         if (
 110             $this->id === null
 111             || ! is_int($this->id)
 112             || empty($this->shortUrl)
 113             || empty($this->created)
 114         ) {
 115             throw new InvalidBookmarkException($this);
 116         }
 117         if (empty($this->url)) {
 118             $this->url = '/shaare/' . $this->shortUrl;
 119         }
 120         if (empty($this->title)) {
 121             $this->title = $this->url;
 122         }
 123         if (array_key_exists('search_highlight', $this->additionalContent)) {
 124             unset($this->additionalContent['search_highlight']);
 125         }
 126     }
 127
 128     /**
 129      * Set the Id.
 130      * If they're not already initialized, this function also set:
 131      *   - created: with the current datetime
 132      *   - shortUrl: with a generated small hash from the date and the given ID
 133      *
 134      * @param int|null $id
 135      *
 136      * @return Bookmark
 137      */
 138     public function setId(?int $id): Bookmark
 139     {
 140         $this->id = $id;
 141         if (empty($this->created)) {
 142             $this->created = new DateTime();
 143         }
 144         if (empty($this->shortUrl)) {
 145             $this->shortUrl = link_small_hash($this->created, $this->id);
 146         }
 147
 148         return $this;
 149     }
 150
 151     /**
 152      * Get the Id.
 153      *
 154      * @return int|null
 155      */
 156     public function getId(): ?int
 157     {
 158         return $this->id;
 159     }
 160
 161     /**
 162      * Get the ShortUrl.
 163      *
 164      * @return string|null
 165      */
 166     public function getShortUrl(): ?string
 167     {
 168         return $this->shortUrl;
 169     }
 170
 171     /**
 172      * Get the Url.
 173      *
 174      * @return string|null
 175      */
 176     public function getUrl(): ?string
 177     {
 178         return $this->url;
 179     }
 180
 181     /**
 182      * Get the Title.
 183      *
 184      * @return string
 185      */
 186     public function getTitle(): ?string
 187     {
 188         return $this->title;
 189     }
 190
 191     /**
 192      * Get the Description.
 193      *
 194      * @return string
 195      */
 196     public function getDescription(): string
 197     {
 198         return ! empty($this->description) ? $this->description : '';
 199     }
 200
 201     /**
 202      * Get the Created.
 203      *
 204      * @return DateTimeInterface
 205      */
 206     public function getCreated(): ?DateTimeInterface
 207     {
 208         return $this->created;
 209     }
 210
 211     /**
 212      * Get the Updated.
 213      *
 214      * @return DateTimeInterface
 215      */
 216     public function getUpdated(): ?DateTimeInterface
 217     {
 218         return $this->updated;
 219     }
 220
 221     /**
 222      * Set the ShortUrl.
 223      *
 224      * @param string|null $shortUrl
 225      *
 226      * @return Bookmark
 227      */
 228     public function setShortUrl(?string $shortUrl): Bookmark
 229     {
 230         $this->shortUrl = $shortUrl;
 231
 232         return $this;
 233     }
 234
 235     /**
 236      * Set the Url.
 237      *
 238      * @param string|null $url
 239      * @param string[]    $allowedProtocols
 240      *
 241      * @return Bookmark
 242      */
 243     public function setUrl(?string $url, array $allowedProtocols = []): Bookmark
 244     {
 245         $url = $url !== null ? trim($url) : '';
 246         if (! empty($url)) {
 247             $url = whitelist_protocols($url, $allowedProtocols);
 248         }
 249         $this->url = $url;
 250
 251         return $this;
 252     }
 253
 254     /**
 255      * Set the Title.
 256      *
 257      * @param string|null $title
 258      *
 259      * @return Bookmark
 260      */
 261     public function setTitle(?string $title): Bookmark
 262     {
 263         $this->title = $title !== null ? trim($title) : '';
 264
 265         return $this;
 266     }
 267
 268     /**
 269      * Set the Description.
 270      *
 271      * @param string|null $description
 272      *
 273      * @return Bookmark
 274      */
 275     public function setDescription(?string $description): Bookmark
 276     {
 277         $this->description = $description;
 278
 279         return $this;
 280     }
 281
 282     /**
 283      * Set the Created.
 284      * Note: you shouldn't set this manually except for special cases (like bookmark import)
 285      *
 286      * @param DateTimeInterface|null $created
 287      *
 288      * @return Bookmark
 289      */
 290     public function setCreated(?DateTimeInterface $created): Bookmark
 291     {
 292         $this->created = $created;
 293
 294         return $this;
 295     }
 296
 297     /**
 298      * Set the Updated.
 299      *
 300      * @param DateTimeInterface|null $updated
 301      *
 302      * @return Bookmark
 303      */
 304     public function setUpdated(?DateTimeInterface $updated): Bookmark
 305     {
 306         $this->updated = $updated;
 307
 308         return $this;
 309     }
 310
 311     /**
 312      * Get the Private.
 313      *
 314      * @return bool
 315      */
 316     public function isPrivate(): bool
 317     {
 318         return $this->private ? true : false;
 319     }
 320
 321     /**
 322      * Set the Private.
 323      *
 324      * @param bool|null $private
 325      *
 326      * @return Bookmark
 327      */
 328     public function setPrivate(?bool $private): Bookmark
 329     {
 330         $this->private = $private ? true : false;
 331
 332         return $this;
 333     }
 334
 335     /**
 336      * Get the Tags.
 337      *
 338      * @return string[]
 339      */
 340     public function getTags(): array
 341     {
 342         return is_array($this->tags) ? $this->tags : [];
 343     }
 344
 345     /**
 346      * Set the Tags.
 347      *
 348      * @param string[]|null $tags
 349      *
 350      * @return Bookmark
 351      */
 352     public function setTags(?array $tags): Bookmark
 353     {
 354         $this->tags = array_map(
 355             function (string $tag): string {
 356                 return $tag[0] === '-' ? substr($tag, 1) : $tag;
 357             },
 358             tags_filter($tags, ' ')
 359         );
 360
 361         return $this;
 362     }
 363
 364     /**
 365      * Get the Thumbnail.
 366      *
 367      * @return string|bool|null Thumbnail's URL - initialized at null, false if no thumbnail could be found
 368      */
 369     public function getThumbnail()
 370     {
 371         return !$this->isNote() ? $this->thumbnail : false;
 372     }
 373
 374     /**
 375      * Set the Thumbnail.
 376      *
 377      * @param string|bool|null $thumbnail Thumbnail's URL - false if no thumbnail could be found
 378      *
 379      * @return Bookmark
 380      */
 381     public function setThumbnail($thumbnail): Bookmark
 382     {
 383         $this->thumbnail = $thumbnail;
 384
 385         return $this;
 386     }
 387
 388     /**
 389      * Return true if:
 390      *   - the bookmark's thumbnail is not already set to false (= not found)
 391      *   - it's not a note
 392      *   - it's an HTTP(S) link
 393      *   - the thumbnail has not yet be retrieved (null) or its associated cache file doesn't exist anymore
 394      *
 395      * @return bool True if the bookmark's thumbnail needs to be retrieved.
 396      */
 397     public function shouldUpdateThumbnail(): bool
 398     {
 399         return $this->thumbnail !== false
 400             && !$this->isNote()
 401             && startsWith(strtolower($this->url), 'http')
 402             && (null === $this->thumbnail || !is_file($this->thumbnail))
 403         ;
 404     }
 405
 406     /**
 407      * Get the Sticky.
 408      *
 409      * @return bool
 410      */
 411     public function isSticky(): bool
 412     {
 413         return $this->sticky ? true : false;
 414     }
 415
 416     /**
 417      * Set the Sticky.
 418      *
 419      * @param bool|null $sticky
 420      *
 421      * @return Bookmark
 422      */
 423     public function setSticky(?bool $sticky): Bookmark
 424     {
 425         $this->sticky = $sticky ? true : false;
 426
 427         return $this;
 428     }
 429
 430     /**
 431      * @param string $separator Tags separator loaded from the config file.
 432      *
 433      * @return string Bookmark's tags as a string, separated by a separator
 434      */
 435     public function getTagsString(string $separator = ' '): string
 436     {
 437         return tags_array2str($this->getTags(), $separator);
 438     }
 439
 440     /**
 441      * @return bool
 442      */
 443     public function isNote(): bool
 444     {
 445         // We check empty value to get a valid result if the link has not been saved yet
 446         return empty($this->url) || startsWith($this->url, '/shaare/') || $this->url[0] === '?';
 447     }
 448
 449     /**
 450      * Set tags from a string.
 451      * Note:
 452      *   - tags must be separated whether by a space or a comma
 453      *   - multiple spaces will be removed
 454      *   - trailing dash in tags will be removed
 455      *
 456      * @param string|null $tags
 457      * @param string      $separator Tags separator loaded from the config file.
 458      *
 459      * @return $this
 460      */
 461     public function setTagsString(?string $tags, string $separator = ' '): Bookmark
 462     {
 463         $this->setTags(tags_str2array($tags, $separator));
 464
 465         return $this;
 466     }
 467
 468     /**
 469      * Get entire additionalContent array.
 470      *
 471      * @return mixed[]
 472      */
 473     public function getAdditionalContent(): array
 474     {
 475         return $this->additionalContent;
 476     }
 477
 478     /**
 479      * Set a single entry in additionalContent, by key.
 480      *
 481      * @param string     $key
 482      * @param mixed|null $value Any type of value can be set.
 483      *
 484      * @return $this
 485      */
 486     public function addAdditionalContentEntry(string $key, $value): self
 487     {
 488         $this->additionalContent[$key] = $value;
 489
 490         return $this;
 491     }
 492
 493     /**
 494      * Get a single entry in additionalContent, by key.
 495      *
 496      * @param string $key
 497      * @param mixed|null $default
 498      *
 499      * @return mixed|null can be any type or even null.
 500      */
 501     public function getAdditionalContentEntry(string $key, $default = null)
 502     {
 503         return array_key_exists($key, $this->additionalContent) ? $this->additionalContent[$key] : $default;
 504     }
 505
 506     /**
 507      * Rename a tag in tags list.
 508      *
 509      * @param string $fromTag
 510      * @param string $toTag
 511      */
 512     public function renameTag(string $fromTag, string $toTag): void
 513     {
 514         if (($pos = array_search($fromTag, $this->tags ?? [])) !== false) {
 515             $this->tags[$pos] = trim($toTag);
 516         }
 517     }
 518
 519     /**
 520      * Delete a tag from tags list.
 521      *
 522      * @param string $tag
 523      */
 524     public function deleteTag(string $tag): void
 525     {
 526         if (($pos = array_search($tag, $this->tags ?? [])) !== false) {
 527             unset($this->tags[$pos]);
 528             $this->tags = array_values($this->tags);
 529         }
 530     }
 531 }