> For the complete documentation index, see [llms.txt](https://quantumphp.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://quantumphp.gitbook.io/docs/packages/paginator/contracts.md).

# Contracts

## Factory contract

Create paginators through `Quantum\Paginator\Factories\PaginatorFactory::create(string $type, array $params)`.

The factory contract is strict:

* `$type` must be one of the built-in paginator types
* adapter-specific required parameters must be present
* `perPage` and `page` are optional because the factory injects defaults

Current required parameters are:

* `array` -> `items`
* `model` -> `model`

## Runtime API contract

The public wrapper is `Quantum\Paginator\Paginator`.

It guarantees these adapter methods:

* `data()`
* `firstItem()`
* `lastItem()`
* `currentPageNumber()`
* `previousPageNumber()`
* `nextPageNumber()`
* `lastPageNumber()`
* `currentPageLink()`
* `firstPageLink()`
* `previousPageLink()`
* `nextPageLink()`
* `lastPageLink()`
* `perPage()`
* `total()`
* `links()`
* `getPagination()`

## Page-number behavior

This package reports page numbers without clamping invalid input.

That leads to a few important edge cases:

* `currentPageNumber()` returns the page you passed in
* if you request a page beyond the last page, `data()` can be empty even though `currentPageNumber()` still reports that page
* on page `1`, `previousPageNumber()` returns `1`
* on the last page, `nextPageNumber()` returns the current page number instead of `null`

Those boundary values matter mostly when you call the page-number and page-link methods directly.

## Link-generation contract

Page links are derived from the current request URI.

The package:

* removes existing `page` and `per_page` query parameters
* keeps the rest of the current URI intact
* appends fresh `per_page=<value>&page=<value>` parameters
* prefixes the application base URL when `$withBaseUrl` is `true`

This makes pagination links request-aware. They are most useful during an active HTTP request.

## HTML output contract

`getPagination(bool $withBaseUrl = false, ?int $pageItemsCount = null)` returns:

* `null` when there is only one page or no pages
* a `<ul class="pagination">...</ul>` string when multiple pages exist

The generated HTML uses translation keys for the previous and next labels:

* `common.pagination.prev`
* `common.pagination.next`

If you rely on the built-in HTML output, make sure those translations exist in your loaded language files.

`$pageItemsCount` is normalized to a minimum of `3`, so smaller values do not reduce the visible page window below that threshold.

When you pass `true` to `getPagination()`, the numbered page links use absolute URLs. The previous, next, and jump-to-first links continue to use request-relative URLs, so use the direct link helpers when you need a fully absolute pagination bar.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://quantumphp.gitbook.io/docs/packages/paginator/contracts.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.