3 files changed, 163 insertions, 13 deletions

diff --git a/application/bookmark/BookmarkFileService.php b/application/bookmark/BookmarkFileService.php
index 6666a251..8ea37427 100644
--- a/application/bookmark/BookmarkFileService.php
+++ b/application/bookmark/BookmarkFileService.php
@@ -55,8 +55,12 @@ class BookmarkFileService implements BookmarkServiceInterface
     /**
      * @inheritDoc
      */
-    public function __construct(ConfigManager $conf, History $history, Mutex $mutex, bool $isLoggedIn)
-    {
+    public function __construct(
+        ConfigManager $conf,
+        History $history,
+        Mutex $mutex,
+        bool $isLoggedIn
+    ) {
         $this->conf = $conf;
         $this->history = $history;
         $this->mutex = $mutex;
@@ -129,8 +133,9 @@ class BookmarkFileService implements BookmarkServiceInterface
         string $visibility = null,
         bool $caseSensitive = false,
         bool $untaggedOnly = false,
-        bool $ignoreSticky = false
-    ) {
+        bool $ignoreSticky = false,
+        array $pagination = []
+    ): SearchResult {
         if ($visibility === null) {
             $visibility = $this->isLoggedIn ? BookmarkFilter::$ALL : BookmarkFilter::$PUBLIC;
         }
@@ -143,13 +148,20 @@ class BookmarkFileService implements BookmarkServiceInterface
             $this->bookmarks->reorder('DESC', true);
         }
 
-        return $this->bookmarkFilter->filter(
+        $bookmarks = $this->bookmarkFilter->filter(
             BookmarkFilter::$FILTER_TAG | BookmarkFilter::$FILTER_TEXT,
             [$searchTags, $searchTerm],
             $caseSensitive,
             $visibility,
             $untaggedOnly
         );
+
+        return SearchResult::getSearchResult(
+            $bookmarks,
+            $pagination['offset'] ?? 0,
+            $pagination['limit'] ?? null,
+            $pagination['allowOutOfBounds'] ?? false
+        );
     }
 
     /**
@@ -282,7 +294,7 @@ class BookmarkFileService implements BookmarkServiceInterface
      */
     public function count(string $visibility = null): int
     {
-        return count($this->search([], $visibility));
+        return $this->search([], $visibility)->getResultCount();
     }
 
     /**
@@ -305,10 +317,10 @@ class BookmarkFileService implements BookmarkServiceInterface
      */
     public function bookmarksCountPerTag(array $filteringTags = [], string $visibility = null): array
     {
-        $bookmarks = $this->search(['searchtags' => $filteringTags], $visibility);
+        $searchResult = $this->search(['searchtags' => $filteringTags], $visibility);
         $tags = [];
         $caseMapping = [];
-        foreach ($bookmarks as $bookmark) {
+        foreach ($searchResult->getBookmarks() as $bookmark) {
             foreach ($bookmark->getTags() as $tag) {
                 if (
                     empty($tag)
@@ -357,7 +369,7 @@ class BookmarkFileService implements BookmarkServiceInterface
         $previous = null;
         $next = null;
 
-        foreach ($this->search([], null, false, false, true) as $bookmark) {
+        foreach ($this->search([], null, false, false, true)->getBookmarks() as $bookmark) {
             if ($to < $bookmark->getCreated()) {
                 $next = $bookmark->getCreated();
             } elseif ($from < $bookmark->getCreated() && $to > $bookmark->getCreated()) {
@@ -378,7 +390,7 @@ class BookmarkFileService implements BookmarkServiceInterface
      */
     public function getLatest(): ?Bookmark
     {
-        foreach ($this->search([], null, false, false, true) as $bookmark) {
+        foreach ($this->search([], null, false, false, true)->getBookmarks() as $bookmark) {
             return $bookmark;
         }
 
diff --git a/application/bookmark/BookmarkServiceInterface.php b/application/bookmark/BookmarkServiceInterface.php
index 08cdbb4e..4b1f0daa 100644
--- a/application/bookmark/BookmarkServiceInterface.php
+++ b/application/bookmark/BookmarkServiceInterface.php
@@ -44,16 +44,18 @@ interface BookmarkServiceInterface
      * @param bool    $caseSensitive
      * @param bool    $untaggedOnly
      * @param bool    $ignoreSticky
+     * @param array   $pagination     This array can contain the following keys for pagination: limit, offset.
      *
-     * @return Bookmark[]
+     * @return SearchResult
      */
     public function search(
         array $request = [],
         string $visibility = null,
         bool $caseSensitive = false,
         bool $untaggedOnly = false,
-        bool $ignoreSticky = false
-    );
+        bool $ignoreSticky = false,
+        array $pagination = []
+    ): SearchResult;
 
     /**
      * Get a single bookmark by its ID.
diff --git a/application/bookmark/SearchResult.php b/application/bookmark/SearchResult.php
new file mode 100644
index 00000000..c0bce311
--- /dev/null
+++ b/application/bookmark/SearchResult.php
@@ -0,0 +1,136 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shaarli\Bookmark;
+
+/**
+ * Read-only class used to represent search result, including pagination.
+ */
+class SearchResult
+{
+    /** @var Bookmark[] List of result bookmarks with pagination applied */
+    protected $bookmarks;
+
+    /** @var int number of Bookmarks found, with pagination applied */
+    protected $resultCount;
+
+    /** @var int total number of result found */
+    protected $totalCount;
+
+    /** @var int pagination: limit number of result bookmarks */
+    protected $limit;
+
+    /** @var int pagination: offset to apply to complete result list */
+    protected $offset;
+
+    public function __construct(array $bookmarks, int $totalCount, int $offset, ?int $limit)
+    {
+        $this->bookmarks = $bookmarks;
+        $this->resultCount = count($bookmarks);
+        $this->totalCount = $totalCount;
+        $this->limit = $limit;
+        $this->offset = $offset;
+    }
+
+    /**
+     * Build a SearchResult from provided full result set and pagination settings.
+     *
+     * @param Bookmark[] $bookmarks        Full set of result which will be filtered
+     * @param int        $offset           Start recording results from $offset
+     * @param int|null   $limit            End recording results after $limit bookmarks is reached
+     * @param bool       $allowOutOfBounds Set to false to display the last page if the offset is out of bound,
+     *                                     return empty result set otherwise (default: false)
+     *
+     * @return SearchResult
+     */
+    public static function getSearchResult(
+        $bookmarks,
+        int $offset = 0,
+        ?int $limit = null,
+        bool $allowOutOfBounds = false
+    ): self {
+        $totalCount = count($bookmarks);
+        if (!$allowOutOfBounds && $offset > $totalCount) {
+            $offset = $limit === null ? 0 : $limit * -1;
+        }
+
+        if ($bookmarks instanceof BookmarkArray) {
+            $buffer = [];
+            foreach ($bookmarks as $key => $value) {
+                $buffer[$key] = $value;
+            }
+            $bookmarks = $buffer;
+        }
+
+        return new static(
+            array_slice($bookmarks, $offset, $limit, true),
+            $totalCount,
+            $offset,
+            $limit
+        );
+    }
+
+    /** @return Bookmark[] List of result bookmarks with pagination applied */
+    public function getBookmarks(): array
+    {
+        return $this->bookmarks;
+    }
+
+    /** @return int number of Bookmarks found, with pagination applied */
+    public function getResultCount(): int
+    {
+        return $this->resultCount;
+    }
+
+    /** @return int total number of result found */
+    public function getTotalCount(): int
+    {
+        return $this->totalCount;
+    }
+
+    /** @return int pagination: limit number of result bookmarks */
+    public function getLimit(): ?int
+    {
+        return $this->limit;
+    }
+
+    /** @return int pagination: offset to apply to complete result list */
+    public function getOffset(): int
+    {
+        return $this->offset;
+    }
+
+    /** @return int Current page of result set in complete results */
+    public function getPage(): int
+    {
+        if (empty($this->limit)) {
+            return $this->offset === 0 ? 1 : 2;
+        }
+        $base = $this->offset >= 0 ? $this->offset : $this->totalCount + $this->offset;
+
+        return (int) ceil($base / $this->limit) + 1;
+    }
+
+    /** @return int Get the # of the last page */
+    public function getLastPage(): int
+    {
+        if (empty($this->limit)) {
+            return $this->offset === 0 ? 1 : 2;
+        }
+
+        return (int) ceil($this->totalCount / $this->limit);
+    }
+
+    /** @return bool Either the current page is the last one or not */
+    public function isLastPage(): bool
+    {
+        return $this->getPage() === $this->getLastPage();
+    }
+
+    /** @return bool Either the current page is the first one or not */
+    public function isFirstPage(): bool
+    {
+        return $this->offset === 0;
+    }
+}