delight-im/pagination

Helps partition items across pages and generates sets of convenient controls for navigation

v1.0.0 2024-07-23 12:46 UTC

Requires

• php: >=5.6.0

MIT

• page
• paging
• paginator
• pagination

README

Helps partition items across pages and generates sets of convenient controls for navigation

Requirements

• PHP 5.6.0+

Installation

1. Include the library via Composer [?]:

   $ composer require delight-im/pagination

2. Include the Composer autoloader:

   require __DIR__ . '/vendor/autoload.php';

Usage

Creating an instance

$numberOfItems = 1000;
$pagination = new Pagination($numberOfItems);

// or

$numberOfItems = 1000;
$itemsPerPage = 30;
$pagination = new Pagination($numberOfItems, $itemsPerPage);

// or

$numberOfItems = 1000;
$itemsPerPage = 30;
$currentPage = 10;
$pagination = new Pagination(
    $numberOfItems,
    $itemsPerPage,
    $currentPage
);

If you don’t specify the current page explicitly in the third argument, it will be auto-detected from the page or p query parameters, if available.

Displaying a pagination bar

Simple HTML

$targetUrl = '/products/drinks/?page={page}';
echo $pagination->toHtml($targetUrl);

// or

$targetUrl = '/products/drinks/?page={page}';
$numberOfControls = 11;
$showFirstLast = true;
$showPreviousNext = true;
$previousLabel = '« Previous';
$nextLabel = 'Next »';
echo $pagination->toHtml(
    $targetUrl,
    $numberOfControls,
    $showFirstLast,
    $showPreviousNext,
    $previousLabel,
    $nextLabel
);

Bootstrap front-end framework

$targetUrl = '/products/drinks/?page={page}';
echo $pagination->toHtmlForBootstrap5($targetUrl);

// or

$targetUrl = '/products/drinks/?page={page}';
$displaySize = 0; // -1 = small, 0 = normal, +1 = large
$numberOfControls = 11;
$showFirstLast = true;
$showPreviousNext = true;
$previousLabel = '« Previous';
$nextLabel = 'Next »';
echo $pagination->toHtmlForBootstrap5(
    $targetUrl,
    $displaySize,
    $numberOfControls,
    $showFirstLast,
    $showPreviousNext,
    $previousLabel,
    $nextLabel
);

Instead of Pagination#toHtmlForBootstrap5, you can also call Pagination#toHtmlForBootstrap4 or Pagination#toHtmlForBootstrap3 with the same method signature.

Custom HTML

First, generate an array of PaginationElement objects:

$controls = $pagination->build();

// or

$numberOfControls = 11;
$showFirstLast = true;
$showPreviousNext = true;
$previousLabel = '« Previous';
$nextLabel = 'Next »';
$controls = $pagination->build(
    $numberOfControls,
    $showFirstLast,
    $showPreviousNext,
    $previousLabel,
    $nextLabel
);

Then turn these PaginationElement objects into custom HTML:

foreach ($controls as $control) {
    // $control->getLabel();
    // $control->getPage();
    // $control->isSelected();
    // $control->isDisabled();
}

Adjusting database queries

$pagination->getOffset();
// int(1000)

$pagination->getLimit();
// int(25)

You can use these two values in your database queries, for example like this:

$sql = "SELECT * FROM products LIMIT " . $pagination->getOffset() . ", " . $pagination->getLimit();

// or

$sql = "SELECT * FROM products LIMIT " . $pagination->getLimit() . " OFFSET " . $pagination->getOffset();

Contributing

All contributions are welcome! If you wish to contribute, please create an issue first so that your feature, problem or question can be discussed.

License

This project is licensed under the terms of the MIT License.