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\Exceptions\IOException;
  10 use Shaarli\History;
  11
  12 /**
  13  * Class BookmarksService
  14  *
  15  * This is the entry point to manipulate the bookmark DB.
  16  */
  17 interface 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 }