aboutsummaryrefslogtreecommitdiffhomepage
path: root/application/bookmark/BookmarkServiceInterface.php
diff options
context:
space:
mode:
authorArthurHoaro <arthur@hoa.ro>2020-11-12 13:02:36 +0100
committerArthurHoaro <arthur@hoa.ro>2020-11-12 13:02:36 +0100
commit1409f1c89a7ca01456ae2dcd6357d296e2b99f5a (patch)
treeffa30a9358e82d27be75d8fc5e57f3c8820dc6d3 /application/bookmark/BookmarkServiceInterface.php
parent054e03f37fa29da8066f1a637919f13c7e7dc5d2 (diff)
parenta6935feb22df8d9634189ee87d257da9f03eedbd (diff)
downloadShaarli-1409f1c89a7ca01456ae2dcd6357d296e2b99f5a.tar.gz
Shaarli-1409f1c89a7ca01456ae2dcd6357d296e2b99f5a.tar.zst
Shaarli-1409f1c89a7ca01456ae2dcd6357d296e2b99f5a.zip
Merge branch 'master' into v0.12v0.12.1v0.12
Diffstat (limited to 'application/bookmark/BookmarkServiceInterface.php')
-rw-r--r--application/bookmark/BookmarkServiceInterface.php109
1 files changed, 55 insertions, 54 deletions
diff --git a/application/bookmark/BookmarkServiceInterface.php b/application/bookmark/BookmarkServiceInterface.php
index b9b483eb..08cdbb4e 100644
--- a/application/bookmark/BookmarkServiceInterface.php
+++ b/application/bookmark/BookmarkServiceInterface.php
@@ -1,79 +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\History;
10 9
11/** 10/**
12 * Class BookmarksService 11 * Class BookmarksService
13 * 12 *
14 * 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.
15 */ 17 */
16interface BookmarkServiceInterface 18interface BookmarkServiceInterface
17{ 19{
18 /** 20 /**
19 * BookmarksService constructor.
20 *
21 * @param ConfigManager $conf instance
22 * @param History $history instance
23 * @param bool $isLoggedIn true if the current user is logged in
24 */
25 public function __construct(ConfigManager $conf, History $history, $isLoggedIn);
26
27 /**
28 * Find a bookmark by hash 21 * Find a bookmark by hash
29 * 22 *
30 * @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
31 * 25 *
32 * @return mixed 26 * @return Bookmark
33 * 27 *
34 * @throws \Exception 28 * @throws \Exception
35 */ 29 */
36 public function findByHash($hash); 30 public function findByHash(string $hash, string $privateKey = null);
37 31
38 /** 32 /**
39 * @param $url 33 * @param $url
40 * 34 *
41 * @return Bookmark|null 35 * @return Bookmark|null
42 */ 36 */
43 public function findByUrl($url); 37 public function findByUrl(string $url): ?Bookmark;
44 38
45 /** 39 /**
46 * Search bookmarks 40 * Search bookmarks
47 * 41 *
48 * @param mixed $request 42 * @param array $request
49 * @param string $visibility 43 * @param ?string $visibility
50 * @param bool $caseSensitive 44 * @param bool $caseSensitive
51 * @param bool $untaggedOnly 45 * @param bool $untaggedOnly
52 * @param bool $ignoreSticky 46 * @param bool $ignoreSticky
53 * 47 *
54 * @return Bookmark[] 48 * @return Bookmark[]
55 */ 49 */
56 public function search( 50 public function search(
57 $request = [], 51 array $request = [],
58 $visibility = null, 52 string $visibility = null,
59 $caseSensitive = false, 53 bool $caseSensitive = false,
60 $untaggedOnly = false, 54 bool $untaggedOnly = false,
61 bool $ignoreSticky = false 55 bool $ignoreSticky = false
62 ); 56 );
63 57
64 /** 58 /**
65 * Get a single bookmark by its ID. 59 * Get a single bookmark by its ID.
66 * 60 *
67 * @param int $id Bookmark ID 61 * @param int $id Bookmark ID
68 * @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
69 * exception 63 * exception
70 * 64 *
71 * @return Bookmark 65 * @return Bookmark
72 * 66 *
73 * @throws BookmarkNotFoundException 67 * @throws BookmarkNotFoundException
74 * @throws \Exception 68 * @throws \Exception
75 */ 69 */
76 public function get($id, $visibility = null); 70 public function get(int $id, string $visibility = null);
77 71
78 /** 72 /**
79 * Updates an existing bookmark (depending on its ID). 73 * Updates an existing bookmark (depending on its ID).
@@ -86,7 +80,7 @@ interface BookmarkServiceInterface
86 * @throws BookmarkNotFoundException 80 * @throws BookmarkNotFoundException
87 * @throws \Exception 81 * @throws \Exception
88 */ 82 */
89 public function set($bookmark, $save = true); 83 public function set(Bookmark $bookmark, bool $save = true): Bookmark;
90 84
91 /** 85 /**
92 * Adds a new bookmark (the ID must be empty). 86 * Adds a new bookmark (the ID must be empty).
@@ -98,7 +92,7 @@ interface BookmarkServiceInterface
98 * 92 *
99 * @throws \Exception 93 * @throws \Exception
100 */ 94 */
101 public function add($bookmark, $save = true); 95 public function add(Bookmark $bookmark, bool $save = true): Bookmark;
102 96
103 /** 97 /**
104 * Adds or updates a bookmark depending on its ID: 98 * Adds or updates a bookmark depending on its ID:
@@ -112,7 +106,7 @@ interface BookmarkServiceInterface
112 * 106 *
113 * @throws \Exception 107 * @throws \Exception
114 */ 108 */
115 public function addOrSet($bookmark, $save = true); 109 public function addOrSet(Bookmark $bookmark, bool $save = true): Bookmark;
116 110
117 /** 111 /**
118 * Deletes a bookmark. 112 * Deletes a bookmark.
@@ -122,65 +116,72 @@ interface BookmarkServiceInterface
122 * 116 *
123 * @throws \Exception 117 * @throws \Exception
124 */ 118 */
125 public function remove($bookmark, $save = true); 119 public function remove(Bookmark $bookmark, bool $save = true): void;
126 120
127 /** 121 /**
128 * Get a single bookmark by its ID. 122 * Get a single bookmark by its ID.
129 * 123 *
130 * @param int $id Bookmark ID 124 * @param int $id Bookmark ID
131 * @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
132 * exception 126 * exception
133 * 127 *
134 * @return bool 128 * @return bool
135 */ 129 */
136 public function exists($id, $visibility = null); 130 public function exists(int $id, string $visibility = null): bool;
137 131
138 /** 132 /**
139 * Return the number of available bookmarks for given visibility. 133 * Return the number of available bookmarks for given visibility.
140 * 134 *
141 * @param string $visibility public|private|all 135 * @param ?string $visibility public|private|all
142 * 136 *
143 * @return int Number of bookmarks 137 * @return int Number of bookmarks
144 */ 138 */
145 public function count($visibility = null); 139 public function count(string $visibility = null): int;
146 140
147 /** 141 /**
148 * Write the datastore. 142 * Write the datastore.
149 * 143 *
150 * @throws NotWritableDataStoreException 144 * @throws NotWritableDataStoreException
151 */ 145 */
152 public function save(); 146 public function save(): void;
153 147
154 /** 148 /**
155 * 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
156 * 150 *
157 * @param array $filteringTags tags selecting the bookmarks to consider 151 * @param array|null $filteringTags tags selecting the bookmarks to consider
158 * @param string $visibility process only all/private/public bookmarks 152 * @param string|null $visibility process only all/private/public bookmarks
159 * 153 *
160 * @return array tag => bookmarksCount 154 * @return array tag => bookmarksCount
161 */ 155 */
162 public function bookmarksCountPerTag($filteringTags = [], $visibility = 'all'); 156 public function bookmarksCountPerTag(array $filteringTags = [], ?string $visibility = null): array;
163 157
164 /** 158 /**
165 * 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.
166 * 166 *
167 * @return array containing days (in format YYYYMMDD). 167 * @return array List of bookmarks matching provided period of time.
168 */ 168 */
169 public function days(); 169 public function findByDate(
170 \DateTimeInterface $from,
171 \DateTimeInterface $to,
172 ?\DateTimeInterface &$previous,
173 ?\DateTimeInterface &$next
174 ): array;
170 175
171 /** 176 /**
172 * Returns the list of articles for a given day. 177 * Returns the latest bookmark by creation date.
173 * 178 *
174 * @param string $request day to filter. Format: YYYYMMDD. 179 * @return Bookmark|null Found Bookmark or null if the datastore is empty.
175 *
176 * @return Bookmark[] list of shaare found.
177 *
178 * @throws BookmarkNotFoundException
179 */ 180 */
180 public function filterDay($request); 181 public function getLatest(): ?Bookmark;
181 182
182 /** 183 /**
183 * Creates the default database after a fresh install. 184 * Creates the default database after a fresh install.
184 */ 185 */
185 public function initialize(); 186 public function initialize(): void;
186} 187}