Usage of Pager 2.x

What is Pager?

Pager is a class to page an array of data. It is taken as input and it is paged according to various parameters. Pager also builds links within a specified range, and allows complete customization of the output (it even works with mod_rewrite). It is compatible with Pager v.1.x and Pager_Sliding API

Example 1

This simple example will page the array of alphabetical letters, giving back pages with 3 letters per page, and links to the previous two / next two pages:


<?php
require_once 'Pager.php';
$params = array(
    'mode'       => 'Jumping',
    'perPage'    => 3,
    'delta'      => 2,
    'itemData'   => array('a','b','c','d','e',[...omissis...],'z')
);
$pager = & Pager::factory($params);
$data  = $pager->getPageData();
$links = $pager->getLinks();
//$links is an ordered+associative array with 'back'/'pages'/'next'/'first'/'last'/'all' links.
//NB: $links['all'] is the same as $pager->links;

//echo links to other pages:
echo $links['all'];

//Pager can also generate <link xmlns:xlink="http://www.w3.org/1999/xlink" rel="first|prev|next|last"> tags
echo $pager->linkTags;

//Show data for current page:
echo 'PAGED DATA: ' ; print_r($data);

//Results from methods:
echo 'getCurrentPageID()...: '; var_dump($pager->getCurrentPageID());
echo 'getNextPageID()......: '; var_dump($pager->getNextPageID());
echo 'getPreviousPageID()..: '; var_dump($pager->getPreviousPageID());
echo 'numItems()...........: '; var_dump($pager->numItems());
echo 'numPages()...........: '; var_dump($pager->numPages());
echo 'isFirstPage()........: '; var_dump($pager->isFirstPage());
echo 'isLastPage().........: '; var_dump($pager->isLastPage());
echo 'isLastPageComplete().: '; var_dump($pager->isLastPageComplete());
echo '$pager->range........: '; var_dump($pager->range);
?>

In case you're wondering, $pager->range is a numeric array; its keys are the numbers of the pages in the current range, and the matching values are booleans (TRUE if its key represents currentPage, FALSE otherwise). This array can be useful to build the links manually, e.g. when using a template engine.

Example 2

This example shows how you can use this class with mod_rewite. Let's suppose we have a .htaccess like this:


---------
RewriteEngine on
#Options FollowSymlinks

RewriteBase /
RewriteRule ^articles/([a-z]{1,12})/art([0-9]{1,4})\.html$ /article.php?num=$2&amp;month=$1 [L]
---------

It should transform an url like "/articles/march/art15.html" into "/article.php?num=15&month=march"


<?php
require_once 'Pager.php';

$month = 'september';
$params = array(
    'mode'      => 'Sliding',
    'append'    => false,
    'urlVar'    => 'num',
    'path'      => 'http://myserver.com/articles/' . $month,
    'fileName'  => 'art%d.html',  //Pager replaces "%d" with page number...
    'itemData'  => array('a','b','c',[...omissis...],'z'),
    'perPage'   => 3
);
$pager = & Pager::factory($params);

$data  = $pager->getPageData();
echo $pager->links;
echo 'Data for current page: '; print_r($data);
?>

More pagers in a single page

Using more than one pager in a single page is as simple as using a different urlVar for each pager:


<?php
require_once 'Pager.php';

//first pager
$params1 = array(
    'perPage'    => 3,
    'urlVar'     => pageID_articles,  //1st identifier
    'itemData'   => $someArray
);
$pager1 = & Pager::factory($params1);
$data1  = $pager1->getPageData();
$links1 = $pager1->getLinks();

//second pager
$params2 = array(
    'perPage'    => 8,
    'urlVar'     => pageID_news,      //2nd identifier
    'itemData'   => $someOtherArray
);
$pager2 = & Pager::factory($params2);
$data2  = $pager2->getPageData();
$links2 = $pager2->getLinks();
?>

Pager and big db resultsets

If you want to paginate db resultsets, fetching them all into an array and passing it to Pager might not be the best option. You can still leverage Pager and have good performances using a wrapper. There is a sample wrapper for each one of the PEAR db abstraction systems in the /docs/examples/ dir of the package. You may use it as-is or customize it to your needs.

Adding extra variables to the querystring

If you need to add some extra variables to the querystring, use the extraVars parameter:


<?php
$params = array(
    'extraVars' => array(
        'firstKey'  => 'firstValue',
        'secondKey' => 'secondValue',
        //...
    ),
    //...
);
$pager1 = & Pager::factory($params);
?>

Important note for PHP 5 users

Since version 2.2.1, Pager works with PHP 5 too, but you must use the factory() method instead of the constructor (which is deprecated):


<?php
require_once 'Pager.php';

//wrong: 
//$pager =& new Pager($params);

//right
$pager =& Pager::factory($params);

//continue as you did before
?>

If you are using a previous revision and cannot update, you must write the following code on PHP 5:


<?php
//chose your preferred mode [Jumping | Sliding]:

//require_once 'Pager/Jumping.php';
require_once 'Pager/Sliding.php';

//$pager =& new Pager_Jumping($params);
$pager =& new Pager_Sliding($params);

//continue as you did before
?>

Pager Tutorials

There are some other online resources with in-depth coverage of what Pager can do: PEAR::Pager tutorials.

Introduction