3 namespace Shaarli\Formatter
;
6 use Shaarli\Bookmark\Bookmark
;
7 use Shaarli\Config\ConfigManager
;
10 * Class BookmarkFormatter
12 * Abstract class processing all bookmark attributes through methods designed to be overridden.
14 * List of available formatted fields:
16 * - shorturl Unique identifier, used in permalinks
17 * - url URL, can be altered in some way, e.g. passing through an HTTP reverse proxy
18 * - real_url (legacy) same as `url`
19 * - url_html URL to be displayed in HTML content (it can contain HTML tags)
21 * - title_html Title to be displayed in HTML content (it can contain HTML tags)
22 * - description Description content. It most likely contains HTML tags
23 * - thumbnail Thumbnail: path to local cache file, false if there is none, null if hasn't been retrieved
24 * - taglist List of tags (array)
25 * - taglist_urlencoded List of tags (array) URL encoded: it must be used to create a link to a URL containing a tag
26 * - taglist_html List of tags (array) to be displayed in HTML content (it can contain HTML tags)
27 * - tags Tags separated by a single whitespace
28 * - tags_urlencoded Tags separated by a single whitespace, URL encoded: must be used to create a link
29 * - sticky Is sticky (bool)
30 * - private Is private (bool)
31 * - class Additional CSS class
32 * - created Creation DateTime
33 * - updated Last edit DateTime
34 * - timestamp Creation timestamp
35 * - updated_timestamp Last edit timestamp
37 * @package Shaarli\Formatter
39 abstract class BookmarkFormatter
47 protected $isLoggedIn;
50 * @var array Additional parameters than can be used for specific formatting
51 * e.g. index_url for Feed formatting
53 protected $contextData = [];
56 * LinkDefaultFormatter constructor.
57 * @param ConfigManager $conf
59 public function __construct(ConfigManager
$conf, bool $isLoggedIn)
62 $this->isLoggedIn
= $isLoggedIn;
66 * Convert a Bookmark into an array usable by templates and plugins.
68 * All Bookmark attributes are formatted through a format method
69 * that can be overridden in a formatter extending this class.
71 * @param Bookmark $bookmark instance
73 * @return array formatted representation of a Bookmark
75 public function format($bookmark)
77 $out['id'] = $this->formatId($bookmark);
78 $out['shorturl'] = $this->formatShortUrl($bookmark);
79 $out['url'] = $this->formatUrl($bookmark);
80 $out['real_url'] = $this->formatRealUrl($bookmark);
81 $out['url_html'] = $this->formatUrlHtml($bookmark);
82 $out['title'] = $this->formatTitle($bookmark);
83 $out['title_html'] = $this->formatTitleHtml($bookmark);
84 $out['description'] = $this->formatDescription($bookmark);
85 $out['thumbnail'] = $this->formatThumbnail($bookmark);
86 $out['taglist'] = $this->formatTagList($bookmark);
87 $out['taglist_urlencoded'] = $this->formatTagListUrlEncoded($bookmark);
88 $out['taglist_html'] = $this->formatTagListHtml($bookmark);
89 $out['tags'] = $this->formatTagString($bookmark);
90 $out['tags_urlencoded'] = $this->formatTagStringUrlEncoded($bookmark);
91 $out['sticky'] = $bookmark->isSticky();
92 $out['private'] = $bookmark->isPrivate();
93 $out['class'] = $this->formatClass($bookmark);
94 $out['created'] = $this->formatCreated($bookmark);
95 $out['updated'] = $this->formatUpdated($bookmark);
96 $out['timestamp'] = $this->formatCreatedTimestamp($bookmark);
97 $out['updated_timestamp'] = $this->formatUpdatedTimestamp($bookmark);
103 * Add additional data available to formatters.
104 * This is used for example to add `index_url` in description's links.
106 * @param string $key Context data key
107 * @param string $value Context data value
109 public function addContextData($key, $value)
111 $this->contextData
[$key] = $value;
119 * @param Bookmark $bookmark instance
121 * @return int formatted ID
123 protected function formatId($bookmark)
125 return $bookmark->getId();
131 * @param Bookmark $bookmark instance
133 * @return string formatted ShortUrl
135 protected function formatShortUrl($bookmark)
137 return $bookmark->getShortUrl();
143 * @param Bookmark $bookmark instance
145 * @return string formatted Url
147 protected function formatUrl($bookmark)
149 return $bookmark->getUrl();
154 * Legacy: identical to Url
156 * @param Bookmark $bookmark instance
158 * @return string formatted RealUrl
160 protected function formatRealUrl($bookmark)
162 return $this->formatUrl($bookmark);
166 * Format Url Html: to be displayed in HTML content, it can contains HTML tags.
168 * @param Bookmark $bookmark instance
170 * @return string formatted Url HTML
172 protected function formatUrlHtml($bookmark)
174 return $this->formatUrl($bookmark);
180 * @param Bookmark $bookmark instance
182 * @return string formatted Title
184 protected function formatTitle($bookmark)
186 return $bookmark->getTitle();
190 * Format Title HTML: to be displayed in HTML content, it can contains HTML tags.
192 * @param Bookmark $bookmark instance
194 * @return string formatted Title
196 protected function formatTitleHtml($bookmark)
198 return $bookmark->getTitle();
204 * @param Bookmark $bookmark instance
206 * @return string formatted Description
208 protected function formatDescription($bookmark)
210 return $bookmark->getDescription();
216 * @param Bookmark $bookmark instance
218 * @return string formatted Thumbnail
220 protected function formatThumbnail($bookmark)
222 return $bookmark->getThumbnail();
228 * @param Bookmark $bookmark instance
230 * @return array formatted Tags
232 protected function formatTagList($bookmark)
234 return $this->filterTagList($bookmark->getTags());
238 * Format Url Encoded Tags
240 * @param Bookmark $bookmark instance
242 * @return array formatted Tags
244 protected function formatTagListUrlEncoded($bookmark)
246 return array_map('urlencode', $this->filterTagList($bookmark->getTags()));
250 * Format Tags HTML: to be displayed in HTML content, it can contains HTML tags.
252 * @param Bookmark $bookmark instance
254 * @return array formatted Tags
256 protected function formatTagListHtml($bookmark)
258 return $this->formatTagList($bookmark);
264 * @param Bookmark $bookmark instance
266 * @return string formatted TagString
268 protected function formatTagString($bookmark)
270 return implode($this->conf
->get('general.tags_separator', ' '), $this->formatTagList($bookmark));
276 * @param Bookmark $bookmark instance
278 * @return string formatted TagString
280 protected function formatTagStringUrlEncoded($bookmark)
282 return implode(' ', $this->formatTagListUrlEncoded($bookmark));
287 * Used to add specific CSS class for a link
289 * @param Bookmark $bookmark instance
291 * @return string formatted Class
293 protected function formatClass($bookmark)
295 return $bookmark->isPrivate() ? 'private' : '';
301 * @param Bookmark $bookmark instance
303 * @return DateTimeInterface instance
305 protected function formatCreated(Bookmark
$bookmark)
307 return $bookmark->getCreated();
313 * @param Bookmark $bookmark instance
315 * @return DateTimeInterface instance
317 protected function formatUpdated(Bookmark
$bookmark)
319 return $bookmark->getUpdated();
323 * Format CreatedTimestamp
325 * @param Bookmark $bookmark instance
327 * @return int formatted CreatedTimestamp
329 protected function formatCreatedTimestamp(Bookmark
$bookmark)
331 if (! empty($bookmark->getCreated())) {
332 return $bookmark->getCreated()->getTimestamp();
338 * Format UpdatedTimestamp
340 * @param Bookmark $bookmark instance
342 * @return int formatted UpdatedTimestamp
344 protected function formatUpdatedTimestamp(Bookmark
$bookmark)
346 if (! empty($bookmark->getUpdated())) {
347 return $bookmark->getUpdated()->getTimestamp();
353 * Format tag list, e.g. remove private tags if the user is not logged in.
354 * TODO: this method is called multiple time to format tags, the result should be cached.
360 protected function filterTagList(array $tags): array
362 if ($this->isLoggedIn
=== true) {
367 foreach ($tags as $tag) {
368 if (strpos($tag, '.') === 0) {