README

A PHP library providing pagination functionality to generate page numbers for UI pagination controls, with smart handling of large page sets.

Installation

Install the package via Composer:

composer require valksor/php-functions-pagination

Requirements

PHP 8.4 or higher

Usage

The Pagination class provides a mechanism to generate pagination data for displaying page numbers in a UI, with intelligent handling of omitted pages.

Basic Usage

use Valksor\Functions\Pagination\Pagination;

// Create a new Pagination instance
$pagination = new Pagination();

// Generate pagination data
$pages = $pagination->paginate(
    7,       // Number of visible pages
    20,      // Total number of pages
    5,       // Current page
    -1       // Indicator for omitted pages (optional, defaults to -1)
);

// $pages will contain an array like: [1, 2, 3, 4, 5, 6, 7, -1, 20]
// where -1 represents omitted pages

Different Pagination Scenarios

The pagination algorithm intelligently handles different scenarios:

All Pages Visible

When the total number of pages is less than or equal to the number of visible pages:

$pages = $pagination->paginate(10, 8, 4); // [1, 2, 3, 4, 5, 6, 7, 8]

Single Omitted Section

When the current page is near the beginning or end:

// Current page near beginning
$pages = $pagination->paginate(7, 20, 3); // [1, 2, 3, 4, 5, -1, 20]

// Current page near end
$pages = $pagination->paginate(7, 20, 18); // [1, -1, 16, 17, 18, 19, 20]

Two Omitted Sections

When the current page is in the middle of a large set:

$pages = $pagination->paginate(7, 20, 10); // [1, -1, 8, 9, 10, 11, 12, -1, 20]

Features

Smart page generation: Intelligently generates page numbers for UI pagination controls
Omitted page handling: Uses indicators to show where pages are omitted in large sets
Configurable visible pages: Control how many page numbers are shown
Flexible indicators: Customize the indicator value for omitted pages
Input validation: Comprehensive validation of all input parameters
Multiple scenarios: Handles current page at beginning, middle, or end of page set

For a complete list of all functions available in this package, see Features.

Validation

The class performs several validations:

The number of visible pages must be at least 5
The total number of pages must be at least 1
The current page must be between 1 and the total number of pages
The indicator value must not be a valid page number (between 1 and total)

Contributing

Contributions are welcome! Please read our Contributing Guidelines for details on:

Code style requirements (PSR-12)
Testing requirements for PRs
One feature per pull request
Development setup instructions

To contribute to Pagination functions:

Fork repository
Create a feature branch (git checkout -b feature/new-pagination-function)
Implement your function following existing patterns
Add comprehensive tests including edge cases
Ensure all tests pass and code style is correct
Submit a pull request

Security

If you discover any security-related issues, please email us at security@valksor.dev instead of using the issue tracker.

For security policy and vulnerability reporting guidelines, please see our Security Policy.

Support

Documentation: Full documentation
Issues: GitHub Issues for bug reports and feature requests
Discussions: GitHub Discussions for questions and community support
Stack Overflow: Use tag valksor-php-functions-pagination

Credits

Original Author - Creator and maintainer
All Contributors - Thank you to all who contributed
Relevant PHP Documentation - Core PHP functionality inspiration
Valksor Project - Part of the larger Valksor PHP ecosystem

License

This package is licensed under the BSD-3-Clause License.

About Valksor

This package is part of the valksor/php-valksor project - a comprehensive PHP library and Symfony bundle that provides a collection of utilities, components, and integrations for Symfony applications.

The main project includes:

Various utility functions and components
Doctrine ORM tools and extensions
Symfony bundle for easy configuration
And much more

If you find this Pagination component useful, you might want to check out the full Valksor project for additional tools and utilities that can enhance your Symfony application development.

To install the complete package:

composer require valksor/php-valksor

valksor / php-functions-pagination

Maintainers

Details