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