Download the PHP package germania-kg/pagination without Composer

Germania KG · Pagination

Installation with Composer

Overview

Pagination: Page numbering made easy! Supports current, next, previous, first and last page numbers as well as number of pages and customizable page sizes.

PaginationFactory: Callable class for creating a Pagination instance. Works great with $_GET['page']

PaginationIterator: Limits your Traversables according to the Pagination status. Useful for paginated JSON API resources.

JsonApiPaginationDecorator: Create useful links and meta information for your JSON API resource collection.

Usage

The Pagination class

Just pass the number of items to paginate. The Pagination class will calculate the page numbers, based on a default page size of 25. See below for customization examples.

Pagination status

Right after instantiation, no page was picked by the user. Hence, the Pagination is then considered inactive.

Please note that the current page also may be int(0) – the first page. This is why we have to check against null. The isActive method is a convenient alias for $p->getCurrent() === null .

It first needs a setCurrent call to become active:

Setting the current page

Setting the page size

Whilst the default number of items on a page is 25, you may set another size—up to 100 per default:

Tweak the page sizes with constructor parameters:

The PaginationFactory

The PaginationFactory constructor also accepts instances of Countable, Traversable or arrays, so you won't have to count the items yourself. The second parameter may be a page number integer or an array with number and/or size values.

Creation from array is useful when working with query parameters such as $_GET['page']

The PaginationIterator

Limits any \Traversable iterator to the current page size, depending on the pagination status. The PaginationIterator constructor accepts your iterator and your pagination instance. It is also \Countable to count the numbers of items shown on the current page.

Which Iterator is used?

Depending on the pagination status, PaginationIterator's inner iterator used in the foreach loop is either \LimitIterator or the MyHugeIterator instance itself, when pagination is not active:

The JsonApiPaginationDecorator

This library provides a handy JsonApiPaginationDecorator which will generate useful information for your JSON API resource collection responses with the help of a given \Psr\Http\Message\UriInterface instance.

Meta information support

The meta member can be used to include non-standard meta-information, such as our pagination:

The result array will be empty, when the Pagination is inactive.

Links object support

The JSON API specs on fetching pagination proposes to use page[number] and page[size] for customizing the paged output. And it states the links object in a collection must use these key names, when working with pagination links:

• first: the first page of data
• last: the last page of data
• prev: the previous page of data
• next: the next page of data

The JsonApiPaginationDecorator generates this elements for you. The class is \JsonSerializable as well.

Default Query Parameters

The JsonApiPaginationDecorator internally calls the withQuery method on the PSR-7 $uri instance. Unfortunately, this will replace any query parameters the URI contained. Just pass any needed query parameters as 3rd constructor parameter:

Custom page sizes

In case you set a custom page size (which differs from the default size), the links will get an additional size field:

Edge cases

On the first and last page, links like previous and next do not make sense. Their value will be null:

When the pagination is not active, all values per default are null:

Filtering the results

To get a clean, uncluttered links array, you may pass a boolean filter flag as fourth constructor parameter:

Issues

See full issues list.

Development

Unit tests

Either copy phpunit.xml.dist to phpunit.xml and adapt to your needs, or leave as is. Run PhpUnit test or composer scripts like this: