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 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.
67 public function fromArray(array $data): Bookmark
69 $this->id
= $data['id'] ?? null;
70 $this->shortUrl
= $data['shorturl'] ?? null;
71 $this->url
= $data['url'] ?? null;
72 $this->title
= $data['title'] ?? null;
73 $this->description
= $data['description'] ?? null;
74 $this->thumbnail
= $data['thumbnail'] ?? null;
75 $this->sticky
= $data['sticky'] ?? false;
76 $this->created
= $data['created'] ?? null;
77 if (is_array($data['tags'])) {
78 $this->tags
= $data['tags'];
80 $this->tags
= preg_split('/\s+/', $data['tags'] ?? '', -1, PREG_SPLIT_NO_EMPTY
);
82 if (! empty($data['updated'])) {
83 $this->updated
= $data['updated'];
85 $this->private = ($data['private'] ?? false) ? true : false;
91 * Make sure that the current instance of Bookmark is valid and can be saved into the data store.
92 * A valid link requires:
94 * - a short URL (for permalinks)
97 * This function also initialize optional empty fields:
98 * - the URL with the permalink
99 * - the title with the URL
101 * Also make sure that we do not save search highlights in the datastore.
103 * @throws InvalidBookmarkException
105 public function validate(): void
107 if ($this->id
=== null
108 || ! is_int($this->id
)
109 || empty($this->shortUrl
)
110 || empty($this->created
)
112 throw new InvalidBookmarkException($this);
114 if (empty($this->url
)) {
115 $this->url
= '/shaare/'. $this->shortUrl
;
117 if (empty($this->title
)) {
118 $this->title
= $this->url
;
120 if (array_key_exists('search_highlight', $this->additionalContent
)) {
121 unset($this->additionalContent
['search_highlight']);
127 * If they're not already initialized, this function also set:
128 * - created: with the current datetime
129 * - shortUrl: with a generated small hash from the date and the given ID
131 * @param int|null $id
135 public function setId(?int $id): Bookmark
138 if (empty($this->created
)) {
139 $this->created
= new DateTime();
141 if (empty($this->shortUrl
)) {
142 $this->shortUrl
= link_small_hash($this->created
, $this->id
);
153 public function getId(): ?int
161 * @return string|null
163 public function getShortUrl(): ?string
165 return $this->shortUrl
;
171 * @return string|null
173 public function getUrl(): ?string
183 public function getTitle(): ?string
189 * Get the Description.
193 public function getDescription(): string
195 return ! empty($this->description
) ? $this->description
: '';
201 * @return DateTimeInterface
203 public function getCreated(): ?DateTimeInterface
205 return $this->created
;
211 * @return DateTimeInterface
213 public function getUpdated(): ?DateTimeInterface
215 return $this->updated
;
221 * @param string|null $shortUrl
225 public function setShortUrl(?string $shortUrl): Bookmark
227 $this->shortUrl
= $shortUrl;
235 * @param string|null $url
236 * @param string[] $allowedProtocols
240 public function setUrl(?string $url, array $allowedProtocols = []): Bookmark
242 $url = $url !== null ? trim($url) : '';
244 $url = whitelist_protocols($url, $allowedProtocols);
254 * @param string|null $title
258 public function setTitle(?string $title): Bookmark
260 $this->title
= $title !== null ? trim($title) : '';
266 * Set the Description.
268 * @param string|null $description
272 public function setDescription(?string $description): Bookmark
274 $this->description
= $description;
281 * Note: you shouldn't set this manually except for special cases (like bookmark import)
283 * @param DateTimeInterface|null $created
287 public function setCreated(?DateTimeInterface
$created): Bookmark
289 $this->created
= $created;
297 * @param DateTimeInterface|null $updated
301 public function setUpdated(?DateTimeInterface
$updated): Bookmark
303 $this->updated
= $updated;
313 public function isPrivate(): bool
315 return $this->private ? true : false;
321 * @param bool|null $private
325 public function setPrivate(?bool $private): Bookmark
327 $this->private = $private ? true : false;
337 public function getTags(): array
339 return is_array($this->tags
) ? $this->tags
: [];
345 * @param string[]|null $tags
349 public function setTags(?array $tags): Bookmark
351 $this->setTagsString(implode(' ', $tags ?? []));
359 * @return string|bool|null Thumbnail's URL - initialized at null, false if no thumbnail could be found
361 public function getThumbnail()
363 return !$this->isNote() ? $this->thumbnail
: false;
369 * @param string|bool|null $thumbnail Thumbnail's URL - false if no thumbnail could be found
373 public function setThumbnail($thumbnail): Bookmark
375 $this->thumbnail
= $thumbnail;
382 * - the bookmark's thumbnail is not already set to false (= not found)
384 * - it's an HTTP(S) link
385 * - the thumbnail has not yet be retrieved (null) or its associated cache file doesn't exist anymore
387 * @return bool True if the bookmark's thumbnail needs to be retrieved.
389 public function shouldUpdateThumbnail(): bool
391 return $this->thumbnail
!== false
393 && startsWith(strtolower($this->url
), 'http')
394 && (null === $this->thumbnail
|| !is_file($this->thumbnail
))
403 public function isSticky(): bool
405 return $this->sticky
? true : false;
411 * @param bool|null $sticky
415 public function setSticky(?bool $sticky): Bookmark
417 $this->sticky
= $sticky ? true : false;
423 * @return string Bookmark's tags as a string, separated by a space
425 public function getTagsString(): string
427 return implode(' ', $this->getTags());
433 public function isNote(): bool
435 // We check empty value to get a valid result if the link has not been saved yet
436 return empty($this->url
) || startsWith($this->url
, '/shaare/') || $this->url
[0] === '?';
440 * Set tags from a string.
442 * - tags must be separated whether by a space or a comma
443 * - multiple spaces will be removed
444 * - trailing dash in tags will be removed
446 * @param string|null $tags
450 public function setTagsString(?string $tags): Bookmark
452 // Remove first '-' char in tags.
453 $tags = preg_replace('/(^| )\-/', '$1', $tags ?? '');
454 // Explode all tags separted by spaces or commas
455 $tags = preg_split('/[\s
,]+
/', $tags);
456 // Remove eventual empty values
457 $tags = array_values(array_filter($tags));
465 * Get entire additionalContent array.
469 public function getAdditionalContent(): array
471 return $this->additionalContent;
475 * Set a single entry in additionalContent, by key.
478 * @param mixed|null $value Any type of value can be set.
482 public function addAdditionalContentEntry(string $key, $value): self
484 $this->additionalContent[$key] = $value;
490 * Get a single entry in additionalContent, by key.
493 * @param mixed|null $default
495 * @return mixed|null can be any type or even null.
497 public function getAdditionalContentEntry(string $key, $default = null)
499 return array_key_exists($key, $this->additionalContent) ? $this->additionalContent[$key] : $default;
503 * Rename a tag in tags list.
505 * @param string $fromTag
506 * @param string $toTag
508 public function renameTag(string $fromTag, string $toTag): void
510 if (($pos = array_search($fromTag, $this->tags)) !== false) {
511 $this->tags[$pos] = trim($toTag);
516 * Delete a tag from tags list.
520 public function deleteTag(string $tag): void
522 if (($pos = array_search($tag, $this->tags)) !== false) {
523 unset($this->tags[$pos]);
524 $this->tags = array_values($this->tags);