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