]>
Commit | Line | Data |
---|---|---|
1 | <?php | |
2 | ||
3 | declare(strict_types=1); | |
4 | ||
5 | namespace Shaarli\Bookmark; | |
6 | ||
7 | use Shaarli\Bookmark\Exception\BookmarkNotFoundException; | |
8 | use Shaarli\Bookmark\Exception\NotWritableDataStoreException; | |
9 | ||
10 | /** | |
11 | * Class BookmarksService | |
12 | * | |
13 | * This is the entry point to manipulate the bookmark DB. | |
14 | * | |
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. | |
17 | */ | |
18 | interface BookmarkServiceInterface | |
19 | { | |
20 | /** | |
21 | * Find a bookmark by hash | |
22 | * | |
23 | * @param string $hash | |
24 | * | |
25 | * @return Bookmark | |
26 | * | |
27 | * @throws \Exception | |
28 | */ | |
29 | public function findByHash(string $hash): Bookmark; | |
30 | ||
31 | /** | |
32 | * @param $url | |
33 | * | |
34 | * @return Bookmark|null | |
35 | */ | |
36 | public function findByUrl(string $url): ?Bookmark; | |
37 | ||
38 | /** | |
39 | * Search bookmarks | |
40 | * | |
41 | * @param array $request | |
42 | * @param ?string $visibility | |
43 | * @param bool $caseSensitive | |
44 | * @param bool $untaggedOnly | |
45 | * @param bool $ignoreSticky | |
46 | * | |
47 | * @return Bookmark[] | |
48 | */ | |
49 | public function search( | |
50 | array $request = [], | |
51 | string $visibility = null, | |
52 | bool $caseSensitive = false, | |
53 | bool $untaggedOnly = false, | |
54 | bool $ignoreSticky = false | |
55 | ); | |
56 | ||
57 | /** | |
58 | * Get a single bookmark by its ID. | |
59 | * | |
60 | * @param int $id Bookmark ID | |
61 | * @param ?string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an | |
62 | * exception | |
63 | * | |
64 | * @return Bookmark | |
65 | * | |
66 | * @throws BookmarkNotFoundException | |
67 | * @throws \Exception | |
68 | */ | |
69 | public function get(int $id, string $visibility = null); | |
70 | ||
71 | /** | |
72 | * Updates an existing bookmark (depending on its ID). | |
73 | * | |
74 | * @param Bookmark $bookmark | |
75 | * @param bool $save Writes to the datastore if set to true | |
76 | * | |
77 | * @return Bookmark Updated bookmark | |
78 | * | |
79 | * @throws BookmarkNotFoundException | |
80 | * @throws \Exception | |
81 | */ | |
82 | public function set(Bookmark $bookmark, bool $save = true): Bookmark; | |
83 | ||
84 | /** | |
85 | * Adds a new bookmark (the ID must be empty). | |
86 | * | |
87 | * @param Bookmark $bookmark | |
88 | * @param bool $save Writes to the datastore if set to true | |
89 | * | |
90 | * @return Bookmark new bookmark | |
91 | * | |
92 | * @throws \Exception | |
93 | */ | |
94 | public function add(Bookmark $bookmark, bool $save = true): Bookmark; | |
95 | ||
96 | /** | |
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 | |
100 | * | |
101 | * @param Bookmark $bookmark | |
102 | * @param bool $save | |
103 | * | |
104 | * @return Bookmark | |
105 | * | |
106 | * @throws \Exception | |
107 | */ | |
108 | public function addOrSet(Bookmark $bookmark, bool $save = true): Bookmark; | |
109 | ||
110 | /** | |
111 | * Deletes a bookmark. | |
112 | * | |
113 | * @param Bookmark $bookmark | |
114 | * @param bool $save | |
115 | * | |
116 | * @throws \Exception | |
117 | */ | |
118 | public function remove(Bookmark $bookmark, bool $save = true): void; | |
119 | ||
120 | /** | |
121 | * Get a single bookmark by its ID. | |
122 | * | |
123 | * @param int $id Bookmark ID | |
124 | * @param ?string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an | |
125 | * exception | |
126 | * | |
127 | * @return bool | |
128 | */ | |
129 | public function exists(int $id, string $visibility = null): bool; | |
130 | ||
131 | /** | |
132 | * Return the number of available bookmarks for given visibility. | |
133 | * | |
134 | * @param ?string $visibility public|private|all | |
135 | * | |
136 | * @return int Number of bookmarks | |
137 | */ | |
138 | public function count(string $visibility = null): int; | |
139 | ||
140 | /** | |
141 | * Write the datastore. | |
142 | * | |
143 | * @throws NotWritableDataStoreException | |
144 | */ | |
145 | public function save(): void; | |
146 | ||
147 | /** | |
148 | * Returns the list tags appearing in the bookmarks with the given tags | |
149 | * | |
150 | * @param array|null $filteringTags tags selecting the bookmarks to consider | |
151 | * @param string|null $visibility process only all/private/public bookmarks | |
152 | * | |
153 | * @return array tag => bookmarksCount | |
154 | */ | |
155 | public function bookmarksCountPerTag(array $filteringTags = [], ?string $visibility = null): array; | |
156 | ||
157 | /** | |
158 | * Returns the list of days containing articles (oldest first) | |
159 | * | |
160 | * @return array containing days (in format YYYYMMDD). | |
161 | */ | |
162 | public function days(): array; | |
163 | ||
164 | /** | |
165 | * Returns the list of articles for a given day. | |
166 | * | |
167 | * @param string $request day to filter. Format: YYYYMMDD. | |
168 | * | |
169 | * @return Bookmark[] list of shaare found. | |
170 | * | |
171 | * @throws BookmarkNotFoundException | |
172 | */ | |
173 | public function filterDay(string $request); | |
174 | ||
175 | /** | |
176 | * Creates the default database after a fresh install. | |
177 | */ | |
178 | public function initialize(): void; | |
179 | } |