<?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).
* @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).
*
* @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:
*
* @throws \Exception
*/
- public function addOrSet($bookmark, $save = true);
+ public function addOrSet(Bookmark $bookmark, bool $save = true): Bookmark;
/**
* Deletes a bookmark.
*
* @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;
}
projects / github / shaarli / Shaarli.git / blobdiff