PHPackages ashleydawson/simple-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. ashleydawson/simple-pagination ActiveLibrary[Utility & Helpers](/categories/utility) ashleydawson/simple-pagination ============================== Simple, lightweight and universal service that implements pagination on collections of things 1.0.8(7y ago)18161.2k↓30%5[1 issues](https://github.com/AshleyDawson/SimplePagination/issues)2MITPHPPHP >=5.3.3 Since Jul 15Pushed 6y ago6 watchersCompare [ Source](https://github.com/AshleyDawson/SimplePagination)[ Packagist](https://packagist.org/packages/ashleydawson/simple-pagination)[ RSS](/packages/ashleydawson-simple-pagination/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (9)Dependencies (1)Versions (11)Used By (2) Simple Pagination ================= [](#simple-pagination) [![Build Status](https://camo.githubusercontent.com/f1490ddbaa53262808478709871829164f91684d48b05c680a05738d6b2d323a/68747470733a2f2f7472617669732d63692e6f72672f4173686c6579446177736f6e2f53696d706c65506167696e6174696f6e2e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/AshleyDawson/SimplePagination) Many thanks to [BrowserStack](https://www.browserstack.com/) for supporting open source projects like this one. Simple pagination library implements a paging interface on collections of things. If you'd like to use the Simple Pagination within a Symfony 2 project then why not try my [Simple Pagination Bundle](https://github.com/AshleyDawson/SimplePaginationBundle). Installation ------------ [](#installation) You can install Simple Pagination via [Composer](https://getcomposer.org/). To do that, simply `require` the package in your `composer.json` file like so: ``` { "require": { "ashleydawson/simple-pagination": "~1.0" } } ``` Then run `composer update` to install the package. How Simple Pagination Works --------------------------- [](#how-simple-pagination-works) I've tried to make Simple Pagination as easy to use and as flexible as possible. There are four main elements that describe the operation of Simple 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's 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 number 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 Simple Pagination is kept, well, simple! The real power comes with the flexibility. You can use Simple 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've got you covered! It really doesn't matter what we paginate - as long as it's a collection of things and you can count and slice it. Basic Usage ----------- [](#basic-usage) Ok, lets go with the most basic example - paginating over an array. ``` use AshleyDawson\SimplePagination\Paginator; // Build a mock list of items we want to paginate through $items = array( '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(function () use ($items) { return count($items); }); // Pass our slice callback $paginator->setSliceCallback(function ($offset, $length) use ($items) { return array_slice($items, $offset, $length); }); // Paginate the item collection, passing the current page number (e.g. from the current request) $pagination = $paginator->paginate((int) $_GET['page']); // 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 $item . ''; } // Let's build a basic page navigation structure foreach ($pagination->getPages() as $page) { echo '' . $page . ' '; } ``` There are lots of other pieces of meta data held within the [pagination object](#pagination-object). These can be used for building first, last previous and next buttons. MySQL Example ------------- [](#mysql-example) Let's take the example above and use a MySQL result set instead of an array. ``` use AshleyDawson\SimplePagination\Paginator; // 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(function () { // Run count query $result = mysql_query("SELECT COUNT(*) FROM `TestData`"); // Return the count (the value of the first result column), cast as an integer return (int) mysql_result($result, 0); }); // Pass our slice callback $paginator->setSliceCallback(function ($offset, $length) { // Run slice query $result = mysql_query("SELECT `Name` FROM `TestData` LIMIT {$offset}, {$length}"); // Build a collection of items $collection = array(); while ($row = mysql_fetch_assoc($result)) { $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((int) $_GET['page']); // 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 $item['Name'] . ''; } // Let's build a basic page navigation structure foreach ($pagination->getPages() as $page) { echo '' . $page . ' '; } ``` **Note:** The example above uses `mysql_connect()` etc. as I tried to make it as simple as possible. In the real world please use [PDO](http://php.net/manual/en/book.pdo.php), [Doctrine DBAL](http://docs.doctrine-project.org/projects/doctrine-dbal/en/latest/), etc. It really doesn't 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(array( 'itemTotalCallback' => function () { // ... }, 'sliceCallback' => function ($offset, $length) { // ... }, '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 $item . ''; } } ``` Arbitrary Pagination Metadata ----------------------------- [](#arbitrary-pagination-metadata) During both item total and slice callbacks 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/), you can pass back secondary information - like aggregations, etc. A generic example can be seen below: ``` use AshleyDawson\SimplePagination\Pagination; // ... $paginator->setItemTotalCallback(function (Pagination $pagination) use ($items) { // Pass arbitrary metadata to pagination object $pagination->setMeta(['my', 'meta', 'data']); return count($items); }); $paginator->setSliceCallback(function ($offset, $length, Pagination $pagination) use ($items) { // 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((int) $_GET['page']); // Get the metadata from the pagination object var_dump($pagination->getMeta()); ``` Pre and Post Query Callbacks ---------------------------- [](#pre-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(function (Paginator $paginator, Pagination $pagination) { }); $paginator->setAfterQueryCallback(function (Paginator $paginator, Pagination $pagination) { }); ``` This is handy if you want to perform some function before and after each query is made. Pagination Object -------------------------------------------------------------- [](#pagination-object) The result of the Paginator::paginate() operation is to produce a Pagination model object, which carries the item collection for the current page plus the meta information for the collection, e.g. pages array, next page number, previous page number, etc. Please see below for a list of properties that the Pagination object has. - **items** : mixed (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 'First Page '; // Render the previous page link (note: the previous page number could be null) echo 'Previous Page '; // Render page range links foreach ($pagination->getPages() as $page) { echo '' . $page . ' '; } // Render the next page link (note: the next page number could be null) echo 'Next Page '; // Render the last page link echo 'Last Page'; ``` ### Health Score 39 — LowBetter than 86% of packages Maintenance19 Infrequent updates — may be unmaintained Popularity40 Moderate usage in the ecosystem Community18 Small or concentrated contributor base Maturity64 Established project with proven stability Bus Factor1 Top contributor holds 89.2% of commits — single point of failure 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 ~205 days Recently: every ~143 days Total 9 Last Release 2679d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/958ec06d53fff9021d93c8728740d74bf348a3ad22a4fb22ef6c1de9ee7f4f7a?d=identicon)[AshleyDawson](/maintainers/AshleyDawson) --- Top Contributors [![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 pagerpaginatorpaginationSimplelightweightFlexibleeasyliteuniversal ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/ashleydawson-simple-pagination/health.svg) ``` [![Health](https://phpackages.com/badges/ashleydawson-simple-pagination/health.svg)](https://phpackages.com/packages/ashleydawson-simple-pagination) ``` ### Alternatives [knplabs/knp-components Knplabs component library 77443.6M46](/packages/knplabs-knp-components)[rinvex/countries Rinvex Countries is a simple and lightweight package for retrieving country details with flexibility. A whole bunch of data including name, demonym, capital, iso codes, dialling codes, geo data, currencies, flags, emoji, and other attributes for all 250 countries worldwide at your fingertips. 1.7k7.4M48](/packages/rinvex-countries)[aplus/pagination Aplus Framework Pagination Library 2091.6M3](/packages/aplus-pagination)[kop/yii2-scroll-pager Infinite AJAX scrolling for Yii2 ListView widget 180706.5k10](/packages/kop-yii2-scroll-pager)[beberlei/porpaginas Library that generically solves several pagination issues with DAO/repository abstractions. 163612.6k11](/packages/beberlei-porpaginas)[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. 6716.1k](/packages/rinvex-universities) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)