a8e210faa6
Fixes #1485
186 lines
4.6 KiB
PHP
186 lines
4.6 KiB
PHP
<?php
|
|
|
|
namespace Shaarli\Bookmark;
|
|
|
|
|
|
use Shaarli\Bookmark\Exception\BookmarkNotFoundException;
|
|
use Shaarli\Bookmark\Exception\NotWritableDataStoreException;
|
|
use Shaarli\Config\ConfigManager;
|
|
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
|
|
* @param bool $ignoreSticky
|
|
*
|
|
* @return Bookmark[]
|
|
*/
|
|
public function search(
|
|
$request = [],
|
|
$visibility = null,
|
|
$caseSensitive = false,
|
|
$untaggedOnly = false,
|
|
bool $ignoreSticky = 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();
|
|
}
|