diff options
Diffstat (limited to 'application/bookmark/BookmarkServiceInterface.php')
-rw-r--r-- | application/bookmark/BookmarkServiceInterface.php | 109 |
1 files changed, 58 insertions, 51 deletions
diff --git a/application/bookmark/BookmarkServiceInterface.php b/application/bookmark/BookmarkServiceInterface.php index 7b7a4f09..08cdbb4e 100644 --- a/application/bookmark/BookmarkServiceInterface.php +++ b/application/bookmark/BookmarkServiceInterface.php | |||
@@ -1,73 +1,73 @@ | |||
1 | <?php | 1 | <?php |
2 | 2 | ||
3 | namespace Shaarli\Bookmark; | 3 | declare(strict_types=1); |
4 | 4 | ||
5 | namespace Shaarli\Bookmark; | ||
5 | 6 | ||
6 | use Shaarli\Bookmark\Exception\BookmarkNotFoundException; | 7 | use Shaarli\Bookmark\Exception\BookmarkNotFoundException; |
7 | use Shaarli\Bookmark\Exception\NotWritableDataStoreException; | 8 | use Shaarli\Bookmark\Exception\NotWritableDataStoreException; |
8 | use Shaarli\Config\ConfigManager; | ||
9 | use Shaarli\Exceptions\IOException; | ||
10 | use Shaarli\History; | ||
11 | 9 | ||
12 | /** | 10 | /** |
13 | * Class BookmarksService | 11 | * Class BookmarksService |
14 | * | 12 | * |
15 | * This is the entry point to manipulate the bookmark DB. | 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. | ||
16 | */ | 17 | */ |
17 | interface BookmarkServiceInterface | 18 | interface BookmarkServiceInterface |
18 | { | 19 | { |
19 | /** | 20 | /** |
20 | * BookmarksService constructor. | ||
21 | * | ||
22 | * @param ConfigManager $conf instance | ||
23 | * @param History $history instance | ||
24 | * @param bool $isLoggedIn true if the current user is logged in | ||
25 | */ | ||
26 | public function __construct(ConfigManager $conf, History $history, $isLoggedIn); | ||
27 | |||
28 | /** | ||
29 | * Find a bookmark by hash | 21 | * Find a bookmark by hash |
30 | * | 22 | * |
31 | * @param string $hash | 23 | * @param string $hash Bookmark's hash |
24 | * @param string|null $privateKey Optional key used to access private links while logged out | ||
32 | * | 25 | * |
33 | * @return mixed | 26 | * @return Bookmark |
34 | * | 27 | * |
35 | * @throws \Exception | 28 | * @throws \Exception |
36 | */ | 29 | */ |
37 | public function findByHash($hash); | 30 | public function findByHash(string $hash, string $privateKey = null); |
38 | 31 | ||
39 | /** | 32 | /** |
40 | * @param $url | 33 | * @param $url |
41 | * | 34 | * |
42 | * @return Bookmark|null | 35 | * @return Bookmark|null |
43 | */ | 36 | */ |
44 | public function findByUrl($url); | 37 | public function findByUrl(string $url): ?Bookmark; |
45 | 38 | ||
46 | /** | 39 | /** |
47 | * Search bookmarks | 40 | * Search bookmarks |
48 | * | 41 | * |
49 | * @param mixed $request | 42 | * @param array $request |
50 | * @param string $visibility | 43 | * @param ?string $visibility |
51 | * @param bool $caseSensitive | 44 | * @param bool $caseSensitive |
52 | * @param bool $untaggedOnly | 45 | * @param bool $untaggedOnly |
46 | * @param bool $ignoreSticky | ||
53 | * | 47 | * |
54 | * @return Bookmark[] | 48 | * @return Bookmark[] |
55 | */ | 49 | */ |
56 | public function search($request = [], $visibility = null, $caseSensitive = false, $untaggedOnly = false); | 50 | public function search( |
51 | array $request = [], | ||
52 | string $visibility = null, | ||
53 | bool $caseSensitive = false, | ||
54 | bool $untaggedOnly = false, | ||
55 | bool $ignoreSticky = false | ||
56 | ); | ||
57 | 57 | ||
58 | /** | 58 | /** |
59 | * Get a single bookmark by its ID. | 59 | * Get a single bookmark by its ID. |
60 | * | 60 | * |
61 | * @param int $id Bookmark ID | 61 | * @param int $id Bookmark ID |
62 | * @param string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an | 62 | * @param ?string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an |
63 | * exception | 63 | * exception |
64 | * | 64 | * |
65 | * @return Bookmark | 65 | * @return Bookmark |
66 | * | 66 | * |
67 | * @throws BookmarkNotFoundException | 67 | * @throws BookmarkNotFoundException |
68 | * @throws \Exception | 68 | * @throws \Exception |
69 | */ | 69 | */ |
70 | public function get($id, $visibility = null); | 70 | public function get(int $id, string $visibility = null); |
71 | 71 | ||
72 | /** | 72 | /** |
73 | * Updates an existing bookmark (depending on its ID). | 73 | * Updates an existing bookmark (depending on its ID). |
@@ -80,7 +80,7 @@ interface BookmarkServiceInterface | |||
80 | * @throws BookmarkNotFoundException | 80 | * @throws BookmarkNotFoundException |
81 | * @throws \Exception | 81 | * @throws \Exception |
82 | */ | 82 | */ |
83 | public function set($bookmark, $save = true); | 83 | public function set(Bookmark $bookmark, bool $save = true): Bookmark; |
84 | 84 | ||
85 | /** | 85 | /** |
86 | * Adds a new bookmark (the ID must be empty). | 86 | * Adds a new bookmark (the ID must be empty). |
@@ -92,7 +92,7 @@ interface BookmarkServiceInterface | |||
92 | * | 92 | * |
93 | * @throws \Exception | 93 | * @throws \Exception |
94 | */ | 94 | */ |
95 | public function add($bookmark, $save = true); | 95 | public function add(Bookmark $bookmark, bool $save = true): Bookmark; |
96 | 96 | ||
97 | /** | 97 | /** |
98 | * Adds or updates a bookmark depending on its ID: | 98 | * Adds or updates a bookmark depending on its ID: |
@@ -106,7 +106,7 @@ interface BookmarkServiceInterface | |||
106 | * | 106 | * |
107 | * @throws \Exception | 107 | * @throws \Exception |
108 | */ | 108 | */ |
109 | public function addOrSet($bookmark, $save = true); | 109 | public function addOrSet(Bookmark $bookmark, bool $save = true): Bookmark; |
110 | 110 | ||
111 | /** | 111 | /** |
112 | * Deletes a bookmark. | 112 | * Deletes a bookmark. |
@@ -116,65 +116,72 @@ interface BookmarkServiceInterface | |||
116 | * | 116 | * |
117 | * @throws \Exception | 117 | * @throws \Exception |
118 | */ | 118 | */ |
119 | public function remove($bookmark, $save = true); | 119 | public function remove(Bookmark $bookmark, bool $save = true): void; |
120 | 120 | ||
121 | /** | 121 | /** |
122 | * Get a single bookmark by its ID. | 122 | * Get a single bookmark by its ID. |
123 | * | 123 | * |
124 | * @param int $id Bookmark ID | 124 | * @param int $id Bookmark ID |
125 | * @param string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an | 125 | * @param ?string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an |
126 | * exception | 126 | * exception |
127 | * | 127 | * |
128 | * @return bool | 128 | * @return bool |
129 | */ | 129 | */ |
130 | public function exists($id, $visibility = null); | 130 | public function exists(int $id, string $visibility = null): bool; |
131 | 131 | ||
132 | /** | 132 | /** |
133 | * Return the number of available bookmarks for given visibility. | 133 | * Return the number of available bookmarks for given visibility. |
134 | * | 134 | * |
135 | * @param string $visibility public|private|all | 135 | * @param ?string $visibility public|private|all |
136 | * | 136 | * |
137 | * @return int Number of bookmarks | 137 | * @return int Number of bookmarks |
138 | */ | 138 | */ |
139 | public function count($visibility = null); | 139 | public function count(string $visibility = null): int; |
140 | 140 | ||
141 | /** | 141 | /** |
142 | * Write the datastore. | 142 | * Write the datastore. |
143 | * | 143 | * |
144 | * @throws NotWritableDataStoreException | 144 | * @throws NotWritableDataStoreException |
145 | */ | 145 | */ |
146 | public function save(); | 146 | public function save(): void; |
147 | 147 | ||
148 | /** | 148 | /** |
149 | * Returns the list tags appearing in the bookmarks with the given tags | 149 | * Returns the list tags appearing in the bookmarks with the given tags |
150 | * | 150 | * |
151 | * @param array $filteringTags tags selecting the bookmarks to consider | 151 | * @param array|null $filteringTags tags selecting the bookmarks to consider |
152 | * @param string $visibility process only all/private/public bookmarks | 152 | * @param string|null $visibility process only all/private/public bookmarks |
153 | * | 153 | * |
154 | * @return array tag => bookmarksCount | 154 | * @return array tag => bookmarksCount |
155 | */ | 155 | */ |
156 | public function bookmarksCountPerTag($filteringTags = [], $visibility = 'all'); | 156 | public function bookmarksCountPerTag(array $filteringTags = [], ?string $visibility = null): array; |
157 | 157 | ||
158 | /** | 158 | /** |
159 | * Returns the list of days containing articles (oldest first) | 159 | * Return a list of bookmark matching provided period of time. |
160 | * It also update directly previous and next date outside of given period found in the datastore. | ||
161 | * | ||
162 | * @param \DateTimeInterface $from Starting date. | ||
163 | * @param \DateTimeInterface $to Ending date. | ||
164 | * @param \DateTimeInterface|null $previous (by reference) updated with first created date found before $from. | ||
165 | * @param \DateTimeInterface|null $next (by reference) updated with first created date found after $to. | ||
160 | * | 166 | * |
161 | * @return array containing days (in format YYYYMMDD). | 167 | * @return array List of bookmarks matching provided period of time. |
162 | */ | 168 | */ |
163 | public function days(); | 169 | public function findByDate( |
170 | \DateTimeInterface $from, | ||
171 | \DateTimeInterface $to, | ||
172 | ?\DateTimeInterface &$previous, | ||
173 | ?\DateTimeInterface &$next | ||
174 | ): array; | ||
164 | 175 | ||
165 | /** | 176 | /** |
166 | * Returns the list of articles for a given day. | 177 | * Returns the latest bookmark by creation date. |
167 | * | 178 | * |
168 | * @param string $request day to filter. Format: YYYYMMDD. | 179 | * @return Bookmark|null Found Bookmark or null if the datastore is empty. |
169 | * | ||
170 | * @return Bookmark[] list of shaare found. | ||
171 | * | ||
172 | * @throws BookmarkNotFoundException | ||
173 | */ | 180 | */ |
174 | public function filterDay($request); | 181 | public function getLatest(): ?Bookmark; |
175 | 182 | ||
176 | /** | 183 | /** |
177 | * Creates the default database after a fresh install. | 184 | * Creates the default database after a fresh install. |
178 | */ | 185 | */ |
179 | public function initialize(); | 186 | public function initialize(): void; |
180 | } | 187 | } |