3 declare(strict_types
=1);
5 namespace Shaarli\Bookmark
;
7 use Shaarli\Bookmark\Exception\BookmarkNotFoundException
;
8 use Shaarli\Bookmark\Exception\NotWritableDataStoreException
;
11 * Class BookmarksService
13 * This is the entry point to manipulate the bookmark DB.
15 * Regarding return types of a list of bookmarks, it can either be an array or an ArrayAccess implementation,
16 * so until PHP 8.0 is the minimal supported version with union return types it cannot be explicitly added.
18 interface BookmarkServiceInterface
21 * Find a bookmark by hash
29 public function findByHash(string $hash): Bookmark
;
34 * @return Bookmark|null
36 public function findByUrl(string $url): ?Bookmark
;
41 * @param array $request
42 * @param ?string $visibility
43 * @param bool $caseSensitive
44 * @param bool $untaggedOnly
45 * @param bool $ignoreSticky
49 public function search(
51 string $visibility = null,
52 bool $caseSensitive = false,
53 bool $untaggedOnly = false,
54 bool $ignoreSticky = false
58 * Get a single bookmark by its ID.
60 * @param int $id Bookmark ID
61 * @param ?string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an
66 * @throws BookmarkNotFoundException
69 public function get(int $id, string $visibility = null);
72 * Updates an existing bookmark (depending on its ID).
74 * @param Bookmark $bookmark
75 * @param bool $save Writes to the datastore if set to true
77 * @return Bookmark Updated bookmark
79 * @throws BookmarkNotFoundException
82 public function set(Bookmark
$bookmark, bool $save = true): Bookmark
;
85 * Adds a new bookmark (the ID must be empty).
87 * @param Bookmark $bookmark
88 * @param bool $save Writes to the datastore if set to true
90 * @return Bookmark new bookmark
94 public function add(Bookmark
$bookmark, bool $save = true): Bookmark
;
97 * Adds or updates a bookmark depending on its ID:
98 * - a Bookmark without ID will be added
99 * - a Bookmark with an existing ID will be updated
101 * @param Bookmark $bookmark
108 public function addOrSet(Bookmark
$bookmark, bool $save = true): Bookmark
;
111 * Deletes a bookmark.
113 * @param Bookmark $bookmark
118 public function remove(Bookmark
$bookmark, bool $save = true): void;
121 * Get a single bookmark by its ID.
123 * @param int $id Bookmark ID
124 * @param ?string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an
129 public function exists(int $id, string $visibility = null): bool;
132 * Return the number of available bookmarks for given visibility.
134 * @param ?string $visibility public|private|all
136 * @return int Number of bookmarks
138 public function count(string $visibility = null): int;
141 * Write the datastore.
143 * @throws NotWritableDataStoreException
145 public function save(): void;
148 * Returns the list tags appearing in the bookmarks with the given tags
150 * @param array|null $filteringTags tags selecting the bookmarks to consider
151 * @param string|null $visibility process only all/private/public bookmarks
153 * @return array tag => bookmarksCount
155 public function bookmarksCountPerTag(array $filteringTags = [], ?string $visibility = null): array;
158 * Returns the list of days containing articles (oldest first)
160 * @return array containing days (in format YYYYMMDD).
162 public function days(): array;
165 * Returns the list of articles for a given day.
167 * @param string $request day to filter. Format: YYYYMMDD.
169 * @return Bookmark[] list of shaare found.
171 * @throws BookmarkNotFoundException
173 public function filterDay(string $request);
176 * Creates the default database after a fresh install.
178 public function initialize(): void;