]>
Commit | Line | Data |
---|---|---|
336a28fa A |
1 | <?php |
2 | ||
3 | namespace Shaarli\Bookmark; | |
4 | ||
5 | ||
6 | use Shaarli\Bookmark\Exception\BookmarkNotFoundException; | |
7 | use Shaarli\Bookmark\Exception\NotWritableDataStoreException; | |
8 | use Shaarli\Config\ConfigManager; | |
336a28fa A |
9 | use Shaarli\History; |
10 | ||
11 | /** | |
12 | * Class BookmarksService | |
13 | * | |
14 | * This is the entry point to manipulate the bookmark DB. | |
15 | */ | |
16 | interface BookmarkServiceInterface | |
17 | { | |
18 | /** | |
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 | |
29 | * | |
30 | * @param string $hash | |
31 | * | |
32 | * @return mixed | |
33 | * | |
34 | * @throws \Exception | |
35 | */ | |
36 | public function findByHash($hash); | |
37 | ||
38 | /** | |
39 | * @param $url | |
40 | * | |
41 | * @return Bookmark|null | |
42 | */ | |
43 | public function findByUrl($url); | |
44 | ||
45 | /** | |
46 | * Search bookmarks | |
47 | * | |
48 | * @param mixed $request | |
49 | * @param string $visibility | |
50 | * @param bool $caseSensitive | |
51 | * @param bool $untaggedOnly | |
a8e210fa | 52 | * @param bool $ignoreSticky |
336a28fa A |
53 | * |
54 | * @return Bookmark[] | |
55 | */ | |
a8e210fa A |
56 | public function search( |
57 | $request = [], | |
58 | $visibility = null, | |
59 | $caseSensitive = false, | |
60 | $untaggedOnly = false, | |
61 | bool $ignoreSticky = false | |
62 | ); | |
336a28fa A |
63 | |
64 | /** | |
65 | * Get a single bookmark by its ID. | |
66 | * | |
67 | * @param int $id Bookmark ID | |
68 | * @param string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an | |
69 | * exception | |
70 | * | |
71 | * @return Bookmark | |
72 | * | |
73 | * @throws BookmarkNotFoundException | |
74 | * @throws \Exception | |
75 | */ | |
76 | public function get($id, $visibility = null); | |
77 | ||
78 | /** | |
79 | * Updates an existing bookmark (depending on its ID). | |
80 | * | |
81 | * @param Bookmark $bookmark | |
82 | * @param bool $save Writes to the datastore if set to true | |
83 | * | |
84 | * @return Bookmark Updated bookmark | |
85 | * | |
86 | * @throws BookmarkNotFoundException | |
87 | * @throws \Exception | |
88 | */ | |
89 | public function set($bookmark, $save = true); | |
90 | ||
91 | /** | |
92 | * Adds a new bookmark (the ID must be empty). | |
93 | * | |
94 | * @param Bookmark $bookmark | |
95 | * @param bool $save Writes to the datastore if set to true | |
96 | * | |
97 | * @return Bookmark new bookmark | |
98 | * | |
99 | * @throws \Exception | |
100 | */ | |
101 | public function add($bookmark, $save = true); | |
102 | ||
103 | /** | |
104 | * Adds or updates a bookmark depending on its ID: | |
105 | * - a Bookmark without ID will be added | |
106 | * - a Bookmark with an existing ID will be updated | |
107 | * | |
108 | * @param Bookmark $bookmark | |
109 | * @param bool $save | |
110 | * | |
111 | * @return Bookmark | |
112 | * | |
113 | * @throws \Exception | |
114 | */ | |
115 | public function addOrSet($bookmark, $save = true); | |
116 | ||
117 | /** | |
118 | * Deletes a bookmark. | |
119 | * | |
120 | * @param Bookmark $bookmark | |
121 | * @param bool $save | |
122 | * | |
123 | * @throws \Exception | |
124 | */ | |
125 | public function remove($bookmark, $save = true); | |
126 | ||
127 | /** | |
128 | * Get a single bookmark by its ID. | |
129 | * | |
130 | * @param int $id Bookmark ID | |
131 | * @param string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an | |
132 | * exception | |
133 | * | |
134 | * @return bool | |
135 | */ | |
136 | public function exists($id, $visibility = null); | |
137 | ||
138 | /** | |
139 | * Return the number of available bookmarks for given visibility. | |
140 | * | |
141 | * @param string $visibility public|private|all | |
142 | * | |
143 | * @return int Number of bookmarks | |
144 | */ | |
145 | public function count($visibility = null); | |
146 | ||
147 | /** | |
148 | * Write the datastore. | |
149 | * | |
150 | * @throws NotWritableDataStoreException | |
151 | */ | |
152 | public function save(); | |
153 | ||
154 | /** | |
155 | * Returns the list tags appearing in the bookmarks with the given tags | |
156 | * | |
157 | * @param array $filteringTags tags selecting the bookmarks to consider | |
158 | * @param string $visibility process only all/private/public bookmarks | |
159 | * | |
160 | * @return array tag => bookmarksCount | |
161 | */ | |
162 | public function bookmarksCountPerTag($filteringTags = [], $visibility = 'all'); | |
163 | ||
164 | /** | |
165 | * Returns the list of days containing articles (oldest first) | |
166 | * | |
167 | * @return array containing days (in format YYYYMMDD). | |
168 | */ | |
169 | public function days(); | |
170 | ||
171 | /** | |
172 | * Returns the list of articles for a given day. | |
173 | * | |
174 | * @param string $request day to filter. Format: YYYYMMDD. | |
175 | * | |
176 | * @return Bookmark[] list of shaare found. | |
177 | * | |
178 | * @throws BookmarkNotFoundException | |
179 | */ | |
180 | public function filterDay($request); | |
181 | ||
182 | /** | |
183 | * Creates the default database after a fresh install. | |
184 | */ | |
185 | public function initialize(); | |
186 | } |