aboutsummaryrefslogtreecommitdiffhomepage
path: root/application/bookmark/BookmarkServiceInterface.php
diff options
context:
space:
mode:
authorArthurHoaro <arthur@hoa.ro>2020-10-13 13:56:07 +0200
committerGitHub <noreply@github.com>2020-10-13 13:56:07 +0200
commit4a26974a4b36362d25d8a3a029eac539685c03f6 (patch)
tree4f34052788a08be1a30cb88c3339ae14e0b7c4da /application/bookmark/BookmarkServiceInterface.php
parent29c31b7ec6ca48ba37b7eb6da650931fd0cb7164 (diff)
parentefb7d21b52eb033530e80e5e49d175e6e3b031f4 (diff)
downloadShaarli-4a26974a4b36362d25d8a3a029eac539685c03f6.tar.gz
Shaarli-4a26974a4b36362d25d8a3a029eac539685c03f6.tar.zst
Shaarli-4a26974a4b36362d25d8a3a029eac539685c03f6.zip
Merge pull request #1583 from ArthurHoaro/feature/bookmark-strict-types
Add strict types for bookmarks management
Diffstat (limited to 'application/bookmark/BookmarkServiceInterface.php')
-rw-r--r--application/bookmark/BookmarkServiceInterface.php72
1 files changed, 38 insertions, 34 deletions
diff --git a/application/bookmark/BookmarkServiceInterface.php b/application/bookmark/BookmarkServiceInterface.php
index 638cfa5f..37a54d03 100644
--- a/application/bookmark/BookmarkServiceInterface.php
+++ b/application/bookmark/BookmarkServiceInterface.php
@@ -1,7 +1,8 @@
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;
@@ -10,6 +11,9 @@ use Shaarli\Bookmark\Exception\NotWritableDataStoreException;
10 * Class BookmarksService 11 * Class BookmarksService
11 * 12 *
12 * 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.
13 */ 17 */
14interface BookmarkServiceInterface 18interface BookmarkServiceInterface
15{ 19{
@@ -18,51 +22,51 @@ interface BookmarkServiceInterface
18 * 22 *
19 * @param string $hash 23 * @param string $hash
20 * 24 *
21 * @return mixed 25 * @return Bookmark
22 * 26 *
23 * @throws \Exception 27 * @throws \Exception
24 */ 28 */
25 public function findByHash($hash); 29 public function findByHash(string $hash): Bookmark;
26 30
27 /** 31 /**
28 * @param $url 32 * @param $url
29 * 33 *
30 * @return Bookmark|null 34 * @return Bookmark|null
31 */ 35 */
32 public function findByUrl($url); 36 public function findByUrl(string $url): ?Bookmark;
33 37
34 /** 38 /**
35 * Search bookmarks 39 * Search bookmarks
36 * 40 *
37 * @param mixed $request 41 * @param array $request
38 * @param string $visibility 42 * @param ?string $visibility
39 * @param bool $caseSensitive 43 * @param bool $caseSensitive
40 * @param bool $untaggedOnly 44 * @param bool $untaggedOnly
41 * @param bool $ignoreSticky 45 * @param bool $ignoreSticky
42 * 46 *
43 * @return Bookmark[] 47 * @return Bookmark[]
44 */ 48 */
45 public function search( 49 public function search(
46 $request = [], 50 array $request = [],
47 $visibility = null, 51 string $visibility = null,
48 $caseSensitive = false, 52 bool $caseSensitive = false,
49 $untaggedOnly = false, 53 bool $untaggedOnly = false,
50 bool $ignoreSticky = false 54 bool $ignoreSticky = false
51 ); 55 );
52 56
53 /** 57 /**
54 * Get a single bookmark by its ID. 58 * Get a single bookmark by its ID.
55 * 59 *
56 * @param int $id Bookmark ID 60 * @param int $id Bookmark ID
57 * @param string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an 61 * @param ?string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an
58 * exception 62 * exception
59 * 63 *
60 * @return Bookmark 64 * @return Bookmark
61 * 65 *
62 * @throws BookmarkNotFoundException 66 * @throws BookmarkNotFoundException
63 * @throws \Exception 67 * @throws \Exception
64 */ 68 */
65 public function get($id, $visibility = null); 69 public function get(int $id, string $visibility = null);
66 70
67 /** 71 /**
68 * Updates an existing bookmark (depending on its ID). 72 * Updates an existing bookmark (depending on its ID).
@@ -75,7 +79,7 @@ interface BookmarkServiceInterface
75 * @throws BookmarkNotFoundException 79 * @throws BookmarkNotFoundException
76 * @throws \Exception 80 * @throws \Exception
77 */ 81 */
78 public function set($bookmark, $save = true); 82 public function set(Bookmark $bookmark, bool $save = true): Bookmark;
79 83
80 /** 84 /**
81 * Adds a new bookmark (the ID must be empty). 85 * Adds a new bookmark (the ID must be empty).
@@ -87,7 +91,7 @@ interface BookmarkServiceInterface
87 * 91 *
88 * @throws \Exception 92 * @throws \Exception
89 */ 93 */
90 public function add($bookmark, $save = true); 94 public function add(Bookmark $bookmark, bool $save = true): Bookmark;
91 95
92 /** 96 /**
93 * Adds or updates a bookmark depending on its ID: 97 * Adds or updates a bookmark depending on its ID:
@@ -101,7 +105,7 @@ interface BookmarkServiceInterface
101 * 105 *
102 * @throws \Exception 106 * @throws \Exception
103 */ 107 */
104 public function addOrSet($bookmark, $save = true); 108 public function addOrSet(Bookmark $bookmark, bool $save = true): Bookmark;
105 109
106 /** 110 /**
107 * Deletes a bookmark. 111 * Deletes a bookmark.
@@ -111,51 +115,51 @@ interface BookmarkServiceInterface
111 * 115 *
112 * @throws \Exception 116 * @throws \Exception
113 */ 117 */
114 public function remove($bookmark, $save = true); 118 public function remove(Bookmark $bookmark, bool $save = true): void;
115 119
116 /** 120 /**
117 * Get a single bookmark by its ID. 121 * Get a single bookmark by its ID.
118 * 122 *
119 * @param int $id Bookmark ID 123 * @param int $id Bookmark ID
120 * @param string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an 124 * @param ?string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an
121 * exception 125 * exception
122 * 126 *
123 * @return bool 127 * @return bool
124 */ 128 */
125 public function exists($id, $visibility = null); 129 public function exists(int $id, string $visibility = null): bool;
126 130
127 /** 131 /**
128 * Return the number of available bookmarks for given visibility. 132 * Return the number of available bookmarks for given visibility.
129 * 133 *
130 * @param string $visibility public|private|all 134 * @param ?string $visibility public|private|all
131 * 135 *
132 * @return int Number of bookmarks 136 * @return int Number of bookmarks
133 */ 137 */
134 public function count($visibility = null); 138 public function count(string $visibility = null): int;
135 139
136 /** 140 /**
137 * Write the datastore. 141 * Write the datastore.
138 * 142 *
139 * @throws NotWritableDataStoreException 143 * @throws NotWritableDataStoreException
140 */ 144 */
141 public function save(); 145 public function save(): void;
142 146
143 /** 147 /**
144 * Returns the list tags appearing in the bookmarks with the given tags 148 * Returns the list tags appearing in the bookmarks with the given tags
145 * 149 *
146 * @param array $filteringTags tags selecting the bookmarks to consider 150 * @param array|null $filteringTags tags selecting the bookmarks to consider
147 * @param string $visibility process only all/private/public bookmarks 151 * @param string|null $visibility process only all/private/public bookmarks
148 * 152 *
149 * @return array tag => bookmarksCount 153 * @return array tag => bookmarksCount
150 */ 154 */
151 public function bookmarksCountPerTag($filteringTags = [], $visibility = 'all'); 155 public function bookmarksCountPerTag(array $filteringTags = [], ?string $visibility = null): array;
152 156
153 /** 157 /**
154 * Returns the list of days containing articles (oldest first) 158 * Returns the list of days containing articles (oldest first)
155 * 159 *
156 * @return array containing days (in format YYYYMMDD). 160 * @return array containing days (in format YYYYMMDD).
157 */ 161 */
158 public function days(); 162 public function days(): array;
159 163
160 /** 164 /**
161 * Returns the list of articles for a given day. 165 * Returns the list of articles for a given day.
@@ -166,10 +170,10 @@ interface BookmarkServiceInterface
166 * 170 *
167 * @throws BookmarkNotFoundException 171 * @throws BookmarkNotFoundException
168 */ 172 */
169 public function filterDay($request); 173 public function filterDay(string $request);
170 174
171 /** 175 /**
172 * Creates the default database after a fresh install. 176 * Creates the default database after a fresh install.
173 */ 177 */
174 public function initialize(); 178 public function initialize(): void;
175} 179}