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
   9 /**
  10  * Class BookmarksService
  11  *
  12  * This is the entry point to manipulate the bookmark DB.
  13  */
  14 interface BookmarkServiceInterface
  15 {
  16     /**
  17      * Find a bookmark by hash
  18      *
  19      * @param string $hash
  20      *
  21      * @return mixed
  22      *
  23      * @throws \Exception
  24      */
  25     public function findByHash($hash);
  26
  27     /**
  28      * @param $url
  29      *
  30      * @return Bookmark|null
  31      */
  32     public function findByUrl($url);
  33
  34     /**
  35      * Search bookmarks
  36      *
  37      * @param mixed  $request
  38      * @param string $visibility
  39      * @param bool   $caseSensitive
  40      * @param bool   $untaggedOnly
  41      * @param bool   $ignoreSticky
  42      *
  43      * @return Bookmark[]
  44      */
  45     public function search(
  46         $request = [],
  47         $visibility = null,
  48         $caseSensitive = false,
  49         $untaggedOnly = false,
  50         bool $ignoreSticky = false
  51     );
  52
  53     /**
  54      * Get a single bookmark by its ID.
  55      *
  56      * @param int    $id         Bookmark ID
  57      * @param string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an
  58      *                           exception
  59      *
  60      * @return Bookmark
  61      *
  62      * @throws BookmarkNotFoundException
  63      * @throws \Exception
  64      */
  65     public function get($id, $visibility = null);
  66
  67     /**
  68      * Updates an existing bookmark (depending on its ID).
  69      *
  70      * @param Bookmark $bookmark
  71      * @param bool     $save Writes to the datastore if set to true
  72      *
  73      * @return Bookmark Updated bookmark
  74      *
  75      * @throws BookmarkNotFoundException
  76      * @throws \Exception
  77      */
  78     public function set($bookmark, $save = true);
  79
  80     /**
  81      * Adds a new bookmark (the ID must be empty).
  82      *
  83      * @param Bookmark $bookmark
  84      * @param bool     $save Writes to the datastore if set to true
  85      *
  86      * @return Bookmark new bookmark
  87      *
  88      * @throws \Exception
  89      */
  90     public function add($bookmark, $save = true);
  91
  92     /**
  93      * Adds or updates a bookmark depending on its ID:
  94      *   - a Bookmark without ID will be added
  95      *   - a Bookmark with an existing ID will be updated
  96      *
  97      * @param Bookmark $bookmark
  98      * @param bool     $save
  99      *
 100      * @return Bookmark
 101      *
 102      * @throws \Exception
 103      */
 104     public function addOrSet($bookmark, $save = true);
 105
 106     /**
 107      * Deletes a bookmark.
 108      *
 109      * @param Bookmark $bookmark
 110      * @param bool     $save
 111      *
 112      * @throws \Exception
 113      */
 114     public function remove($bookmark, $save = true);
 115
 116     /**
 117      * Get a single bookmark by its ID.
 118      *
 119      * @param int    $id         Bookmark ID
 120      * @param string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an
 121      *                           exception
 122      *
 123      * @return bool
 124      */
 125     public function exists($id, $visibility = null);
 126
 127     /**
 128      * Return the number of available bookmarks for given visibility.
 129      *
 130      * @param string $visibility public|private|all
 131      *
 132      * @return int Number of bookmarks
 133      */
 134     public function count($visibility = null);
 135
 136     /**
 137      * Write the datastore.
 138      *
 139      * @throws NotWritableDataStoreException
 140      */
 141     public function save();
 142
 143     /**
 144      * Returns the list tags appearing in the bookmarks with the given tags
 145      *
 146      * @param array  $filteringTags tags selecting the bookmarks to consider
 147      * @param string $visibility    process only all/private/public bookmarks
 148      *
 149      * @return array tag => bookmarksCount
 150      */
 151     public function bookmarksCountPerTag($filteringTags = [], $visibility = 'all');
 152
 153     /**
 154      * Returns the list of days containing articles (oldest first)
 155      *
 156      * @return array containing days (in format YYYYMMDD).
 157      */
 158     public function days();
 159
 160     /**
 161      * Returns the list of articles for a given day.
 162      *
 163      * @param string $request day to filter. Format: YYYYMMDD.
 164      *
 165      * @return Bookmark[] list of shaare found.
 166      *
 167      * @throws BookmarkNotFoundException
 168      */
 169     public function filterDay($request);
 170
 171     /**
 172      * Creates the default database after a fresh install.
 173      */
 174     public function initialize();
 175 }