3 declare(strict_types
=1);
5 namespace Shaarli\Bookmark
;
9 use Shaarli\Bookmark\Exception\InvalidBookmarkException
;
14 * This class represent a single Bookmark with all its attributes.
15 * Every bookmark should manipulated using this, before being formatted.
17 * @package Shaarli\Bookmark
21 /** @var string Date format used in string (former ID format) */
22 public const LINK_DATE_FORMAT
= 'Ymd_His';
24 /** @var int Bookmark ID */
27 /** @var string Permalink identifier */
30 /** @var string Bookmark's URL - $shortUrl prefixed with `?` for notes */
33 /** @var string Bookmark's title */
36 /** @var string Raw bookmark's description */
37 protected $description;
39 /** @var array List of bookmark's tags */
42 /** @var string|bool|null Thumbnail's URL - initialized at null, false if no thumbnail could be found */
45 /** @var bool Set to true if the bookmark is set as sticky */
48 /** @var DateTimeInterface Creation datetime */
51 /** @var DateTimeInterface datetime */
54 /** @var bool True if the bookmark can only be seen while logged in */
57 /** @var mixed[] Available to store any additional content for a bookmark. Currently used for search highlight. */
58 protected $additionalContent = [];
61 * Initialize a link from array data. Especially useful to create a Bookmark from former link storage format.
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.
69 public function fromArray(array $data, string $tagsSeparator = ' '): Bookmark
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'];
82 $this->tags
= tags_str2array($data['tags'] ?? '', $tagsSeparator);
84 if (! empty($data['updated'])) {
85 $this->updated
= $data['updated'];
87 $this->private = ($data['private'] ?? false) ? true : false;
93 * Make sure that the current instance of Bookmark is valid and can be saved into the data store.
94 * A valid link requires:
96 * - a short URL (for permalinks)
99 * This function also initialize optional empty fields:
100 * - the URL with the permalink
101 * - the title with the URL
103 * Also make sure that we do not save search highlights in the datastore.
105 * @throws InvalidBookmarkException
107 public function validate(): void
111 || ! is_int($this->id
)
112 || empty($this->shortUrl
)
113 || empty($this->created
)
115 throw new InvalidBookmarkException($this);
117 if (empty($this->url
)) {
118 $this->url
= '/shaare/' . $this->shortUrl
;
120 if (empty($this->title
)) {
121 $this->title
= $this->url
;
123 if (array_key_exists('search_highlight', $this->additionalContent
)) {
124 unset($this->additionalContent
['search_highlight']);
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
134 * @param int|null $id
138 public function setId(?int $id): Bookmark
141 if (empty($this->created
)) {
142 $this->created
= new DateTime();
144 if (empty($this->shortUrl
)) {
145 $this->shortUrl
= link_small_hash($this->created
, $this->id
);
156 public function getId(): ?int
164 * @return string|null
166 public function getShortUrl(): ?string
168 return $this->shortUrl
;
174 * @return string|null
176 public function getUrl(): ?string
186 public function getTitle(): ?string
192 * Get the Description.
196 public function getDescription(): string
198 return ! empty($this->description
) ? $this->description
: '';
204 * @return DateTimeInterface
206 public function getCreated(): ?DateTimeInterface
208 return $this->created
;
214 * @return DateTimeInterface
216 public function getUpdated(): ?DateTimeInterface
218 return $this->updated
;
224 * @param string|null $shortUrl
228 public function setShortUrl(?string $shortUrl): Bookmark
230 $this->shortUrl
= $shortUrl;
238 * @param string|null $url
239 * @param string[] $allowedProtocols
243 public function setUrl(?string $url, array $allowedProtocols = []): Bookmark
245 $url = $url !== null ? trim($url) : '';
247 $url = whitelist_protocols($url, $allowedProtocols);
257 * @param string|null $title
261 public function setTitle(?string $title): Bookmark
263 $this->title
= $title !== null ? trim($title) : '';
269 * Set the Description.
271 * @param string|null $description
275 public function setDescription(?string $description): Bookmark
277 $this->description
= $description;
284 * Note: you shouldn't set this manually except for special cases (like bookmark import)
286 * @param DateTimeInterface|null $created
290 public function setCreated(?DateTimeInterface
$created): Bookmark
292 $this->created
= $created;
300 * @param DateTimeInterface|null $updated
304 public function setUpdated(?DateTimeInterface
$updated): Bookmark
306 $this->updated
= $updated;
316 public function isPrivate(): bool
318 return $this->private ? true : false;
324 * @param bool|null $private
328 public function setPrivate(?bool $private): Bookmark
330 $this->private = $private ? true : false;
340 public function getTags(): array
342 return is_array($this->tags
) ? $this->tags
: [];
348 * @param string[]|null $tags
352 public function setTags(?array $tags): Bookmark
354 $this->tags
= array_map(
355 function (string $tag): string {
356 return $tag[0] === '-' ? substr($tag, 1) : $tag;
358 tags_filter($tags, ' ')
367 * @return string|bool|null Thumbnail's URL - initialized at null, false if no thumbnail could be found
369 public function getThumbnail()
371 return !$this->isNote() ? $this->thumbnail
: false;
377 * @param string|bool|null $thumbnail Thumbnail's URL - false if no thumbnail could be found
381 public function setThumbnail($thumbnail): Bookmark
383 $this->thumbnail
= $thumbnail;
390 * - the bookmark's thumbnail is not already set to false (= not found)
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
395 * @return bool True if the bookmark's thumbnail needs to be retrieved.
397 public function shouldUpdateThumbnail(): bool
399 return $this->thumbnail
!== false
401 && startsWith(strtolower($this->url
), 'http')
402 && (null === $this->thumbnail
|| !is_file($this->thumbnail
))
411 public function isSticky(): bool
413 return $this->sticky
? true : false;
419 * @param bool|null $sticky
423 public function setSticky(?bool $sticky): Bookmark
425 $this->sticky
= $sticky ? true : false;
431 * @param string $separator Tags separator loaded from the config file.
433 * @return string Bookmark's tags as a string, separated by a separator
435 public function getTagsString(string $separator = ' '): string
437 return tags_array2str($this->getTags(), $separator);
443 public function isNote(): bool
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] === '?';
450 * Set tags from a string.
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
456 * @param string|null $tags
457 * @param string $separator Tags separator loaded from the config file.
461 public function setTagsString(?string $tags, string $separator = ' '): Bookmark
463 $this->setTags(tags_str2array($tags, $separator));
469 * Get entire additionalContent array.
473 public function getAdditionalContent(): array
475 return $this->additionalContent
;
479 * Set a single entry in additionalContent, by key.
482 * @param mixed|null $value Any type of value can be set.
486 public function addAdditionalContentEntry(string $key, $value): self
488 $this->additionalContent
[$key] = $value;
494 * Get a single entry in additionalContent, by key.
497 * @param mixed|null $default
499 * @return mixed|null can be any type or even null.
501 public function getAdditionalContentEntry(string $key, $default = null)
503 return array_key_exists($key, $this->additionalContent
) ? $this->additionalContent
[$key] : $default;
507 * Rename a tag in tags list.
509 * @param string $fromTag
510 * @param string $toTag
512 public function renameTag(string $fromTag, string $toTag): void
514 if (($pos = array_search($fromTag, $this->tags
?? [])) !== false) {
515 $this->tags
[$pos] = trim($toTag);
520 * Delete a tag from tags list.
524 public function deleteTag(string $tag): void
526 if (($pos = array_search($tag, $this->tags
?? [])) !== false) {
527 unset($this->tags
[$pos]);
528 $this->tags
= array_values($this->tags
);