application/bookmark/BookmarkServiceInterface.php

   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      *
  53      * @return Bookmark[]
  54      */
  55     public function search($request = [], $visibility = null, $caseSensitive = false, $untaggedOnly = false);
  56
  57     /**
  58      * Get a single bookmark by its ID.
  59      *
  60      * @param int    $id         Bookmark ID
  61      * @param string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an
  62      *                           exception
  63      *
  64      * @return Bookmark
  65      *
  66      * @throws BookmarkNotFoundException
  67      * @throws \Exception
  68      */
  69     public function get($id, $visibility = null);
  70
  71     /**
  72      * Updates an existing bookmark (depending on its ID).
  73      *
  74      * @param Bookmark $bookmark
  75      * @param bool     $save Writes to the datastore if set to true
  76      *
  77      * @return Bookmark Updated bookmark
  78      *
  79      * @throws BookmarkNotFoundException
  80      * @throws \Exception
  81      */
  82     public function set($bookmark, $save = true);
  83
  84     /**
  85      * Adds a new bookmark (the ID must be empty).
  86      *
  87      * @param Bookmark $bookmark
  88      * @param bool     $save Writes to the datastore if set to true
  89      *
  90      * @return Bookmark new bookmark
  91      *
  92      * @throws \Exception
  93      */
  94     public function add($bookmark, $save = true);
  95
  96     /**
  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
 100      *
 101      * @param Bookmark $bookmark
 102      * @param bool     $save
 103      *
 104      * @return Bookmark
 105      *
 106      * @throws \Exception
 107      */
 108     public function addOrSet($bookmark, $save = true);
 109
 110     /**
 111      * Deletes a bookmark.
 112      *
 113      * @param Bookmark $bookmark
 114      * @param bool     $save
 115      *
 116      * @throws \Exception
 117      */
 118     public function remove($bookmark, $save = true);
 119
 120     /**
 121      * Get a single bookmark by its ID.
 122      *
 123      * @param int    $id         Bookmark ID
 124      * @param string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an
 125      *                           exception
 126      *
 127      * @return bool
 128      */
 129     public function exists($id, $visibility = null);
 130
 131     /**
 132      * Return the number of available bookmarks for given visibility.
 133      *
 134      * @param string $visibility public|private|all
 135      *
 136      * @return int Number of bookmarks
 137      */
 138     public function count($visibility = null);
 139
 140     /**
 141      * Write the datastore.
 142      *
 143      * @throws NotWritableDataStoreException
 144      */
 145     public function save();
 146
 147     /**
 148      * Returns the list tags appearing in the bookmarks with the given tags
 149      *
 150      * @param array  $filteringTags tags selecting the bookmarks to consider
 151      * @param string $visibility    process only all/private/public bookmarks
 152      *
 153      * @return array tag => bookmarksCount
 154      */
 155     public function bookmarksCountPerTag($filteringTags = [], $visibility = 'all');
 156
 157     /**
 158      * Returns the list of days containing articles (oldest first)
 159      *
 160      * @return array containing days (in format YYYYMMDD).
 161      */
 162     public function days();
 163
 164     /**
 165      * Returns the list of articles for a given day.
 166      *
 167      * @param string $request day to filter. Format: YYYYMMDD.
 168      *
 169      * @return Bookmark[] list of shaare found.
 170      *
 171      * @throws BookmarkNotFoundException
 172      */
 173     public function filterDay($request);
 174
 175     /**
 176      * Creates the default database after a fresh install.
 177      */
 178     public function initialize();
 179 }