kodhe / pagination

2.0.0 2026-09-28 21:42 UTC

Requires

• php: >=8.1

MIT

Published on Packagist.org on 2026-09-29 18:31 UTC

README

A pagination package — a refactored version of the CodeIgniter 3 Pagination library under the Kodhe\Framework\Pagination namespace. Besides the complete CI3 API (initialize() + create_links()), this package adds a modular layer: pluggable renderers (default / Bootstrap / Tailwind) and URL builders (URI segment / query string) selectable via configuration, plus an internal link cache.

Installation

composer require kodhe/pagination

Requirements: PHP >= 8.1. No external dependencies.

Quick Start

<?php

declare(strict_types=1);

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

use Kodhe\Framework\Pagination\Pagination;

$config = [
    'base_url'   => 'http://localhost/article/index/',
    'total_rows' => 200,          // total number of data rows
    'per_page'   => 10,           // rows per page
    'num_links'  => 2,            // number of neighbour links left/right of the active page
    'uri_segment'=> 3,            // URI segment position holding the page number
];

$pagination = new Pagination($config);

echo $pagination->create_links();
// <ul class="pagination">... <li><a href=".../index/2">2</a></li> ...</ul>

Directory Structure

src/
├── Pagination.php              # Main class (CI3-compatible API)
├── Contracts/                  # RendererInterface, UrlBuilderInterface
├── Renderers/                  # DefaultRenderer, BootstrapRenderer, TailwindRenderer
├── Url/                        # SegmentUrlBuilder, QueryStringUrlBuilder
├── Factory/RendererFactory.php
├── Support/                    # PaginationBuilder, AttributeHelper, LinkCache
├── ValueObjects/               # LinkData, PaginationConfig
├── language/pagination_lang.php
└── helpers.php                 # render_pagination() — quick Bootstrap 5 helper

Usage

1. CI3 style (separate initialize)

$pagination = new Pagination();
$pagination->initialize([
    'base_url'   => site_url('article/index/'),
    'total_rows' => $this->article_model->count_all(),
    'per_page'   => 10,
    'cur_page'   => (int) $this->uri->segment(3), // optional; by default read from uri_segment
]);

$data['links'] = $pagination->create_links();

2. Pages via query string (?page=N)

$pagination = new Pagination([
    'base_url'             => 'http://localhost/article',
    'total_rows'           => 200,
    'per_page'             => 10,
    'page_query_string'    => true,
    'query_string_segment' => 'page',   // default 'per_page', change to 'page'
    'use_page_numbers'     => true,
]);
echo $pagination->create_links();       // http://localhost/article?page=2

3. Choosing a renderer (Bootstrap / Tailwind)

The public renderer_name property is read during initialize():

$pagination = new Pagination();
$pagination->renderer_name = 'bootstrap';  // or 'tailwind', default 'default'
$pagination->initialize($config);
echo $pagination->create_links();

• default — plain markup with opening/closing tags from the CI3 config (full_tag_open, cur_tag_open, etc.)
• bootstrap — ready-to-use Bootstrap 5 <nav><ul class="pagination">…</ul></nav>
• tailwind — Tailwind utility-class markup

4. Customizing labels & appearance (CI3 compatible)

$pagination->initialize([
    'base_url'        => 'http://localhost/product/index/',
    'total_rows'      => 500,
    'per_page'        => 25,
    'first_link'      => '« First',
    'last_link'       => 'Last »',
    'next_link'       => 'Next',
    'prev_link'       => 'Previous',
    'full_tag_open'   => '<nav class="mx-auto">',
    'full_tag_close'  => '</nav>',
    'cur_tag_open'    => '<span class="badge bg-primary">',
    'cur_tag_close'   => '</span>',
    'display_pages'   => true,
    'anchor_class'    => 'link-underline',
]);

5. Quick Bootstrap 5 helper

For CI3 projects with a kodhe() instance, a procedural helper is available:

echo render_pagination(site_url('article'), 200, 10, 'page');

(It must be loaded manually: require pagination/src/helpers.php or load it via the framework's helper loader.)

Configuration

Property	Default	Description
base_url	''	Base pagination URL
total_rows	0	Total data rows (required)
per_page	10	Rows per page
num_links	2	Number of numbered links around the active page
cur_page	0	Active page (0 = read automatically)
uri_segment	3	URI segment storing the page number
use_page_numbers	false	true: links are page numbers; false: offsets
page_query_string	false	true: use a query string instead of a URI segment
query_string_segment	'per_page'	Query string parameter name
first_link/next_link/prev_link/last_link	CI3	Navigation labels
*_tag_open/*_tag_close	''	Wrapper for each part
first_url	''	Custom URL for the first page
display_pages	true	Show/hide the page number list
prefix / suffix	''	Added before/after the page number
reuse_query	CI3	Keep other GET parameters in the links
renderer_name	'default'	default | bootstrap | tailwind

API Reference (summary)

Method	Description
__construct(array $params = [])	Creates an instance, optionally calling initialize() right away
initialize($params = [])	Sets the config & prepares the renderer/url-builder; returns $this
create_links()	Generates the pagination HTML (string)
parse_string($template, $data, $return)	Renders a simple template with data

CodeIgniter 3 Compatibility

All CI_Pagination properties and behavior are preserved — it is a drop-in replacement. The only additions are renderer_name and the internal modular components; if unused, the output is identical to CI3.

Notes

• The link cache (LinkCache) is enabled by default (enable_cache = true) and cleared on every initialize().
• create_links() returns an empty string when total_rows <= 0 or there is only one page.
• The modular layer (Renderers/, Url/, Support/) is still evolving; the stable API is Pagination + the helper.

Testing

vendor/bin/phpunit --filter Pagination