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