The PaginationHelper class in JiFramework provides an efficient and flexible way to implement pagination in your application. It simplifies the process of dividing large datasets into manageable pages and generating pagination links for navigation. By using this class, developers can easily integrate pagination functionality without reinventing the wheel.

Key Features:

• Dynamic Pagination Data: Calculates necessary pagination parameters such as current page, total pages, offsets, and more.
• HTML Pagination Links: Generates customizable HTML pagination links, compatible with popular CSS frameworks like Bootstrap.
• Flexible Configuration: Supports custom query parameters, base URLs, and the maximum number of page links to display.

Usage:

// Option 1: Initialize the PaginationHelper through the App
use JIFramework\Core\App\App;
$app = new App();
$pagination = $app->pagination;

OR 

// Option 2: Directly instantiate the PaginationHelper
use JIFramework\Core\Utilities\Pagination\PaginationHelper;
$pagination = new PaginationHelper();

Explanation:

• Option 1: Initializes the App class and retrieves the PaginationHelper instance through it, using the framework's main entry point.
• Option 2: Directly creates a PaginationHelper instance.

Method: paginate(int $itemsPerPage, int $totalItems, array $options = []): object

Description: Calculates and returns pagination data based on the total number of items and items per page.

Parameters:

• $itemsPerPage (int): The number of items to display per page.
• $totalItems (int): The total number of items in the dataset.
• $options (array, optional): An associative array of optional parameters:
• 'currentPage' (int): The current page number. Defaults to $_GET['page'] or 1 if not set.
• 'queryParams' (array): Additional query parameters to include in pagination links.

Returns: An object containing pagination data:

• currentPage (int): The current page number.
• nextPage (int): The next page number.
• previousPage (int): The previous page number.
• offset (int): The offset to use in database queries.
• itemsPerPage (int): The number of items per page.
• totalPages (int): The total number of pages.
• queryParams (string): Query parameters to include in pagination links.

Usage:

$itemsPerPage = 10;
$totalItems = 150; // For example, total items retrieved from a database count query

$paginationData = $pagination->paginate($itemsPerPage, $totalItems);

/*
Sample $paginationData:

object(stdClass)#1 (7) {
  ["currentPage"]=> int(1)
  ["nextPage"]=> int(2)
  ["previousPage"]=> int(1)
  ["offset"]=> int(0)
  ["itemsPerPage"]=> int(10)
  ["totalPages"]=> int(15)
  ["queryParams"]=> string(0) ""
}

*/

// Use $paginationData->offset and $paginationData->itemsPerPage in your database query

Explanation:

• Determines the current page from the $options array or $_GET['page'].
• Calculates the total number of pages based on $totalItems and $itemsPerPage.
• Computes the nextPage and previousPage numbers with boundary checks.
• Calculates the offset for use in database queries (e.g., SQL LIMIT and OFFSET).
• Preserves existing query parameters, excluding 'page', and constructs a query string.
• Returns an object with all relevant pagination data for use in your application.

Method: renderPaginationLinks(object $paginationData, string $baseUrl, int $maxPagesToShow = 5): string

Description: Generates HTML pagination links based on the provided pagination data.

Parameters:

• $paginationData (object): The pagination data object returned by the paginate() method.
• $baseUrl (string): The base URL for pagination links (e.g., '/products').
• $maxPagesToShow (int, optional): The maximum number of page links to display in the pagination control. Default is 5.

Returns: A string containing HTML markup for the pagination links.

Usage:

$baseUrl = '/products'; // The base URL for the pagination links
$paginationLinks = $pagination->renderPaginationLinks($paginationData, $baseUrl);

/*
Sample $paginationLinks:

<nav aria-label="Page navigation">
  <ul class="pagination">
    <li class="page-item disabled"><span class="page-link">&laquo;</span></li>
    <li class="page-item active"><span class="page-link">1</span></li>
    <li class="page-item"><a class="page-link" href="/products?page=2">2</a></li>
    <li class="page-item"><a class="page-link" href="/products?page=3">3</a></li>
    <li class="page-item"><a class="page-link" href="/products?page=4">4</a></li>
    <li class="page-item"><a class="page-link" href="/products?page=5">5</a></li>
    <li class="page-item"><a class="page-link" href="/products?page=2">&raquo;</a></li>
  </ul>
</nav>
*/

echo $paginationLinks;

Explanation:

• Checks if pagination is necessary (i.e., total pages > 1).
• Determines the range of page numbers to display based on the current page and $maxPagesToShow.
• Generates HTML markup for previous, numbered, and next page links.
• Utilizes Bootstrap-compatible classes ('pagination', 'page-item', 'page-link') for styling.
• Incorporates preserved query parameters into the pagination links.
• Returns the HTML string, ready to be embedded in your view.