2019-05-25 15:46:47 +02:00
|
|
|
<?php
|
|
|
|
|
2020-10-02 17:50:59 +02:00
|
|
|
declare(strict_types=1);
|
2019-05-25 15:46:47 +02:00
|
|
|
|
2020-10-02 17:50:59 +02:00
|
|
|
namespace Shaarli\Bookmark;
|
2019-05-25 15:46:47 +02:00
|
|
|
|
|
|
|
use Shaarli\Bookmark\Exception\BookmarkNotFoundException;
|
|
|
|
use Shaarli\Bookmark\Exception\NotWritableDataStoreException;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Class BookmarksService
|
|
|
|
*
|
|
|
|
* This is the entry point to manipulate the bookmark DB.
|
2020-10-02 17:50:59 +02:00
|
|
|
*
|
|
|
|
* 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.
|
2019-05-25 15:46:47 +02:00
|
|
|
*/
|
|
|
|
interface BookmarkServiceInterface
|
|
|
|
{
|
|
|
|
/**
|
|
|
|
* Find a bookmark by hash
|
|
|
|
*
|
2020-10-16 20:17:08 +02:00
|
|
|
* @param string $hash Bookmark's hash
|
|
|
|
* @param string|null $privateKey Optional key used to access private links while logged out
|
2019-05-25 15:46:47 +02:00
|
|
|
*
|
2020-10-02 17:50:59 +02:00
|
|
|
* @return Bookmark
|
2019-05-25 15:46:47 +02:00
|
|
|
*
|
|
|
|
* @throws \Exception
|
|
|
|
*/
|
2020-10-16 20:17:08 +02:00
|
|
|
public function findByHash(string $hash, string $privateKey = null);
|
2019-05-25 15:46:47 +02:00
|
|
|
|
|
|
|
/**
|
|
|
|
* @param $url
|
|
|
|
*
|
|
|
|
* @return Bookmark|null
|
|
|
|
*/
|
2020-10-02 17:50:59 +02:00
|
|
|
public function findByUrl(string $url): ?Bookmark;
|
2019-05-25 15:46:47 +02:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Search bookmarks
|
|
|
|
*
|
2020-10-02 17:50:59 +02:00
|
|
|
* @param array $request
|
|
|
|
* @param ?string $visibility
|
|
|
|
* @param bool $caseSensitive
|
|
|
|
* @param bool $untaggedOnly
|
|
|
|
* @param bool $ignoreSticky
|
2019-05-25 15:46:47 +02:00
|
|
|
*
|
|
|
|
* @return Bookmark[]
|
|
|
|
*/
|
2020-08-29 10:06:40 +02:00
|
|
|
public function search(
|
2020-10-02 17:50:59 +02:00
|
|
|
array $request = [],
|
|
|
|
string $visibility = null,
|
|
|
|
bool $caseSensitive = false,
|
|
|
|
bool $untaggedOnly = false,
|
2020-08-29 10:06:40 +02:00
|
|
|
bool $ignoreSticky = false
|
|
|
|
);
|
2019-05-25 15:46:47 +02:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Get a single bookmark by its ID.
|
|
|
|
*
|
2020-10-02 17:50:59 +02:00
|
|
|
* @param int $id Bookmark ID
|
|
|
|
* @param ?string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an
|
|
|
|
* exception
|
2019-05-25 15:46:47 +02:00
|
|
|
*
|
|
|
|
* @return Bookmark
|
|
|
|
*
|
|
|
|
* @throws BookmarkNotFoundException
|
|
|
|
* @throws \Exception
|
|
|
|
*/
|
2020-10-02 17:50:59 +02:00
|
|
|
public function get(int $id, string $visibility = null);
|
2019-05-25 15:46:47 +02:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Updates an existing bookmark (depending on its ID).
|
|
|
|
*
|
|
|
|
* @param Bookmark $bookmark
|
|
|
|
* @param bool $save Writes to the datastore if set to true
|
|
|
|
*
|
|
|
|
* @return Bookmark Updated bookmark
|
|
|
|
*
|
|
|
|
* @throws BookmarkNotFoundException
|
|
|
|
* @throws \Exception
|
|
|
|
*/
|
2020-10-02 17:50:59 +02:00
|
|
|
public function set(Bookmark $bookmark, bool $save = true): Bookmark;
|
2019-05-25 15:46:47 +02:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Adds a new bookmark (the ID must be empty).
|
|
|
|
*
|
|
|
|
* @param Bookmark $bookmark
|
|
|
|
* @param bool $save Writes to the datastore if set to true
|
|
|
|
*
|
|
|
|
* @return Bookmark new bookmark
|
|
|
|
*
|
|
|
|
* @throws \Exception
|
|
|
|
*/
|
2020-10-02 17:50:59 +02:00
|
|
|
public function add(Bookmark $bookmark, bool $save = true): Bookmark;
|
2019-05-25 15:46:47 +02:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Adds or updates a bookmark depending on its ID:
|
|
|
|
* - a Bookmark without ID will be added
|
|
|
|
* - a Bookmark with an existing ID will be updated
|
|
|
|
*
|
|
|
|
* @param Bookmark $bookmark
|
|
|
|
* @param bool $save
|
|
|
|
*
|
|
|
|
* @return Bookmark
|
|
|
|
*
|
|
|
|
* @throws \Exception
|
|
|
|
*/
|
2020-10-02 17:50:59 +02:00
|
|
|
public function addOrSet(Bookmark $bookmark, bool $save = true): Bookmark;
|
2019-05-25 15:46:47 +02:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Deletes a bookmark.
|
|
|
|
*
|
|
|
|
* @param Bookmark $bookmark
|
|
|
|
* @param bool $save
|
|
|
|
*
|
|
|
|
* @throws \Exception
|
|
|
|
*/
|
2020-10-02 17:50:59 +02:00
|
|
|
public function remove(Bookmark $bookmark, bool $save = true): void;
|
2019-05-25 15:46:47 +02:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Get a single bookmark by its ID.
|
|
|
|
*
|
2020-10-02 17:50:59 +02:00
|
|
|
* @param int $id Bookmark ID
|
|
|
|
* @param ?string $visibility all|public|private e.g. with public, accessing a private bookmark will throw an
|
|
|
|
* exception
|
2019-05-25 15:46:47 +02:00
|
|
|
*
|
|
|
|
* @return bool
|
|
|
|
*/
|
2020-10-02 17:50:59 +02:00
|
|
|
public function exists(int $id, string $visibility = null): bool;
|
2019-05-25 15:46:47 +02:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Return the number of available bookmarks for given visibility.
|
|
|
|
*
|
2020-10-02 17:50:59 +02:00
|
|
|
* @param ?string $visibility public|private|all
|
2019-05-25 15:46:47 +02:00
|
|
|
*
|
|
|
|
* @return int Number of bookmarks
|
|
|
|
*/
|
2020-10-02 17:50:59 +02:00
|
|
|
public function count(string $visibility = null): int;
|
2019-05-25 15:46:47 +02:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Write the datastore.
|
|
|
|
*
|
|
|
|
* @throws NotWritableDataStoreException
|
|
|
|
*/
|
2020-10-02 17:50:59 +02:00
|
|
|
public function save(): void;
|
2019-05-25 15:46:47 +02:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns the list tags appearing in the bookmarks with the given tags
|
|
|
|
*
|
2020-10-02 17:50:59 +02:00
|
|
|
* @param array|null $filteringTags tags selecting the bookmarks to consider
|
|
|
|
* @param string|null $visibility process only all/private/public bookmarks
|
2019-05-25 15:46:47 +02:00
|
|
|
*
|
|
|
|
* @return array tag => bookmarksCount
|
|
|
|
*/
|
2020-10-02 17:50:59 +02:00
|
|
|
public function bookmarksCountPerTag(array $filteringTags = [], ?string $visibility = null): array;
|
2019-05-25 15:46:47 +02:00
|
|
|
|
|
|
|
/**
|
2020-10-16 11:50:53 +02:00
|
|
|
* 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.
|
2019-05-25 15:46:47 +02:00
|
|
|
*
|
2020-10-16 11:50:53 +02:00
|
|
|
* @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 List of bookmarks matching provided period of time.
|
2019-05-25 15:46:47 +02:00
|
|
|
*/
|
2020-10-16 11:50:53 +02:00
|
|
|
public function findByDate(
|
|
|
|
\DateTimeInterface $from,
|
|
|
|
\DateTimeInterface $to,
|
|
|
|
?\DateTimeInterface &$previous,
|
|
|
|
?\DateTimeInterface &$next
|
|
|
|
): array;
|
2019-05-25 15:46:47 +02:00
|
|
|
|
|
|
|
/**
|
2020-10-16 11:50:53 +02:00
|
|
|
* Returns the latest bookmark by creation date.
|
2019-05-25 15:46:47 +02:00
|
|
|
*
|
2020-10-16 11:50:53 +02:00
|
|
|
* @return Bookmark|null Found Bookmark or null if the datastore is empty.
|
2019-05-25 15:46:47 +02:00
|
|
|
*/
|
2020-10-16 11:50:53 +02:00
|
|
|
public function getLatest(): ?Bookmark;
|
2019-05-25 15:46:47 +02:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Creates the default database after a fresh install.
|
|
|
|
*/
|
2020-10-02 17:50:59 +02:00
|
|
|
public function initialize(): void;
|
2019-05-25 15:46:47 +02:00
|
|
|
}
|