3 namespace Shaarli\Bookmark
;
6 use Shaarli\Bookmark\Exception\BookmarkNotFoundException
;
7 use Shaarli\Bookmark\Exception\NotWritableDataStoreException
;
8 use Shaarli\Config\ConfigManager
;
12 * Class BookmarksService
14 * This is the entry point to manipulate the bookmark DB.
16 interface BookmarkServiceInterface
19 * BookmarksService constructor.
21 * @param ConfigManager $conf instance
22 * @param History $history instance
23 * @param bool $isLoggedIn true if the current user is logged in
25 public function __construct(ConfigManager
$conf, History
$history, $isLoggedIn);
28 * Find a bookmark by hash
36 public function findByHash($hash);
41 * @return Bookmark|null
43 public function findByUrl($url);
48 * @param mixed $request
49 * @param string $visibility
50 * @param bool $caseSensitive
51 * @param bool $untaggedOnly
55 public function search($request = [], $visibility = null, $caseSensitive = false, $untaggedOnly = false);
58 * Get a single bookmark by its ID.
60 * @param int $id Bookmark ID
61 * @param string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an
66 * @throws BookmarkNotFoundException
69 public function get($id, $visibility = null);
72 * Updates an existing bookmark (depending on its ID).
74 * @param Bookmark $bookmark
75 * @param bool $save Writes to the datastore if set to true
77 * @return Bookmark Updated bookmark
79 * @throws BookmarkNotFoundException
82 public function set($bookmark, $save = true);
85 * Adds a new bookmark (the ID must be empty).
87 * @param Bookmark $bookmark
88 * @param bool $save Writes to the datastore if set to true
90 * @return Bookmark new bookmark
94 public function add($bookmark, $save = true);
97 * Adds or updates a bookmark depending on its ID:
98 * - a Bookmark without ID will be added
99 * - a Bookmark with an existing ID will be updated
101 * @param Bookmark $bookmark
108 public function addOrSet($bookmark, $save = true);
111 * Deletes a bookmark.
113 * @param Bookmark $bookmark
118 public function remove($bookmark, $save = true);
121 * Get a single bookmark by its ID.
123 * @param int $id Bookmark ID
124 * @param string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an
129 public function exists($id, $visibility = null);
132 * Return the number of available bookmarks for given visibility.
134 * @param string $visibility public|private|all
136 * @return int Number of bookmarks
138 public function count($visibility = null);
141 * Write the datastore.
143 * @throws NotWritableDataStoreException
145 public function save();
148 * Returns the list tags appearing in the bookmarks with the given tags
150 * @param array $filteringTags tags selecting the bookmarks to consider
151 * @param string $visibility process only all/private/public bookmarks
153 * @return array tag => bookmarksCount
155 public function bookmarksCountPerTag($filteringTags = [], $visibility = 'all');
158 * Returns the list of days containing articles (oldest first)
160 * @return array containing days (in format YYYYMMDD).
162 public function days();
165 * Returns the list of articles for a given day.
167 * @param string $request day to filter. Format: YYYYMMDD.
169 * @return Bookmark[] list of shaare found.
171 * @throws BookmarkNotFoundException
173 public function filterDay($request);
176 * Creates the default database after a fresh install.
178 public function initialize();