yidas/pagination

PHP Paginator with Pager Widget (pure PHP, CI, Yii, Laravel support)

1.1.0 2023-05-29 02:43 UTC

Requires

• php: >=5.4.0

MIT

• php
• pagination
• codeigniter
• linkpager

README

PHP Paginator with Pager Widget (pure PHP, CI, Yii, Laravel support)

Features

• Compatible with pure PHP, Codeigniter, Yii & Laravel

• SOLID principle with Yii 2 pattern like

• Pagination Widget (View Block) included

OUTLINE

• Demonstration
• Requirements
  • PDO with pure PHP
  • Codeiginter 3 Framework
  • Widget Render
• Installation
  • Codeigniter 3
• Configuration
  • Inheritance
• Usage
  • Widget
    • Customized View
    • Inheritance
  • Build URL
• API Documentation
• Examples
  • PDO with pure PHP
  • Codeiginter 3 Framework
• References

DEMONSTRATION

PDO with pure PHP

// Get count of data set first
$sql = "SELECT count(*) FROM `table`"; 
$count = $conn->query($sql)->fetchColumn(); 

// Initialize a Data Pagination with previous count number
$pagination = new \yidas\data\Pagination([
    'totalCount' => $count,
]);

// Get range data for the current page
$sql = "SELECT * FROM `table` LIMIT {$pagination->offset}, {$pagination->limit}"; 
$sth = $conn->prepare($sql);
$sth->execute();
$data = $sth->fetchAll();

Codeiginter 3 Framework

$query = $this->db->where('type', 'C');

// Clone same query for get total count
$countQuery = clone $query;

// Get total count from cloned query
// Or you could use count_all_results('', false) to keep query instead of using `clone`
$count = $countQuery->count_all_results();

// Initialize a Data Pagination with previous count number
$pagination = new \yidas\data\Pagination([
    'totalCount' => $count,
]);

// Get range data for the current page
$records = $query
    ->offset($pagination->offset)
    ->limit($pagination->limit)
    ->get()->result_array();

Widget Render

<div>
<?=\yidas\widgets\Pagination::widget([
    'pagination' => $pagination
])?>
</div>

$pagination is the object of yidas\data\Pagination.

REQUIREMENTS

This library requires the following:

• PHP 5.4.0+

INSTALLATION

Run Composer in your project:

composer require yidas/pagination

Then initialize it at the bootstrap of application such as config file:

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

Codeigniter 3

Run Composer in your Codeigniter project under the folder \application:

composer require yidas/pagination

Check Codeigniter application/config/config.php:

$config['composer_autoload'] = TRUE;

You could customize the vendor path into $config['composer_autoload']

CONFIGURATION

The simple config and usage could refer to Demonstration.

When you are dealing with pagination, you could new yidas\data\Pagination with configuration to get pager information for data query. For example:

// Get total rows from your query
$count = $query->count();
// Initialize a Data Pagination
$pagination = new \yidas\data\Pagination([
    'totalCount' => $count,
    'pergpage' => 10,
]);
// ...use $pagination offset/limit info for your query

For more parameters, you could refer to API Documentation.

Inheritance

You could build your application data Pagination with styles Inherited from yidas\data\Pagination. For example:

namespace yidas\data;

use yidas\data\Pagination as BasePagination;

class Pagination extends BasePagination
{
    // Name of the parameter storing the current page index
    public $pageParam = 'page';
    
    // The number of items per page
    public $perPage = 10;
    
    // Name of the parameter storing the page size
    // false to turn off per-page input by client
    public $perPageParam = false;
}

USAGE

When there are too much data to be displayed on a single page, a common strategy is to display them in multiple pages and on each page only display a small portion of the data. This strategy is known as pagination.

This library uses a yidas\data\Pagination object to represent the information about a pagination scheme. In particular,

• total count specifies the total number of data items. Note that this is usually much more than the number of data items needed to display on a single page.
• page size specifies how many data items each page contains. The default value is 20.
• current page gives the current page number (not zero-based). The default value is 1, meaning the first page.

With a fully specified yidas\data\Pagination object, you can retrieve and display data partially. For example, if you are fetching data from a database, you can specify the OFFSET and LIMIT clause of the DB query with the corresponding values provided by the pagination. Below is an example:

/**
 * Yii 2 Framework sample code
 */
use yidas\data\Pagination;

// build a DB query to get all articles with status = 1
$query = Article::find()->where(['status' => 1]);

// get the total number of articles (but do not fetch the article data yet)
$count = $query->count();

// create a pagination object with the total count
$pagination = new Pagination(['totalCount' => $count]);

// limit the query using the pagination and retrieve the articles
$articles = $query->offset($pagination->offset)
    ->limit($pagination->limit)
    ->all();

Widget

To facilitate building the UI element that supports pagination, This library provides the yii\widgets\Pagination widget that displays a list of page buttons upon which users can click to indicate which page of data should be displayed. The widget takes a pagination object so that it knows what is the current page and how many page buttons should be displayed. For example,

use yidas\widgets\Pagination;

echo  Pagination::widget([
    'pagination' => $pagination
]);

$pagination is a yidas\data\Pagination object for data provider.

Customized View

The default widget view is for Bootstrap(bootstrap), you could choose a template view for your Pagination Widget:

echo  \yidas\widgets\Pagination::widget([
    'pagination' => $pagination,
    'view' => 'simple',
]);

You can also use your customized view for Pagination widget:

echo  \yidas\widgets\Pagination::widget([
    'pagination' => $pagination,
    'view' => __DIR__ . '/../widgets/pagination_view.php',
]);

Inheritance

You could build your application Pagination Widget with styles Inherited from yidas\widgets\Pagination. For example:

<?php

namespace app\widgets;

use yidas\widgets\Pagination as BaseWidget;

/**
 * Pagination Widget
 */
class Pagination extends BaseWidget
{
    // Set the Widget pager is center align or not   
    public $alignCenter = false;
    
    // Maximum number of page buttons that can be displayed   
    public $buttonCount = 7;

    // The text label for the "first" page button
    public $firstPageLabel = '<i class="fa fa-step-backward" aria-hidden="true"></i>';

    // The text label for the "last" page button
    public $lastPageLabel = '<i class="fa fa-step-forward" aria-hidden="true"></i>';
    
    // The text label for the "next" page button
    public $nextPageLabel = '<i class="fa fa-caret-right" aria-hidden="true"></i>';
    
    // The text label for the "previous" page button
    public $prevPageLabel = '<i class="fa fa-caret-left" aria-hidden="true"></i>';
    
    // <ul> class. For example, 'pagination-sm' for Bootstrap small size.
    public $ulCssClass = '';
}

Build URL

If you want to build UI element manually, you may use yidas\data\Pagination::createUrl() to create URLs that would lead to different pages. The method requires a page parameter and will create a properly formatted URL containing the page parameter. For example:

// ex. https://yoursite.com/list/
// displays: https://yoursite.com/list/?page=100
echo $pagination->createUrl(100);

// ex. https://yoursite.com/list/?sort=desc&type=a
// displays: https://yoursite.com/list/?sort=desc&type=a&page=101
echo $pagination->createUrl(101);

The formatted URL pattern is //{current-host-uri}{parameters-with-pagination}

You could also build a per-page setting URL for changing per-page when perPageParam is set:

// ex. https://yoursite.com/list/
// displays: https://yoursite.com/list/?page=1&per-page=50
echo $pagination->createUrl(1, 50);

EXAMPLES

PDO with Pure PHP

$conn = new PDO("mysql:host=localhost;dbname=database", 'username', 'password');

// Get count of data set first
$sql = "SELECT count(*) FROM `table`"; 
$count = $conn->query($sql)->fetchColumn(); 

// Initialize a Data Pagination with previous count number
$pagination = new \yidas\data\Pagination([
    'totalCount' => $count,
]);

// Get range data for the current page
$sql = "SELECT * FROM `table` LIMIT {$pagination->offset}, {$pagination->limit}"; 
$sth = $conn->prepare($sql);
$sth->execute();
$data = $sth->fetchAll();

print_r($data);

LinkPager display:

echo yidas\widgets\Pagination::widget([
    'pagination' => $pagination
]);

Codeiginter 3 Framework

Codeiginter 3 Framework with yidas/codeigniter-model:

$this->load->model('Post_model');

$query = $this->Post_model->find()
    ->where('type', 'C');
    
// Clone same query for get total count
$countQuery = clone $query;

// Get total count from cloned query
// Or you could use count(false) to keep query instead of using `clone`
$count = $countQuery->count();

// Initialize a Data Pagination with previous count number
$pagination = new \yidas\data\Pagination([
    'totalCount' => $count,
]);

// Get range data for the current page
$records = $query
    ->offset($pagination->offset)
    ->limit($pagination->limit)
    ->get()->result_array();

LinkPager in view:

<div>
<?=yidas\widgets\Pagination::widget([
    'pagination' => $pagination
])?>
</div>

API DOCUMENTATION

Data Pagination

Widget Pagination

REFERENCES

Yii 2 PHP Framework - Displaying Data: Pagination

Yii 2 PHP Framework - Class yii\data\Pagination