aboutsummaryrefslogtreecommitdiffhomepage
path: root/application/bookmark/BookmarkServiceInterface.php
diff options
context:
space:
mode:
Diffstat (limited to 'application/bookmark/BookmarkServiceInterface.php')
-rw-r--r--application/bookmark/BookmarkServiceInterface.php109
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
3namespace Shaarli\Bookmark; 3declare(strict_types=1);
4 4
5namespace Shaarli\Bookmark;
5 6
6use Shaarli\Bookmark\Exception\BookmarkNotFoundException; 7use Shaarli\Bookmark\Exception\BookmarkNotFoundException;
7use Shaarli\Bookmark\Exception\NotWritableDataStoreException; 8use Shaarli\Bookmark\Exception\NotWritableDataStoreException;
8use Shaarli\Config\ConfigManager;
9use Shaarli\Exceptions\IOException;
10use 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 */
17interface BookmarkServiceInterface 18interface 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}