tjweldon/pages

A lightweight standalone pagination component

dev-master 2020-07-20 14:28 UTC

Requires (Dev)

• phpunit/phpunit: 9.2.6

MIT

• Thomas Weldon

README

Pages is a lightweight pagination component. It is a paged wrapper for any collection of values.

Installation

Composer

composer require tjweldon/pages

Usage

Creating your Pages

To create your paginated collection:

$pages = Pages::empty()
	->appendCollection($iterableCollectionOfItems)
	->appendItem($aSingleItem)
;

The $pages variable now holds your collection of items but is not going to page them by default. To set paging:

$pages->limitPageSize($pageSize);

OR

$pages->limitPageCount($pageCount);

Warning: using one after the other, in either order, will ignore the first, since one value sets the other, depending on the number of items.

Reading from your Pages

The Pages class is an collection of Page objects. Pages implements the \Iterator interface and can be looped over like an array i.e.

$pages = Pages::empty()->appendCollection($iterableCollectionOfItems);

foreach ($pages as $pageNumber => $page) {
	// do something
}

An indiviadual page can be accessed:

$page = $pages->getPage($pageNumber)

In both of these cases the $page variable is storing a Page instance. To access the items on a page:

$items = $page->getItems();

The Page class also implements the \Iterator interface so it can also be looped over

foreach ($page as $index => $item) {
	// do something
}

Item Indexing

Items are indexed numeriacally, there are two schemes available. By default, pages and items in a Page are indexed starting at 0, the page number is accessed via $page->getPageNumber() . At any time you can set the items in a page to index relative to the full item collection like so:

$fifthPage = Pages::empty()
	->appendCollection($oneHundredItems)
	->limitPageSize(10)
	->getPage(4)
;

$fifthPage->getPageNumber() // Returns int(4)

$items = $fifthPage
	->indexRelativeToPagination(true)
	->getItems() // returns the items on the page with sequential indexes from 40 to 49
; 	

or

foreach ($items->indexRelativeToPagination(true) as $index => $item) {
	echo $index . ", "; // will echo the numbers 40 to 49
}