X-Git-Url: https://git.immae.eu/?a=blobdiff_plain;f=application%2Fbookmark%2FBookmarkServiceInterface.php;fp=application%2Fbookmark%2FBookmarkServiceInterface.php;h=08cdbb4ed4055cc3f6ef2672b991f9c3b1cfeda7;hb=1409f1c89a7ca01456ae2dcd6357d296e2b99f5a;hp=b9b483eb8ae14ae70582ec5589eb67fd9f066558;hpb=054e03f37fa29da8066f1a637919f13c7e7dc5d2;p=github%2Fshaarli%2FShaarli.git

diff --git a/application/bookmark/BookmarkServiceInterface.php b/application/bookmark/BookmarkServiceInterface.php
index b9b483eb..08cdbb4e 100644
--- a/application/bookmark/BookmarkServiceInterface.php
+++ b/application/bookmark/BookmarkServiceInterface.php
@@ -1,79 +1,73 @@
 <?php
 
-namespace Shaarli\Bookmark;
+declare(strict_types=1);
 
+namespace Shaarli\Bookmark;
 
 use Shaarli\Bookmark\Exception\BookmarkNotFoundException;
 use Shaarli\Bookmark\Exception\NotWritableDataStoreException;
-use Shaarli\Config\ConfigManager;
-use Shaarli\History;
 
 /**
  * Class BookmarksService
  *
  * This is the entry point to manipulate the bookmark DB.
+ *
+ * Regarding return types of a list of bookmarks, it can either be an array or an ArrayAccess implementation,
+ * so until PHP 8.0 is the minimal supported version with union return types it cannot be explicitly added.
  */
 interface BookmarkServiceInterface
 {
-    /**
-     * BookmarksService constructor.
-     *
-     * @param ConfigManager $conf       instance
-     * @param History       $history    instance
-     * @param bool          $isLoggedIn true if the current user is logged in
-     */
-    public function __construct(ConfigManager $conf, History $history, $isLoggedIn);
-
     /**
      * Find a bookmark by hash
      *
-     * @param string $hash
+     * @param string      $hash       Bookmark's hash
+     * @param string|null $privateKey Optional key used to access private links while logged out
      *
-     * @return mixed
+     * @return Bookmark
      *
      * @throws \Exception
      */
-    public function findByHash($hash);
+    public function findByHash(string $hash, string $privateKey = null);
 
     /**
      * @param $url
      *
      * @return Bookmark|null
      */
-    public function findByUrl($url);
+    public function findByUrl(string $url): ?Bookmark;
 
     /**
      * Search bookmarks
      *
-     * @param mixed  $request
-     * @param string $visibility
-     * @param bool   $caseSensitive
-     * @param bool   $untaggedOnly
-     * @param bool   $ignoreSticky
+     * @param array   $request
+     * @param ?string $visibility
+     * @param bool    $caseSensitive
+     * @param bool    $untaggedOnly
+     * @param bool    $ignoreSticky
      *
      * @return Bookmark[]
      */
     public function search(
-        $request = [],
-        $visibility = null,
-        $caseSensitive = false,
-        $untaggedOnly = false,
+        array $request = [],
+        string $visibility = null,
+        bool $caseSensitive = false,
+        bool $untaggedOnly = false,
         bool $ignoreSticky = false
     );
 
     /**
      * Get a single bookmark by its ID.
      *
-     * @param int    $id         Bookmark ID
-     * @param string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an
-     *                           exception
+     * @param int    $id          Bookmark ID
+     * @param ?string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an
+     *                            exception
      *
      * @return Bookmark
      *
      * @throws BookmarkNotFoundException
      * @throws \Exception
      */
-    public function get($id, $visibility = null);
+    public function get(int $id, string $visibility = null);
 
     /**
      * Updates an existing bookmark (depending on its ID).
@@ -86,7 +80,7 @@ interface BookmarkServiceInterface
      * @throws BookmarkNotFoundException
      * @throws \Exception
      */
-    public function set($bookmark, $save = true);
+    public function set(Bookmark $bookmark, bool $save = true): Bookmark;
 
     /**
      * Adds a new bookmark (the ID must be empty).
@@ -98,7 +92,7 @@ interface BookmarkServiceInterface
      *
      * @throws \Exception
      */
-    public function add($bookmark, $save = true);
+    public function add(Bookmark $bookmark, bool $save = true): Bookmark;
 
     /**
      * Adds or updates a bookmark depending on its ID:
@@ -112,7 +106,7 @@ interface BookmarkServiceInterface
      *
      * @throws \Exception
      */
-    public function addOrSet($bookmark, $save = true);
+    public function addOrSet(Bookmark $bookmark, bool $save = true): Bookmark;
 
     /**
      * Deletes a bookmark.
@@ -122,65 +116,72 @@ interface BookmarkServiceInterface
      *
      * @throws \Exception
      */
-    public function remove($bookmark, $save = true);
+    public function remove(Bookmark $bookmark, bool $save = true): void;
 
     /**
      * Get a single bookmark by its ID.
      *
-     * @param int    $id         Bookmark ID
-     * @param string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an
-     *                           exception
+     * @param int     $id         Bookmark ID
+     * @param ?string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an
+     *                            exception
      *
      * @return bool
      */
-    public function exists($id, $visibility = null);
+    public function exists(int $id, string $visibility = null): bool;
 
     /**
      * Return the number of available bookmarks for given visibility.
      *
-     * @param string $visibility public|private|all
+     * @param ?string $visibility public|private|all
      *
      * @return int Number of bookmarks
      */
-    public function count($visibility = null);
+    public function count(string $visibility = null): int;
 
     /**
      * Write the datastore.
      *
      * @throws NotWritableDataStoreException
      */
-    public function save();
+    public function save(): void;
 
     /**
      * Returns the list tags appearing in the bookmarks with the given tags
      *
-     * @param array  $filteringTags tags selecting the bookmarks to consider
-     * @param string $visibility    process only all/private/public bookmarks
+     * @param array|null  $filteringTags tags selecting the bookmarks to consider
+     * @param string|null $visibility    process only all/private/public bookmarks
      *
      * @return array tag => bookmarksCount
      */
-    public function bookmarksCountPerTag($filteringTags = [], $visibility = 'all');
+    public function bookmarksCountPerTag(array $filteringTags = [], ?string $visibility = null): array;
 
     /**
-     * Returns the list of days containing articles (oldest first)
+     * Return a list of bookmark matching provided period of time.
+     * It also update directly previous and next date outside of given period found in the datastore.
+     *
+     * @param \DateTimeInterface      $from     Starting date.
+     * @param \DateTimeInterface      $to       Ending date.
+     * @param \DateTimeInterface|null $previous (by reference) updated with first created date found before $from.
+     * @param \DateTimeInterface|null $next     (by reference) updated with first created date found after $to.
      *
-     * @return array containing days (in format YYYYMMDD).
+     * @return array List of bookmarks matching provided period of time.
      */
-    public function days();
+    public function findByDate(
+        \DateTimeInterface $from,
+        \DateTimeInterface $to,
+        ?\DateTimeInterface &$previous,
+        ?\DateTimeInterface &$next
+    ): array;
 
     /**
-     * Returns the list of articles for a given day.
+     * Returns the latest bookmark by creation date.
      *
-     * @param string $request day to filter. Format: YYYYMMDD.
-     *
-     * @return Bookmark[] list of shaare found.
-     *
-     * @throws BookmarkNotFoundException
+     * @return Bookmark|null Found Bookmark or null if the datastore is empty.
      */
-    public function filterDay($request);
+    public function getLatest(): ?Bookmark;
 
     /**
      * Creates the default database after a fresh install.
      */
-    public function initialize();
+    public function initialize(): void;
 }