volnix/paginate

A simple pagination library that is easily extensible for custom pagination operations.

Paginate

, _(*1)

Paginate is a dead-simple pagination data-model. It holds metadata about your pagination system and also the current state of pagination at any given time. It is useful for use in models for server-side pagination, views for client-side pagination building, and everywhere in between., _(*2)

Basic Usage

The pagination library can be used with zero configuration if desired. There are 3 config settings for Paginate and are simply metadata about your pagination system:, _(*3)

• Results per Page (default: 50) - the number of results to display on each page
• Page Range (default: 2) - the number of pages on either side of the current page to display (e.g., if you're on page 5 it would show pages 3 through 7 in your pagination)
• Index (default: 'page') - the GET/POST index that your current page identifier is passed in on; useful when it's time to start building up pagination

Zero-configuration pagination:, _(*4)

// instantiate our pager
$pager = new \Volnix\Paginate\Pager;

// actually set the pagination parameters
$pager->paginate(1000, 5); // 100 results in result-set, current page = 5

Note: The paginate method is what actually sets the current pagination state. This must be called with the result count (and optionally current page) to build up useful pagination information., _(*5)

The use-case above would set the following parameters about the current state of your pagination (these correspond to class variables in the Pager):, _(*6)

• Number of pages ($max_page): 20 (1000 results, 50 per page)
• Current page: 5
• Page range shown ($low_page - $high_page): 3 - 7 (2 page page-range)
• Query skip ($query_skip): 400 (on page 5 with 100 results per page, so skip the first 400 since we're on 401-500)

Configuring Pagination

You may also set the style of pagination you want by passing in metadata through the constructor or calling the setConfig method:, _(*7)

// both of the below examples do the exact same thing
$pager = new \Volnix\Paginate\Pager(5, 5, 'foo');

$pager = new \Volnix\Paginate\Pager;
$pager->setConfig(5, 5, 'foo');

Note: Neither of the above examples are calling the paginate method. The pager is not of any value until paginate is called, for that method actually sets your current state., _(*8)

Pagination Information

The class variables exposed by the Pager are the core of the information provided by this library and are what are to be used by any extensions:, _(*9)

• paginate - A bool of whether to paginate or not
• current_page - The current page (passed in through the paginate method call.
• query_skip - The amount of records of skip in your ORM when querying for the next result-set
• result_count - The total number of results matching a given set of search criteria that need to be paged through
• min_page - The minimum page of pagination (always 1)
• max_page - The maximum page of pagination (equals the number of results / the results per page)
• low_page - The low range of pages to display (determined by $page_range)
• high_page - The high range of pages to display

public $paginate                = true; // whether to even paginate or not
public $current_page            = 1; // current page
public $query_skip              = 0; // the skip step to be passed into queries
public $result_count            = 0; // how many results we're paginating
public $min_page                = 1; // min page of all pages
public $max_page                = 1; // max page (i.e. results / results per page)
public $low_page                = 1; // low page in range of pages being displayed
public $high_page               = 1; // high page in range of pages being displayed

Method Chaining

The paginate and setConfig methods both return the Pager object, so method-chaining is possible:, _(*10)

$pager = new \Volnix\Paginate\Pager;
$pager->setConfig(5, 5, 'foo')->paginate(100);

// OR

$pager = (new \Volnix\Paginate\Pager)->setConfig(5, 5, 'foo')->paginate(100);

API Pagination

Paginate can return an array or JSON containing pertinent information for API pagination. These fields are returned in both formats:, _(*11)

• current: the current page
• prev: the previous page (equal to the minimum page if at the low end of pagination)
• next: the next page (equal to the maximum page if at the upper end of pagination)
• skip: the query skip
• min: the minimum page
• max: the maxmimum page

Note: prev and next will both be equal to 1 if there is no pagination, _(*12)

Extending Paginate

This library is meant to be extended. Once you have your basic pagination information, it is possible to build up server-side, client-side, etc. pagination in whatever ORM or javascript library you use in your project., _(*13)