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      *
  48      * @return Bookmark[]
  49      */
  50     public function search(
  51         array $request = [],
  52         string $visibility = null,
  53         bool $caseSensitive = false,
  54         bool $untaggedOnly = false,
  55         bool $ignoreSticky = false
  56     );
  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(int $id, string $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 $bookmark, bool $save = true): Bookmark;
  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 $bookmark, bool $save = true): Bookmark;
  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 $bookmark, bool $save = true): Bookmark;
 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 $bookmark, bool $save = true): void;
 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(int $id, string $visibility = null): bool;
 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(string $visibility = null): int;
 140
 141     /**
 142      * Write the datastore.
 143      *
 144      * @throws NotWritableDataStoreException
 145      */
 146     public function save(): void;
 147
 148     /**
 149      * Returns the list tags appearing in the bookmarks with the given tags
 150      *
 151      * @param array|null  $filteringTags tags selecting the bookmarks to consider
 152      * @param string|null $visibility    process only all/private/public bookmarks
 153      *
 154      * @return array tag => bookmarksCount
 155      */
 156     public function bookmarksCountPerTag(array $filteringTags = [], ?string $visibility = null): array;
 157
 158     /**
 159      * Return a list of bookmark matching provided period of time.
 160      * It also update directly previous and next date outside of given period found in the datastore.
 161      *
 162      * @param \DateTimeInterface      $from     Starting date.
 163      * @param \DateTimeInterface      $to       Ending date.
 164      * @param \DateTimeInterface|null $previous (by reference) updated with first created date found before $from.
 165      * @param \DateTimeInterface|null $next     (by reference) updated with first created date found after $to.
 166      *
 167      * @return array List of bookmarks matching provided period of time.
 168      */
 169     public function findByDate(
 170         \DateTimeInterface $from,
 171         \DateTimeInterface $to,
 172         ?\DateTimeInterface &$previous,
 173         ?\DateTimeInterface &$next
 174     ): array;
 175
 176     /**
 177      * Returns the latest bookmark by creation date.
 178      *
 179      * @return Bookmark|null Found Bookmark or null if the datastore is empty.
 180      */
 181     public function getLatest(): ?Bookmark;
 182
 183     /**
 184      * Creates the default database after a fresh install.
 185      */
 186     public function initialize(): void;
 187 }