PHPackages esi/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. esi/pagination ActiveLibrary[Utility & Helpers](/categories/utility) esi/pagination ============== Simple, lightweight and universal service that implements pagination on collections of things. v2.1.1(4mo ago)123[1 issues](https://github.com/ericsizemore/pagination/issues)[2 PRs](https://github.com/ericsizemore/pagination/pulls)MITPHPPHP >=8.2CI passing Since Feb 28Pushed 1mo agoCompare [ Source](https://github.com/ericsizemore/pagination)[ Packagist](https://packagist.org/packages/esi/pagination)[ Fund](https://ko-fi.com/ericsizemore)[ GitHub Sponsors](https://github.com/ericsizemore)[ RSS](/packages/esi-pagination/feed)WikiDiscussions master Synced today READMEChangelog (5)Dependencies (11)Versions (11)Used By (0) Pagination ========== [](#pagination) [![Build Status](https://camo.githubusercontent.com/9d581413dddfaf14d0afd4bf9c4ad49a9b2c4936c7c289386b96830c4246bde8/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f6572696373697a656d6f72652f706167696e6174696f6e2f6261646765732f6275696c642e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/ericsizemore/pagination/build-status/master)[![Code Coverage](https://camo.githubusercontent.com/2ad081d349d2be1fa78ae6d07ed7757d7f860efa388557764391617494dfa5c7/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f6572696373697a656d6f72652f706167696e6174696f6e2f6261646765732f636f7665726167652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/ericsizemore/pagination/?branch=master)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/3c5bf16097ebcb955a3f4670a985fa303ad40815b655ab6ec57552fa495eef96/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f6572696373697a656d6f72652f706167696e6174696f6e2f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/ericsizemore/pagination/?branch=master)[![Continuous Integration](https://github.com/ericsizemore/pagination/actions/workflows/continuous-integration.yml/badge.svg)](https://github.com/ericsizemore/pagination/actions/workflows/continuous-integration.yml)[![Type Coverage](https://camo.githubusercontent.com/90abc8de286d186d99bc4d5c8d726f09c5f4c7c6ae4615734570dbc6c30d38b3/68747470733a2f2f73686570686572642e6465762f6769746875622f6572696373697a656d6f72652f706167696e6174696f6e2f636f7665726167652e737667)](https://shepherd.dev/github/ericsizemore/pagination)[![Psalm Level](https://camo.githubusercontent.com/be44944a8794e17238876e7e6347c22b6b137f0e06f3a0d24289e5b119e82f2c/68747470733a2f2f73686570686572642e6465762f6769746875622f6572696373697a656d6f72652f706167696e6174696f6e2f6c6576656c2e737667)](https://shepherd.dev/github/ericsizemore/pagination)[![Quality Gate Status](https://camo.githubusercontent.com/ff86e399502131ed1694a46a0d8a86f1c597d9810d8799192bc90272257fd488/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d6572696373697a656d6f72655f706167696e6174696f6e266d65747269633d616c6572745f737461747573)](https://sonarcloud.io/summary/new_code?id=ericsizemore_pagination)[![Latest Stable Version](https://camo.githubusercontent.com/7e34e982cda116a31d9ec90a822d633fe3605d4c88083e0012870036054bf601/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6573692f706167696e6174696f6e2e737667)](https://packagist.org/packages/esi/pagination)[![Downloads per Month](https://camo.githubusercontent.com/63bd376009f5eb8d5602858aae6aad677e9b62432e71debd79663d3c59367fba/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646d2f6573692f706167696e6174696f6e2e737667)](https://packagist.org/packages/esi/pagination)[![License](https://camo.githubusercontent.com/75c828610195249ac0093c25e97a0549a1a7217f6f575fe14cee001e628ee99c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6573692f706167696e6174696f6e2e737667)](https://packagist.org/packages/esi/pagination) `Esi\Pagination` - A library that implements a paging interface on collections of things. Installation ------------ [](#installation) `Esi\Pagination` can be installed via [Composer](https://getcomposer.org/): ``` $ composer require esi/pagination:^2.1 ``` How Pagination Works -------------------- [](#how-pagination-works) I have tried to make Pagination as simple, flexible, and easy to use as possible. There are four main elements that describe the operation of Pagination. These are: - Paginator service - Item total callback - Slice callback - Pagination model The **Paginator** service performs the pagination algorithm, generating the page range and item collection slices. When it is done, it will return a **Pagination** object filled with the item collection slice and metadata. The two main operations the **Paginator** service will perform on your collection (or data set) are denoted by two callback methods passed to the **Paginator** service. The first one is the **Item total callback**. This callback is used to determine the total amount of items in your collection (returned as an integer). The second one is the **Slice callback**. This callback actually slices your collection given an **offset** and **length** argument. The idea behind using these callbacks is so that Pagination is kept, well, simple! The real power comes with the flexibility. You can use Pagination with just about any collection you want. From simple arrays to database lists to [Doctrine](http://www.doctrine-project.org/) collections to [Solr](http://lucene.apache.org/solr/) result sets — we have you covered! It really doesn't matter what we paginate — as long as it is a collection of things, and you can count and slice it. ### Basic Usage [](#basic-usage) First, the most basic example — paginating over an array. ``` use Esi\Pagination\Paginator; use function array_slice; use function filter_input; use const FILTER_VALIDATE_INT; use const INPUT_GET; // Build a mock list of items we want to paginate through. $items = [ 'Banana', 'Apple', 'Cherry', 'Lemon', 'Pear', 'Watermelon', 'Orange', 'Grapefruit', 'Blackcurrant', 'Dingleberry', 'Snosberry', 'Tomato', ]; // Instantiate a new paginator service. $paginator = new Paginator(); // Set some parameters (optional). $paginator ->setItemsPerPage(10) // Give us a maximum of 10 items per page. ->setPagesInRange(5) // How many pages to display in navigation (e.g. if we have a lot of pages to get through). ; // Pass our item total callback. $paginator->setItemTotalCallback(static function () use ($items): int { return \count($items); }); // Pass our slice callback. $paginator->setSliceCallback(static function (int $offset, int $length) use ($items): array { return array_slice($items, $offset, $length); }); // Paginate the collection, passing the current page number (e.g., from the current request). $pagination = $paginator->paginate(filter_input(INPUT_GET, 'page', FILTER_VALIDATE_INT)); // Ok, from here on is where we would be inside a template or view (e.g., pass $pagination to your view). // Iterate over the items on this page. foreach ($pagination->getItems() as $item) { echo \sprintf('%s', $item); } // Build a basic page navigation structure. foreach ($pagination->getPages() as $page) { echo \sprintf('%1$d ', $page); } ``` There are lots of other pieces of metadata held within the [pagination object](#pagination-object). These can be used for building first, last, previous and next buttons. ### MySQL Example [](#mysql-example) Now take the example above and use a MySQL result set instead of an array. ``` use Esi\Pagination\Paginator; use mysqli; use function filter_input; use const FILTER_VALIDATE_INT; use const INPUT_GET; // Instantiate a new paginator service. $paginator = new Paginator(); // Set some parameters (optional). $paginator ->setItemsPerPage(10) // Give us a maximum of 10 items per page. ->setPagesInRange(5) // How many pages to display in navigation (e.g., if we have a lot of pages to get through). ; // Connect to a database. $mysql = new mysqli('localhost', 'root', 'password', 'myDatabase'); // Pass our item total callback. $paginator->setItemTotalCallback(static function () use($mysql): int { // Run count query. $result = $mysql->query("SELECT COUNT(*) AS `totalCount` FROM `TestData`"); $row = $result->fetch_array(MYSQLI_ASSOC); // Return the count, cast as an integer. return (int) $row['totalCount']; }); // Pass our slice callback. $paginator->setSliceCallback(static function (int $offset, int $length) use ($mysql): array { // Run slice query. $result = $mysql->query("SELECT `Name` FROM `TestData` LIMIT $offset, $length"); // Build a collection of items. $collection = []; while ($row = $result->fetch_assoc()) { $collection[] = $row; } // Return the collection. return $collection; }); // Paginate the item collection, passing the current page number (e.g. from the current request). $pagination = $paginator->paginate(filter_input(INPUT_GET, 'page', FILTER_VALIDATE_INT)); // Ok, from here on is where we'd be inside a template of view (e.g. pass $pagination to your view). // Iterate over the items on this page. foreach ($pagination->getItems() as $item) { echo sprintf('%s', $item['Name']); } // Let's build a basic page navigation structure. foreach ($pagination->getPages() as $page) { echo \sprintf('%1$d ', $page); } ``` **Note:** The example above uses `mysqli` as I tried to make it as simple as possible. In the real world please use [PDO](https://www.php.net/pdo), [Doctrine DBAL](https://www.doctrine-project.org/projects/dbal.html), etc. It really does not matter what sort of collection you return from the `Paginator::setSliceCallback()` callback. It will always end up in `Pagination::getItems()`. ### Constructor Configuration [](#constructor-configuration) You can also configure the paginator with a configuration array passed to the constructor. For example: ``` $paginator = new Paginator([ 'itemTotalCallback' => static function (): int { // ... }, 'sliceCallback' => static function (int $offset, int $length): array { // ... }, 'itemsPerPage' => 10, 'pagesInRange' => 5, ]); ``` ### Pagination as an Iterator [](#pagination-as-an-iterator) The `Pagination` object returned from the `Paginator` service implements `\IteratorAggregate` and `\Countable` so you can do things like this in your view: ``` if (\count($pagination) > 0) { foreach ($pagination as $item) { echo \sprintf('%s', $item); } } ``` ### Arbitrary Pagination Metadata [](#arbitrary-pagination-metadata) In `itemTotalCallback` and `sliceCallback`, you have the option of passing arbitrary metadata to the pagination object. This is an optional feature and is useful if you have a use-case where additional data is returned by these operations, and you want to access it from the pagination object whilst listing the items. A good example of this is when using search engines such as [ElasticSearch](https://www.elastic.co/elasticsearch), you can pass back secondary information — like aggregations, etc. A generic example can be seen below: ``` use Esi\Pagination\Pagination; use function array_slice; use function filter_input; use function var_dump; use const FILTER_VALIDATE_INT; use const INPUT_GET; // ... $paginator->setItemTotalCallback(static function (Pagination $pagination) use ($items): int { // Pass arbitrary metadata to pagination object. $pagination->setMeta(['my', 'meta', 'data']); return \count($items); }); $paginator->setSliceCallback(static function (int $offset, int $length, Pagination $pagination) use ($items): array { // Pass more arbitrary metadata to pagination object. $pagination->setMeta(array_merge($pagination->getMeta(), ['more', 'stuff'])); return array_slice($items, $offset, $length); }); // ... // Perform the pagination $pagination = $paginator->paginate(filter_input(INPUT_GET, 'page', FILTER_VALIDATE_INT)); // Get the metadata from the pagination object. var_dump($pagination->getMeta()); ``` ### Pre-Query and Post-Query Callbacks [](#pre-query-and-post-query-callbacks) Before and after the count and slice queries, you can set callbacks to fire. To set them, do the following: ``` $paginator->setBeforeQueryCallback(static function (Paginator $paginator, Pagination $pagination): void { // ... }); $paginator->setAfterQueryCallback(static function (Paginator $paginator, Pagination $pagination): void { // ... }); ``` This is handy if you want to perform some function or process, such as adding/removing meta data, before and after each query is made. ### Pagination Object [](#pagination-object) `Paginator::paginate()` will return a `Pagination` model object, which carries the item collection for the current page plus the meta information for the collection. For e.g., the pages array, next page number, previous page number, etc. Please see below for a list of properties that the `Pagination` object has. - **items** : array (Collection of items for the current page) - **pages** : array (Array of page numbers in the current range) - **totalNumberOfPages** : int (Total number of pages) - **currentPageNumber** : int (Current page number) - **firstPageNumber** : int (First page number) - **lastPageNumber** : int (Last page number) - **previousPageNumber** : int | null (Previous page number) - **nextPageNumber** : int | null (Next page number) - **itemsPerPage** : int (Number of items per page) - **totalNumberOfItems** : int (Total number of items) - **firstPageNumberInRange** : int (First page number in current range) - **lastPageNumberInRange** : int (Last page number in current range) A good example of using the `Pagination` object is to build a simple pagination navigation structure: ``` // Render the first page link, echo \sprintf('First Page ', $pagination->getFirstPageNumber()); // Render the previous page link (note: the previous page number could be null), echo \sprintf('Previous Page ', $pagination->getPreviousPageNumber()); // Render page range links, foreach ($pagination->getPages() as $page) { echo \sprintf('%1$d ', $page); } // Render the next page link (note: the next page number could be null), echo \sprintf('Next Page ', $pagination->getNextPageNumber()); // Render the last page link, echo \sprintf('Last Page', $pagination->getLastPageNumber()); ``` About ----- [](#about) ### Requirements [](#requirements) - Pagination works with PHP 8.2.0 or above. ### Credits [](#credits) This library is a `fork` of the [AshleyDawson\\SimplePagination](https://github.com/AshleyDawson/SimplePagination) library by [Ashley Dawson](https://github.com/AshleyDawson). To view changes in this library in comparison to the original library, please see the [CHANGELOG.md](./CHANGELOG.md) file. - Author: [Eric Sizemore](https://github.com/ericsizemore) - Thanks to [Ashley Dawson](https://github.com/AshleyDawson) for the original [AshleyDawson\\SimplePagination](https://github.com/AshleyDawson/SimplePagination) library that this library is forked from. - Thanks to [all Contributors](https://github.com/ericsizemore/pagination/contributors). ### Contributing [](#contributing) See [CONTRIBUTING](./CONTRIBUTING.md). Bugs and feature requests are tracked on [GitHub](https://github.com/ericsizemore/pagination/issues). ### Contributor Covenant Code of Conduct [](#contributor-covenant-code-of-conduct) See [CODE\_OF\_CONDUCT.md](./CODE_OF_CONDUCT.md) ### Backward Compatibility Promise [](#backward-compatibility-promise) See [backward-compatibility.md](./backward-compatibility.md) for more information on Backwards Compatibility. ### Changelog [](#changelog) See the [CHANGELOG](./CHANGELOG.md) for more information on what has changed recently. ### License [](#license) See the [LICENSE](./LICENSE.md) for more information on the license that applies to this project. ### Security [](#security) See [SECURITY](./SECURITY.md) for more information on the security disclosure process. ### Health Score 38 — LowBetter than 83% of packages Maintenance65 Regular maintenance activity Popularity9 Limited adoption so far Community10 Small or concentrated contributor base Maturity60 Established project with proven stability Bus Factor2 2 contributors hold 50%+ of commits How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~179 days Total 5 Last Release 138d ago PHP version history (2 changes)v2.0.0PHP ^8.2 <8.5 v2.1.1PHP >=8.2 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/723810?v=4)[Eric Sizemore](/maintainers/ericsizemore)[@ericsizemore](https://github.com/ericsizemore) --- Top Contributors [![ericsizemore](https://avatars.githubusercontent.com/u/723810?v=4)](https://github.com/ericsizemore "ericsizemore (294 commits)")[![renovate[bot]](https://avatars.githubusercontent.com/in/2740?v=4)](https://github.com/renovate[bot] "renovate[bot] (244 commits)")[![AshleyDawson](https://avatars.githubusercontent.com/u/1968942?v=4)](https://github.com/AshleyDawson "AshleyDawson (58 commits)")[![ajdaw](https://avatars.githubusercontent.com/u/205369218?v=4)](https://github.com/ajdaw "ajdaw (7 commits)") --- Tags flexiblehacktoberfestlightlightweightlitepagerpaginationpaginatorsimpleuniversalpagerpaginatorpaginationSimplelightweightlightFlexibleeasyliteuniversal ### Code Quality TestsPHPUnit Static AnalysisPHPStan, Psalm, Rector Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/esi-pagination/health.svg) ``` [![Health](https://phpackages.com/badges/esi-pagination/health.svg)](https://phpackages.com/packages/esi-pagination) ``` ### Alternatives [ashleydawson/simple-pagination Simple, lightweight and universal service that implements pagination on collections of things 19162.6k2](/packages/ashleydawson-simple-pagination)[jasongrimes/paginator A lightweight PHP paginator, for generating pagination controls in the style of Stack Overflow and Flickr. The 'first' and 'last' page links are shown inline as page numbers, and excess page numbers are replaced by ellipses. 4091.3M22](/packages/jasongrimes-paginator)[rinvex/universities Rinvex Universities is a simple and lightweight package for retrieving university details with flexibility. A whole bunch of data including name, country, state, email, website, telephone, address, and much more attributes for the 17k+ known universities worldwide at your fingertips. 6816.6k](/packages/rinvex-universities)[ttskch/paginator-bundle The most thin, simple and customizable paginator bundle for Symfony 1115.2k](/packages/ttskch-paginator-bundle)[sivka/paginator bootstrap-4 fork of jasongrimes/php-paginator, a lightweight PHP paginator, for generating pagination controls in the style of Stack Overflow and Flickr. The 'first' and 'last' page links are shown inline as page numbers, and excess page numbers are replaced by ellipses. 141.4k](/packages/sivka-paginator) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)