path: root/application/bookmark/BookmarkServiceInterface.php

<?php

namespace Shaarli\Bookmark;


use Shaarli\Bookmark\Exception\BookmarkNotFoundException;
use Shaarli\Bookmark\Exception\NotWritableDataStoreException;

/**
 * Class BookmarksService
 *
 * This is the entry point to manipulate the bookmark DB.
 */
interface BookmarkServiceInterface
{
    /**
     * 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();
}