PHPackages                             tobento/service-pagination - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. tobento/service-pagination

ActiveLibrary[Utility & Helpers](/categories/utility)

tobento/service-pagination
==========================

Building pagination controls easily.

2.0(7mo ago)0462MITPHPPHP >=8.4

Since Oct 7Pushed 7mo ago1 watchersCompare

[ Source](https://github.com/tobento-ch/service-pagination)[ Packagist](https://packagist.org/packages/tobento/service-pagination)[ Docs](https://www.tobento.ch)[ RSS](/packages/tobento-service-pagination/feed)WikiDiscussions 2.x Synced 1mo ago

READMEChangelog (4)Dependencies (4)Versions (6)Used By (2)

Pagination Service
==================

[](#pagination-service)

The Pagination Service provides a way for building pagination controls easily.

Table of Contents
-----------------

[](#table-of-contents)

- [Getting started](#getting-started)
    - [Requirements](#requirements)
    - [Highlights](#highlights)
    - [Screenshots](#screenshots)
    - [Simple Example](#simple-example)
- [Documentation](#documentation)
    - [Create Pagination](#create-pagination)
    - [Pagination Data](#pagination-data)
    - [Current Page Verification](#current-page-verification)
    - [Render Pagination](#render-pagination)
        - [Menu Renderer](#menu-renderer)
        - [Custom Renderer](#custom-renderer)
    - [Url Generation](#url-generation)
        - [Default Url Generator](#default-url-generator)
        - [Custom Url Generator](#custom-url-generator)
- [Credits](#credits)

---

Getting started
===============

[](#getting-started)

Add the latest version of the Pagination service project running this command.

```
composer require tobento/service-pagination

```

Requirements
------------

[](#requirements)

- PHP 8.4 or greater

Highlights
----------

[](#highlights)

- Framework-agnostic, will work with any project
- Decoupled design
- Customize rendering
- Customize url generation

Screenshots
-----------

[](#screenshots)

[![](demo/pagination.png)](demo/pagination.png)
[![](demo/pagination-small.png)](demo/pagination-small.png)

Simple Example
--------------

[](#simple-example)

```
use Tobento\Service\Pagination\Pagination;

$pagination = new Pagination(
    totalItems: 200,
    currentPage: 3,
);
```

**Render the pagination**

```

// or just

```

Documentation
=============

[](#documentation)

Pagination
----------

[](#pagination)

### Create Pagination

[](#create-pagination)

```
use Tobento\Service\Pagination\Pagination;
use Tobento\Service\Pagination\PaginationInterface;
use Tobento\Service\Pagination\UrlGenerator;
use Tobento\Service\Pagination\MenuRenderer;

$pagination = new Pagination(
    totalItems: 200,
    currentPage: 3,
    itemsPerPage: 50,
    maxPagesToShow: 10,
    maxItemsPerPage: 1000,
    urlGenerator: new UrlGenerator()->addPageUrl('#{num}'),
    renderer: new MenuRenderer('prev', 'next'),
);

var_dump($pagination instanceof PaginationInterface);
// bool(true)
```

#### With Methods

[](#with-methods)

You might change some data or implentation by the following "with methods" returning a new instance.

**withTotalItems**

```
use Tobento\Service\Pagination\Pagination;

$pagination = new Pagination(totalItems: 200);

$newPagination = $pagination->withTotalItems(150);

var_dump($pagination === $newPagination);
// bool(false)
```

**withCurrentPage**

```
use Tobento\Service\Pagination\Pagination;

$pagination = new Pagination(totalItems: 200);

$newPagination = $pagination->withCurrentPage(6);

var_dump($pagination === $newPagination);
// bool(false)
```

**withItemsPerPage**

```
use Tobento\Service\Pagination\Pagination;

$pagination = new Pagination(totalItems: 200);

$newPagination = $pagination->withItemsPerPage(30);

var_dump($pagination === $newPagination);
// bool(false)
```

**withMaxPagesToShow**

```
use Tobento\Service\Pagination\Pagination;

$pagination = new Pagination(totalItems: 200);

$newPagination = $pagination->withMaxPagesToShow(6);

var_dump($pagination === $newPagination);
// bool(false)
```

**withUrlGenerator**

```
use Tobento\Service\Pagination\Pagination;
use Tobento\Service\Pagination\UrlGenerator;

$pagination = new Pagination(totalItems: 200);

$newPagination = $pagination->withUrlGenerator(new UrlGenerator());

var_dump($pagination === $newPagination);
// bool(false)
```

**withRenderer**

```
use Tobento\Service\Pagination\Pagination;
use Tobento\Service\Pagination\MenuRenderer;

$pagination = new Pagination(totalItems: 200);

$newPagination = $pagination->withRenderer(new MenuRenderer());

var_dump($pagination === $newPagination);
// bool(false)
```

### Pagination Data

[](#pagination-data)

You might need the following data for a custom renderer, verifying page number or limiting queries.

```
use Tobento\Service\Pagination\Pagination;
use Tobento\Service\Pagination\PageInterface;

$pagination = new Pagination(
    totalItems: 200,
    currentPage: 3,
    itemsPerPage: 50,
    maxPagesToShow: 10,
);

var_dump($pagination->getTotalItems());
// int(200)

var_dump($pagination->getTotalItemsFrom());
// int(101)

var_dump($pagination->getTotalItemsTo());
// int(150)

var_dump($pagination->getItemsPerPage());
// int(50)

var_dump($pagination->getItemsOffset());
// int(100)

var_dump($pagination->hasPages());
// bool(true)

$pages = $pagination->getPages();
// array

$pages = $pagination->getTotalPages();
// int(4)

var_dump($pagination->hasPage(num: 5));
// bool(false)

var_dump($pagination->hasCurrentPage());
// bool(true)

var_dump($pagination->getCurrentPage());
// int(3)

var_dump($pagination->getLastPage());
// null|PageInterface

var_dump($pagination->getPrevPageUrl());
// string(6) "page/2"

var_dump($pagination->getNextPageUrl());
// NULL
```

### Current Page Verification

[](#current-page-verification)

It is advised to check if the current page exists, especially if you set the current page from user input or based on a url parameter.

```
use Tobento\Service\Pagination\Pagination;

$pagination = new Pagination(
    totalItems: 200,
    currentPage: 12,
    itemsPerPage: 50,
);

if (! $pagination->hasCurrentPage()) {
    // handle if current page does not exist.
    // redirect, page not found or whatever fits your application design.
    $pagination = $pagination->withCurrentPage(1);
}
```

### Render Pagination

[](#render-pagination)

There are different ways of rendering the pagination depending on your needs.

#### Menu Renderer

[](#menu-renderer)

The menu renderer is the default pagination renderer. It uses the [Menu Service](https://github.com/tobento-ch/service-menu) to generate the pagination HTML.

```
use Tobento\Service\Pagination\Pagination;
use Tobento\Service\Pagination\MenuRenderer;

$pagination = new Pagination(
    totalItems: 200,
    currentPage: 3,
    itemsPerPage: 30,
    renderer: new MenuRenderer(previousText: 'prev', nextText: 'next'),
);

echo $pagination;
```

Outputs:

```

    prev
    1
    2
    3
    4
    5
    6
    7
    next

```

#### Custom Renderer

[](#custom-renderer)

You might write your own renderer fitting your application. The following example uses the [View Service](https://github.com/tobento-ch/service-view) to generate the pagination HTML.

```
use Tobento\Service\Pagination\Pagination;
use Tobento\Service\Pagination\RendererInterface;
use Tobento\Service\Pagination\PaginationInterface;
use Tobento\Service\View\ViewInterface;
use Tobento\Service\View\View;
use Tobento\Service\View\PhpRenderer;
use Tobento\Service\Dir\Dirs;
use Tobento\Service\Dir\Dir;
use Tobento\Service\View\Data;
use Tobento\Service\View\Assets;

$view = new View(
    new PhpRenderer(
        new Dirs(
            new Dir('home/private/views/')
        )
    ),
    new Data(),
    new Assets('home/public/src/', 'https://www.example.com/src/')
);

class ViewRenderer implements RendererInterface
{
    public function __construct(
        private ViewInterface $view,
        private string $viewToRender = 'service/pagination',
    ) {}

    public function render(PaginationInterface $pagination): string
    {
        return $this->view->render(
            $this->viewToRender,
            ['pagination' => $pagination]
        );
    }
}

$pagination = new Pagination(
    totalItems: 500,
    currentPage: 2,
    renderer: new ViewRenderer($view),
);

echo $pagination;
```

***The view template***

```