solophp / paginator

v2.1.0 2025-08-02 19:08 UTC

Requires

• php: >=8.2

Requires (Dev)

• phpunit/phpunit: ^10.0
• squizlabs/php_codesniffer: ^3.7

MIT

• Vitaliy Olos

• php
• paginator
• pagination
• psr-7

Published on Packagist.org on 2025-08-02 19:09 UTC

README

Warning

Abandoned. This package is no longer maintained and gets no fixes. It has no successor and stays on Packagist for the projects that use it. The current Solo packages are listed at solophp.github.io.

A lightweight, framework-agnostic pagination package for PHP 8.2+.

Features

• Zero dependencies
• Framework agnostic
• Configurable items per page
• Maintains all query parameters in URLs
• SEO-friendly pagination links
• Ellipsis support for long page lists
• Static interface
• Pre-calculated pagination support

Requirements

• PHP 8.2 or higher

Installation

You can install the package via composer:

composer require solophp/paginator

Usage

use Solo\Paginator\Paginator;

public static function paginate(
    array $queryParams,
    int $totalItems,
    array $limitOptions = [10, 25, 50, 100]
): PaginationResult

Parameters:

• $queryParams - Array of query parameters (typically $_GET or $request->getQueryParams())
• $totalItems - Total number of items to paginate
• $limitOptions - Optional array of allowed limit values. Default is [10, 25, 50, 100]

Basic usage:

use Solo\Paginator\Paginator;

class ProductsController
{
    public function list(ServerRequestInterface $request): ResponseInterface
    {
        $queryParams = $request->getQueryParams(); // or $_GET
        $result = Paginator::paginate(
            queryParams: $queryParams,
            totalItems: $totalItems
        );

        return $this->view->render('products/list', [
            'pagination' => $result
        ]);
    }
}

Custom limit options:

$result = Paginator::paginate(
    queryParams: $queryParams,
    totalItems: 100,
    limitOptions: [20, 40, 60, 80]
);

PaginationResult

The paginate() method returns a PaginationResult object with the following properties:

• page: Current page number
• limit: Items per page limit
• totalPages: Total number of pages
• totalItems: Total number of items
• links: Array of pagination links with url, page number and current state
• nextPageUrl: URL for the next page
• previousPageUrl: URL for the previous page
• hasNextPage: Whether there is a next page
• hasPreviousPage: Whether there is a previous page
• limitOptions: Array of available limit options with urls

Template Usage

Basic pagination links:

<?php foreach ($result->links as $link): ?>
    <?php if ($link->isEllipsis): ?>
        <span>...</span>
    <?php else: ?>
        <a 
            href="<?= $link->url ?>"
            <?= $link->isCurrent ? 'class="active"' : '' ?>
        >
            <?= $link->page ?>
        </a>
    <?php endif; ?>
<?php endforeach; ?>

Items per page selector:

<select onchange="window.location.href=this.value">
    <?php foreach ($result->limitOptions as $option): ?>
        <option 
            value="<?= $option->url ?>"
            <?= $option->isCurrent ? 'selected' : '' ?>
        >
            <?= $option->value ?> items
        </option>
    <?php endforeach; ?>
</select>

Navigation links:

<?php if ($result->hasPreviousPage): ?>
    <a href="<?= $result->previousPageUrl ?>">Previous</a>
<?php endif; ?>

<?php if ($result->hasNextPage): ?>
    <a href="<?= $result->nextPageUrl ?>">Next</a>
<?php endif; ?>

Default Values

• Default page: 1
• Default limit: 25
• Default limit options: [10, 25, 50, 100]
• Minimum links count: 3

Query Parameters

The paginator uses the following query parameters:

• page: Current page number
• limit: Number of items per page

All other query parameters in the URL are preserved.

Development

Running Tests

composer test

Code Style

Check code style:

composer cs

Fix code style:

composer cs-fix

License

MIT