]>
Commit | Line | Data |
---|---|---|
336a28fa A |
1 | <?php |
2 | ||
efb7d21b | 3 | declare(strict_types=1); |
336a28fa | 4 | |
efb7d21b | 5 | namespace Shaarli\Bookmark; |
336a28fa A |
6 | |
7 | use Shaarli\Bookmark\Exception\BookmarkNotFoundException; | |
8 | use Shaarli\Bookmark\Exception\NotWritableDataStoreException; | |
336a28fa A |
9 | |
10 | /** | |
11 | * Class BookmarksService | |
12 | * | |
13 | * This is the entry point to manipulate the bookmark DB. | |
efb7d21b A |
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. | |
336a28fa A |
17 | */ |
18 | interface BookmarkServiceInterface | |
19 | { | |
336a28fa A |
20 | /** |
21 | * Find a bookmark by hash | |
22 | * | |
9c04921a A |
23 | * @param string $hash Bookmark's hash |
24 | * @param string|null $privateKey Optional key used to access private links while logged out | |
336a28fa | 25 | * |
efb7d21b | 26 | * @return Bookmark |
336a28fa A |
27 | * |
28 | * @throws \Exception | |
29 | */ | |
9c04921a | 30 | public function findByHash(string $hash, string $privateKey = null); |
336a28fa A |
31 | |
32 | /** | |
33 | * @param $url | |
34 | * | |
35 | * @return Bookmark|null | |
36 | */ | |
efb7d21b | 37 | public function findByUrl(string $url): ?Bookmark; |
336a28fa A |
38 | |
39 | /** | |
40 | * Search bookmarks | |
41 | * | |
efb7d21b A |
42 | * @param array $request |
43 | * @param ?string $visibility | |
44 | * @param bool $caseSensitive | |
45 | * @param bool $untaggedOnly | |
46 | * @param bool $ignoreSticky | |
9b8c0a45 | 47 | * @param array $pagination This array can contain the following keys for pagination: limit, offset. |
336a28fa | 48 | * |
9b8c0a45 | 49 | * @return SearchResult |
336a28fa | 50 | */ |
a8e210fa | 51 | public function search( |
efb7d21b A |
52 | array $request = [], |
53 | string $visibility = null, | |
54 | bool $caseSensitive = false, | |
55 | bool $untaggedOnly = false, | |
9b8c0a45 A |
56 | bool $ignoreSticky = false, |
57 | array $pagination = [] | |
58 | ): SearchResult; | |
336a28fa A |
59 | |
60 | /** | |
61 | * Get a single bookmark by its ID. | |
62 | * | |
efb7d21b A |
63 | * @param int $id Bookmark ID |
64 | * @param ?string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an | |
65 | * exception | |
336a28fa A |
66 | * |
67 | * @return Bookmark | |
68 | * | |
69 | * @throws BookmarkNotFoundException | |
70 | * @throws \Exception | |
71 | */ | |
efb7d21b | 72 | public function get(int $id, string $visibility = null); |
336a28fa A |
73 | |
74 | /** | |
75 | * Updates an existing bookmark (depending on its ID). | |
76 | * | |
77 | * @param Bookmark $bookmark | |
78 | * @param bool $save Writes to the datastore if set to true | |
79 | * | |
80 | * @return Bookmark Updated bookmark | |
81 | * | |
82 | * @throws BookmarkNotFoundException | |
83 | * @throws \Exception | |
84 | */ | |
efb7d21b | 85 | public function set(Bookmark $bookmark, bool $save = true): Bookmark; |
336a28fa A |
86 | |
87 | /** | |
88 | * Adds a new bookmark (the ID must be empty). | |
89 | * | |
90 | * @param Bookmark $bookmark | |
91 | * @param bool $save Writes to the datastore if set to true | |
92 | * | |
93 | * @return Bookmark new bookmark | |
94 | * | |
95 | * @throws \Exception | |
96 | */ | |
efb7d21b | 97 | public function add(Bookmark $bookmark, bool $save = true): Bookmark; |
336a28fa A |
98 | |
99 | /** | |
100 | * Adds or updates a bookmark depending on its ID: | |
101 | * - a Bookmark without ID will be added | |
102 | * - a Bookmark with an existing ID will be updated | |
103 | * | |
104 | * @param Bookmark $bookmark | |
105 | * @param bool $save | |
106 | * | |
107 | * @return Bookmark | |
108 | * | |
109 | * @throws \Exception | |
110 | */ | |
efb7d21b | 111 | public function addOrSet(Bookmark $bookmark, bool $save = true): Bookmark; |
336a28fa A |
112 | |
113 | /** | |
114 | * Deletes a bookmark. | |
115 | * | |
116 | * @param Bookmark $bookmark | |
117 | * @param bool $save | |
118 | * | |
119 | * @throws \Exception | |
120 | */ | |
efb7d21b | 121 | public function remove(Bookmark $bookmark, bool $save = true): void; |
336a28fa A |
122 | |
123 | /** | |
124 | * Get a single bookmark by its ID. | |
125 | * | |
efb7d21b A |
126 | * @param int $id Bookmark ID |
127 | * @param ?string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an | |
128 | * exception | |
336a28fa A |
129 | * |
130 | * @return bool | |
131 | */ | |
efb7d21b | 132 | public function exists(int $id, string $visibility = null): bool; |
336a28fa A |
133 | |
134 | /** | |
135 | * Return the number of available bookmarks for given visibility. | |
136 | * | |
efb7d21b | 137 | * @param ?string $visibility public|private|all |
336a28fa A |
138 | * |
139 | * @return int Number of bookmarks | |
140 | */ | |
efb7d21b | 141 | public function count(string $visibility = null): int; |
336a28fa A |
142 | |
143 | /** | |
144 | * Write the datastore. | |
145 | * | |
146 | * @throws NotWritableDataStoreException | |
147 | */ | |
efb7d21b | 148 | public function save(): void; |
336a28fa A |
149 | |
150 | /** | |
151 | * Returns the list tags appearing in the bookmarks with the given tags | |
152 | * | |
efb7d21b A |
153 | * @param array|null $filteringTags tags selecting the bookmarks to consider |
154 | * @param string|null $visibility process only all/private/public bookmarks | |
336a28fa A |
155 | * |
156 | * @return array tag => bookmarksCount | |
157 | */ | |
efb7d21b | 158 | public function bookmarksCountPerTag(array $filteringTags = [], ?string $visibility = null): array; |
336a28fa A |
159 | |
160 | /** | |
36e6d88d A |
161 | * Return a list of bookmark matching provided period of time. |
162 | * It also update directly previous and next date outside of given period found in the datastore. | |
336a28fa | 163 | * |
36e6d88d A |
164 | * @param \DateTimeInterface $from Starting date. |
165 | * @param \DateTimeInterface $to Ending date. | |
166 | * @param \DateTimeInterface|null $previous (by reference) updated with first created date found before $from. | |
167 | * @param \DateTimeInterface|null $next (by reference) updated with first created date found after $to. | |
168 | * | |
169 | * @return array List of bookmarks matching provided period of time. | |
336a28fa | 170 | */ |
36e6d88d A |
171 | public function findByDate( |
172 | \DateTimeInterface $from, | |
173 | \DateTimeInterface $to, | |
174 | ?\DateTimeInterface &$previous, | |
175 | ?\DateTimeInterface &$next | |
176 | ): array; | |
336a28fa A |
177 | |
178 | /** | |
36e6d88d | 179 | * Returns the latest bookmark by creation date. |
336a28fa | 180 | * |
36e6d88d | 181 | * @return Bookmark|null Found Bookmark or null if the datastore is empty. |
336a28fa | 182 | */ |
36e6d88d | 183 | public function getLatest(): ?Bookmark; |
336a28fa A |
184 | |
185 | /** | |
186 | * Creates the default database after a fresh install. | |
187 | */ | |
efb7d21b | 188 | public function initialize(): void; |
336a28fa | 189 | } |