rayne/pagination

Pagination library without dependencies.

Rayne\Pagination

Pagination library without dependencies., _(*1)

Contents

• Installation
• Features
• Usage
• Examples
• Tests

Installation

It's recommended to use the dependency manager Composer to install rayne/pagination., _(*2)

composer require rayne/pagination

Features

• Implementation of the Search Pagination Pattern defined by Yahoo, _(*3)

  • One or zero indexed pages, _(*4)

  • Extracts safe page numbers from arbitrary user inputs, e.g. first or last page on invalid input or when being out of bounds, _(*5)

• Implementation of the Filter Pagination Pattern defined by Yahoo, _(*6)

  (This pattern is currently not officially supported but the code is ready for playing around), _(*7)

• No dependencies (except the ones for testing), _(*8)

• Framework-agnostic, _(*9)

  • No markup (but Bootstrap examples in /examples), _(*10)

  • No template engine (but Twig examples in /examples), _(*11)

  • No database backend (but offset and limit provided), _(*12)

  • No URL builder, _(*13)

Usage

SearchPagination

1. Retrieve item count $totalItems, _(*14)

2. Let Rayne\Pagination calculate the offset, _(*15)

   $pagination = new SearchPagination(
      $totalItems,
      $itemsPerPage,
      $currentPage,
      $pagePadding = 4, 
      $isZeroBased = false
   );
   

3. Verify $currentPage with $pagination->isOnValidPage() or retrieve the requested items with the help of $pagination->getItemOffset() and $pagination->getItemLimit(), _(*16)

4. Render results and controls with the help of $pagination or $pagination->toArray() and the example templates in the /examples directory, _(*17)

Read the Examples section for examples and ideas., _(*18)

SearchPaginationFactory

Instead of creating the SearchPaginationInterface implementation by hand a configurable factory can be used to provide the pagination as a service., _(*19)

1. Either create a new factory (useful when working with a DI system) …, _(*20)

   $factory = new SearchPaginationFactory;
   

   … or initialize/fetch the global one, _(*21)

   $factory = SearchPaginationFactory::instance();
   

   The defaults are: one-indexed pages, 20 items per page and a page padding of 4., _(*22)

2. Configure the factory (or skip this step), _(*23)

   $factory->setIsZeroBased(true);
   $factory->setItemsPerPage(25);
   $factory->setPagePadding(2);
   

3. Build a new SearchPagination object, _(*24)

   $totalItems = 123;
   $currentPage = 2;
   $pagination = $factory->build($totalItems, $currentPage);
   

FilterPagination

The filter pagination pattern is not officially supported but feel free to play around with the following classes:, _(*25)

Rayne\Pagination\Filter\FilterPage
Rayne\Pagination\Filter\FilterPages
Rayne\Pagination\Filter\FilterPagination

Examples

The following examples are part of the /examples directory., _(*26)

• Complete example (/examples/index.php), _(*27)

• Simple (highlights current page) and advanced (highlights current page, hides redundant pagination controls) examples, _(*28)

  • PHP snippets (/examples/PHP), _(*29)

  • Twig macros (/examples/Twig), _(*30)

• The Twig macros are Bootstrap Framework compatible, _(*31)

Tests

1. Clone the repository, _(*32)

   git clone https://github.com/rayne/pagination.git
   

2. Install the development dependencies, _(*33)

   composer install --dev
   

3. Run the tests, _(*34)

   composer test