application/bookmark/BookmarkServiceInterface.php

   1 <?php
   2
   3 declare(strict_types=1);
   4
   5 namespace Shaarli\Bookmark;
   6
   7 use Shaarli\Bookmark\Exception\BookmarkNotFoundException;
   8 use Shaarli\Bookmark\Exception\NotWritableDataStoreException;
   9
  10 /**
  11  * Class BookmarksService
  12  *
  13  * This is the entry point to manipulate the bookmark DB.
  14  *
  15  * Regarding return types of a list of bookmarks, it can either be an array or an ArrayAccess implementation,
  16  * so until PHP 8.0 is the minimal supported version with union return types it cannot be explicitly added.
  17  */
  18 interface BookmarkServiceInterface
  19 {
  20     /**
  21      * Find a bookmark by hash
  22      *
  23      * @param string      $hash       Bookmark's hash
  24      * @param string|null $privateKey Optional key used to access private links while logged out
  25      *
  26      * @return Bookmark
  27      *
  28      * @throws \Exception
  29      */
  30     public function findByHash(string $hash, string $privateKey = null);
  31
  32     /**
  33      * @param $url
  34      *
  35      * @return Bookmark|null
  36      */
  37     public function findByUrl(string $url): ?Bookmark;
  38
  39     /**
  40      * Search bookmarks
  41      *
  42      * @param array   $request
  43      * @param ?string $visibility
  44      * @param bool    $caseSensitive
  45      * @param bool    $untaggedOnly
  46      * @param bool    $ignoreSticky
  47      * @param array   $pagination     This array can contain the following keys for pagination: limit, offset.
  48      *
  49      * @return SearchResult
  50      */
  51     public function search(
  52         array $request = [],
  53         string $visibility = null,
  54         bool $caseSensitive = false,
  55         bool $untaggedOnly = false,
  56         bool $ignoreSticky = false,
  57         array $pagination = []
  58     ): SearchResult;
  59
  60     /**
  61      * Get a single bookmark by its ID.
  62      *
  63      * @param int    $id          Bookmark ID
  64      * @param ?string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an
  65      *                            exception
  66      *
  67      * @return Bookmark
  68      *
  69      * @throws BookmarkNotFoundException
  70      * @throws \Exception
  71      */
  72     public function get(int $id, string $visibility = null);
  73
  74     /**
  75      * Updates an existing bookmark (depending on its ID).
  76      *
  77      * @param Bookmark $bookmark
  78      * @param bool     $save Writes to the datastore if set to true
  79      *
  80      * @return Bookmark Updated bookmark
  81      *
  82      * @throws BookmarkNotFoundException
  83      * @throws \Exception
  84      */
  85     public function set(Bookmark $bookmark, bool $save = true): Bookmark;
  86
  87     /**
  88      * Adds a new bookmark (the ID must be empty).
  89      *
  90      * @param Bookmark $bookmark
  91      * @param bool     $save Writes to the datastore if set to true
  92      *
  93      * @return Bookmark new bookmark
  94      *
  95      * @throws \Exception
  96      */
  97     public function add(Bookmark $bookmark, bool $save = true): Bookmark;
  98
  99     /**
 100      * Adds or updates a bookmark depending on its ID:
 101      *   - a Bookmark without ID will be added
 102      *   - a Bookmark with an existing ID will be updated
 103      *
 104      * @param Bookmark $bookmark
 105      * @param bool     $save
 106      *
 107      * @return Bookmark
 108      *
 109      * @throws \Exception
 110      */
 111     public function addOrSet(Bookmark $bookmark, bool $save = true): Bookmark;
 112
 113     /**
 114      * Deletes a bookmark.
 115      *
 116      * @param Bookmark $bookmark
 117      * @param bool     $save
 118      *
 119      * @throws \Exception
 120      */
 121     public function remove(Bookmark $bookmark, bool $save = true): void;
 122
 123     /**
 124      * Get a single bookmark by its ID.
 125      *
 126      * @param int     $id         Bookmark ID
 127      * @param ?string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an
 128      *                            exception
 129      *
 130      * @return bool
 131      */
 132     public function exists(int $id, string $visibility = null): bool;
 133
 134     /**
 135      * Return the number of available bookmarks for given visibility.
 136      *
 137      * @param ?string $visibility public|private|all
 138      *
 139      * @return int Number of bookmarks
 140      */
 141     public function count(string $visibility = null): int;
 142
 143     /**
 144      * Write the datastore.
 145      *
 146      * @throws NotWritableDataStoreException
 147      */
 148     public function save(): void;
 149
 150     /**
 151      * Returns the list tags appearing in the bookmarks with the given tags
 152      *
 153      * @param array|null  $filteringTags tags selecting the bookmarks to consider
 154      * @param string|null $visibility    process only all/private/public bookmarks
 155      *
 156      * @return array tag => bookmarksCount
 157      */
 158     public function bookmarksCountPerTag(array $filteringTags = [], ?string $visibility = null): array;
 159
 160     /**
 161      * Return a list of bookmark matching provided period of time.
 162      * It also update directly previous and next date outside of given period found in the datastore.
 163      *
 164      * @param \DateTimeInterface      $from     Starting date.
 165      * @param \DateTimeInterface      $to       Ending date.
 166      * @param \DateTimeInterface|null $previous (by reference) updated with first created date found before $from.
 167      * @param \DateTimeInterface|null $next     (by reference) updated with first created date found after $to.
 168      *
 169      * @return array List of bookmarks matching provided period of time.
 170      */
 171     public function findByDate(
 172         \DateTimeInterface $from,
 173         \DateTimeInterface $to,
 174         ?\DateTimeInterface &$previous,
 175         ?\DateTimeInterface &$next
 176     ): array;
 177
 178     /**
 179      * Returns the latest bookmark by creation date.
 180      *
 181      * @return Bookmark|null Found Bookmark or null if the datastore is empty.
 182      */
 183     public function getLatest(): ?Bookmark;
 184
 185     /**
 186      * Creates the default database after a fresh install.
 187      */
 188     public function initialize(): void;
 189 }