> 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/usage.md).

# Usage

## Paginate an array

Use the array adapter when the full result set is already in memory.

```php
use Quantum\Paginator\Enums\PaginatorType;
use Quantum\Paginator\Factories\PaginatorFactory;

$paginator = PaginatorFactory::create(PaginatorType::ARRAY, [
    'items' => $users,
    'perPage' => 25,
    'page' => 1,
]);

return view('users/index', [
    'users' => $paginator->data(),
    'pagination' => $paginator->getPagination(),
]);
```

## Paginate a model query

Use the model adapter after you finish building the query.

```php
use Quantum\Paginator\Enums\PaginatorType;
use Quantum\Paginator\Factories\PaginatorFactory;

$postModel = $postModel
    ->criteria('status', '=', 'published')
    ->orderBy('id', 'desc');

$paginator = PaginatorFactory::create(PaginatorType::MODEL, [
    'model' => $postModel,
    'perPage' => 10,
    'page' => 2,
]);

$posts = $paginator->data();
```

The key rule is order of operations: prepare filters and sorting first, then create the paginator.

The paginator captures `total()` when you create it and reuses the same model instance for page data. If you add more criteria after construction, create a fresh paginator so the row count and page slice stay aligned.

## Read navigation metadata

The same calls work for both adapters.

```php
$currentPage = $paginator->currentPageNumber();
$lastPage = $paginator->lastPageNumber();
$total = $paginator->total();
$links = $paginator->links();
```

Use this when you want to render your own pagination UI instead of the built-in HTML.

## Generate relative or absolute links

By default, link methods return request-relative URLs.

```php
$current = $paginator->currentPageLink();
$next = $paginator->nextPageLink();
```

Pass `true` when you need links prefixed with the application base URL.

```php
$absoluteLinks = $paginator->links(true);
```

For a full set of absolute navigation links, prefer the direct link helpers or `links(true)`. The built-in HTML renderer keeps its previous and next controls request-relative.

## Use the built-in HTML renderer

`getPagination()` returns a ready-to-render `<ul>` only when there is more than one page.

```php
$pagination = $paginator->getPagination();

if ($pagination !== null) {
    echo $pagination;
}
```

You can also control the visible page window size.

```php
echo $paginator->getPagination(false, 5);
```

Values below `3` are treated as `3`.

## Common pitfalls

### Do not expect automatic page correction

If the requested page is outside the available range, the paginator does not snap it back to the first or last page for you.

Handle that at the request-validation or controller level if your application needs strict bounds.

### Know the boundary link behavior

Direct page-link helpers mirror the page-number methods.

That means:

* `previousPageLink()` on page `1` points to page `1`
* `nextPageLink()` on the last page points to the last page

The built-in HTML renderer avoids showing previous and next buttons at those boundaries, but direct helper calls still return those links.

### Avoid repeated page fetch calls in the same render path

`data()`, `firstItem()`, and `lastItem()` can trigger their own data retrieval work.

Fetch once and reuse the result when possible, especially with the model adapter.

### Use built-in HTML only in request-aware contexts

Pagination URLs come from the current request URI. If there is no meaningful request context, generate your own links instead of relying on `getPagination()` or the page-link helpers.


---

# 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/usage.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.