T14754 paginator cursor

CHANGELOG-5.0.md

@@ -32,6 +32,7 @@
 - Added `Phalcon\Html\Helper\Script::beginInternal()` and `endInternal(array $attributes = [], int $pos = -1)` to capture inline JavaScript via output buffering and append it to the asset stack as a `<script>...</script>` block [#16971](https://github.com/phalcon/cphalcon/issues/16971)
 - Added `Phalcon\Html\Helper\Tag` (open tag) and `Phalcon\Html\Helper\VoidTag` (self-closing tag) as escape hatches for arbitrary tag names without a dedicated helper; available via `TagFactory` as `tag` and `voidTag` [#16971](https://github.com/phalcon/cphalcon/issues/16971)
 - Added `Phalcon\Mvc\Router::getMethodRoutes(): array` — returns the internal HTTP-method index (routes bucketed by method string, unconstrained routes under `"*"`). `handle()` now builds a candidate list from only the matching-method bucket plus the unconstrained bucket and iterates that subset in reverse, eliminating the O(n) per-route HTTP-method check that previously ran against every registered route on each request [#17015](https://github.com/phalcon/cphalcon/issues/17015)
+- Added `Phalcon\Paginator\Adapter\QueryBuilderCursor` — a keyset (cursor-based) pagination adapter that accepts a `QueryBuilder`, a `limit`, and a `cursorColumn` (the column used as the cursor key, typically a primary key). Each `paginate()` call fetches `limit + 1` rows using `cursorColumn > :cursor:` to skip already-seen rows; the extra row is used only to detect whether a next page exists and is never returned. `getNext()` returns the last visible row's cursor value, or `0` when no further page exists. `setCursor(int|null $cursor)` advances or resets the position. `getTotalItems()` and `getLast()` return `0` by design — no COUNT query is issued. Registered in `PaginatorFactory` as `"queryBuilderCursor"` [#14754](https://github.com/phalcon/cphalcon/issues/14754)
 - Added `Phalcon\Support\Collection:column(string $propertyOrMethod): array` (lift a single property/method off every item, keyed by the original collection key) [#17000](https://github.com/phalcon/cphalcon/issues/17000)
 - Added `Phalcon\Support\Collection:each(callable $callback)` (run the callback for side effects and return `$this` for chaining) [#17000](https://github.com/phalcon/cphalcon/issues/17000)
 - Added `Phalcon\Support\Collection:filter(callable $callback)` (new collection of items where the callback returns truthy) [#17000](https://github.com/phalcon/cphalcon/issues/17000)

phalcon/Contracts/Paginator/Adapter.zep

@@ -0,0 +1,37 @@
+
+/**
+ * This file is part of the Phalcon Framework.
+ *
+ * (c) Phalcon Team <team@phalcon.io>
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+namespace Phalcon\Contracts\Paginator;
+
+/**
+ * Interface for Phalcon\Paginator adapters
+ */
+interface Adapter
+{
+    /**
+     * Get current rows limit
+     */
+    public function getLimit() -> int;
+
+    /**
+     * Returns a slice of the resultset to show in the pagination
+     */
+    public function paginate() -> <Repository>;
+
+    /**
+     * Set the current page number
+     */
+    public function setCurrentPage(int page);
+
+    /**
+     * Set current rows limit
+     */
+    public function setLimit(int limit);
+}

phalcon/Contracts/Paginator/Repository.zep

@@ -0,0 +1,106 @@
+
+/**
+ * This file is part of the Phalcon Framework.
+ *
+ * (c) Phalcon Team <team@phalcon.io>
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+namespace Phalcon\Contracts\Paginator;
+
+/**
+ * Interface for the repository of current state
+ * Phalcon\Paginator\AdapterInterface::paginate()
+ */
+interface Repository
+{
+    /**
+     * @var string
+     */
+    const PROPERTY_CURRENT_PAGE  = "current";
+    /**
+     * @var string
+     */
+    const PROPERTY_FIRST_PAGE    = "first";
+    /**
+     * @var string
+     */
+    const PROPERTY_ITEMS         = "items";
+    /**
+     * @var string
+     */
+    const PROPERTY_LAST_PAGE     = "last";
+    /**
+     * @var string
+     */
+    const PROPERTY_LIMIT         = "limit";
+    /**
+     * @var string
+     */
+    const PROPERTY_NEXT_PAGE     = "next";
+    /**
+     * @var string
+     */
+    const PROPERTY_PREVIOUS_PAGE = "previous";
+    /**
+     * @var string
+     */
+    const PROPERTY_TOTAL_ITEMS   = "total_items";
+
+    /**
+     * Gets the aliases for properties repository
+     */
+    public function getAliases() -> array;
+
+    /**
+     * Gets number of the current page
+     */
+    public function getCurrent() -> int;
+
+    /**
+     * Gets number of the first page
+     */
+    public function getFirst() -> int;
+
+    /**
+     * Gets the items on the current page
+     */
+    public function getItems() -> var;
+
+    /**
+     * Gets number of the last page
+     */
+    public function getLast() -> int;
+
+    /**
+     * Gets current rows limit
+     */
+    public function getLimit() -> int;
+
+    /**
+     * Gets number of the next page
+     */
+    public function getNext() -> int;
+
+    /**
+     * Gets number of the previous page
+     */
+    public function getPrevious() -> int;
+
+    /**
+     * Gets the total number of items
+     */
+    public function getTotalItems() -> int;
+
+    /**
+     * Sets the aliases for properties repository
+     */
+    public function setAliases(array aliases) -> <Repository>;
+
+    /**
+     * Sets values for properties of the repository
+     */
+    public function setProperties(array properties) -> <Repository>;
+}

phalcon/Paginator/Adapter/AdapterInterface.zep

@@ -10,32 +10,13 @@
 
 namespace Phalcon\Paginator\Adapter;
 
-use Phalcon\Paginator\RepositoryInterface;
+use Phalcon\Contracts\Paginator\Adapter as AdapterContract;
 
 /**
- * Phalcon\Paginator\AdapterInterface
- *
- * Interface for Phalcon\Paginator adapters
+ * @psalm-suppress DeprecatedInterface
+ * @deprecated Will be removed in a future major release.
+ *             Use {@see \Phalcon\Contracts\Paginator\Adapter} instead.
  */
-interface AdapterInterface
+interface AdapterInterface extends AdapterContract
 {
-    /**
-     * Get current rows limit
-     */
-    public function getLimit() -> int;
-
-    /**
-     * Returns a slice of the resultset to show in the pagination
-     */
-    public function paginate() -> <RepositoryInterface>;
-
-    /**
-     * Set the current page number
-     */
-    public function setCurrentPage(int page);
-
-    /**
-     * Set current rows limit
-     */
-    public function setLimit(int limit);
 }