diff options
Diffstat (limited to 'application/bookmark/BookmarkServiceInterface.php')
-rw-r--r-- | application/bookmark/BookmarkServiceInterface.php | 186 |
1 files changed, 186 insertions, 0 deletions
diff --git a/application/bookmark/BookmarkServiceInterface.php b/application/bookmark/BookmarkServiceInterface.php new file mode 100644 index 00000000..b9b483eb --- /dev/null +++ b/application/bookmark/BookmarkServiceInterface.php | |||
@@ -0,0 +1,186 @@ | |||
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; | ||
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 | ||
52 | * @param bool $ignoreSticky | ||
53 | * | ||
54 | * @return Bookmark[] | ||
55 | */ | ||
56 | public function search( | ||
57 | $request = [], | ||
58 | $visibility = null, | ||
59 | $caseSensitive = false, | ||
60 | $untaggedOnly = false, | ||
61 | bool $ignoreSticky = false | ||
62 | ); | ||
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 | } | ||