I can remember years ago when I first began coding in PHP and MySQL, how excited I was the first time I got information from a database to show up in a web browser. For someone who had little database and programming knowledge, seeing those table rows show up onscreen based on the code I wrote (okay so I copied an example from a book -- let's not split hairs) gave me a triumphant high. I may not have fully understood all the magic at work back then, but that first success spurred me on to bigger and better projects.

While my level of exuberance over databases may not be the same as it once was, ever since my first 'hello world' encounter with PHP and MySQL I've been hooked on the power of making things simple and easy to use. As a developer, one problem I'm constantly faced with is taking a large set of information and making it easy to digest. Whether its a large company's client list or a personal mp3 catalog, having to sit and stare at rows upon rows upon rows of data can be discouraging and frustrating. What can a good developer do? Paginate!

Pagination

Pagination is essentially the process of taking a set of results and spreading them out over pages to make them easier to view.

I realized early on that if I had 5000 rows of information to display not only would it be a headache for someone to try and read, but most browsers would take an Internet eternity (i.e. more than about five seconds) to display it. To solve this I would code various SQL statements to pull out chunks of data, and if I was in a good mood I might even throw in a couple of "next" and "previous" buttons. After a while, having to drop this code into every similar project and customize it to fit got old. Fast. And as every good developer knows, laziness breeds inventiveness or something like that. So one day I sat down and decided to come up with a simple, flexible, and easy to use PHP class that would automatically do the dirty work for me.

A quick word about me and PHP classes. I'm no object-oriented whiz. In fact I hardly ever use the stuff. But after reading some OOP examples and tutorials, and some simple trial and error examples, I decided to give it a whirl and you know what? It works perfectly for pagination. The code used here is written in PHP 4 but will work in PHP 5.

The Database

Gotta love MySQL. No offense to the other database systems out there, but for me all I need is MySQL. And one great feature of MySQL is that they give you some free sample databases to play with at http://dev.mysql.com/doc/#sampledb. For my examples I'll be using the world database (~90k zipped) which contains over 4000 records to play with, but the beauty of the PHP script we'll be creating is that it can be used with any database. Now I think we can all agree that if we decided not to paginate our results that we would end up with some very long and unwieldy results like the following:

(click for full size, ridiculously long image ~ 338k)

So lets gets down to breaking up our data into easy to digest bites like this:

Beautiful isn't it? Once you drop the pagination class into your code you can quickly and easily transform a huge set of data into easy to navigate pages with just a few lines of code. Really.

Paginator.class.php

Our examples will use just two scripts: paginator.class.php, the reusable pagination script, and index.php, the PHP page that will call and use paginator.class.php. Let's take a look at the guts of the pagination class script.

<?php

class Paginator{
    var $items_per_page;
    var $items_total;
    var $current_page;
    var $num_pages;
    var $mid_range;
    var $low;
    var $high;
    var $limit;
    var $return;
    var $default_ipp = 25;

    function Paginator()
    {
        $this->current_page = 1;
        $this->mid_range = 7;
        $this->items_per_page = (!empty($_GET['ipp'])) ? $_GET['ipp']:$this->default_ipp;
    }

    function paginate()
    {
        if($_GET['ipp'] == 'All')
        {
            $this->num_pages = ceil($this->items_total/$this->default_ipp);
            $this->items_per_page = $this->default_ipp;
        }
        else
        {
            if(!is_numeric($this->items_per_page) OR $this->items_per_page <= 0) $this->items_per_page = $this->default_ipp;
            $this->num_pages = ceil($this->items_total/$this->items_per_page);
        }
        $this->current_page = (int) $_GET['page']; // must be numeric > 0
        if($this->current_page < 1 Or !is_numeric($this->current_page)) $this->current_page = 1;
        if($this->current_page > $this->num_pages) $this->current_page = $this->num_pages;
        $prev_page = $this->current_page-1;
        $next_page = $this->current_page+1;

        if($this->num_pages > 10)
        {
            $this->return = ($this->current_page != 1 And $this->items_total >= 10) ? "<a class=\"paginate\" href=\"$_SERVER[PHP_SELF]?page=$prev_page&ipp=$this->items_per_page\">« Previous</a> ":"<span class=\"inactive\" href=\"#\">« Previous</span> ";

            $this->start_range = $this->current_page - floor($this->mid_range/2);
            $this->end_range = $this->current_page + floor($this->mid_range/2);

            if($this->start_range <= 0)
            {
                $this->end_range += abs($this->start_range)+1;
                $this->start_range = 1;
            }
            if($this->end_range > $this->num_pages)
            {
                $this->start_range -= $this->end_range-$this->num_pages;
                $this->end_range = $this->num_pages;
            }
            $this->range = range($this->start_range,$this->end_range);

            for($i=1;$i<=$this->num_pages;$i++)
            {
                if($this->range[0] > 2 And $i == $this->range[0]) $this->return .= " ... ";
                // loop through all pages. if first, last, or in range, display
                if($i==1 Or $i==$this->num_pages Or in_array($i,$this->range))
                {
                    $this->return .= ($i == $this->current_page And $_GET['page'] != 'All') ? "<a title=\"Go to page $i of $this->num_pages\" class=\"current\" href=\"#\">$i</a> ":"<a class=\"paginate\" title=\"Go to page $i of $this->num_pages\" href=\"$_SERVER[PHP_SELF]?page=$i&ipp=$this->items_per_page\">$i</a> ";
                }
                if($this->range[$this->mid_range-1] < $this->num_pages-1 And $i == $this->range[$this->mid_range-1]) $this->return .= " ... ";
            }
            $this->return .= (($this->current_page != $this->num_pages And $this->items_total >= 10) And ($_GET['page'] != 'All')) ? "<a class=\"paginate\" href=\"$_SERVER[PHP_SELF]?page=$next_page&ipp=$this->items_per_page\">Next »</a>\n":"<span class=\"inactive\" href=\"#\">» Next</span>\n";
            $this->return .= ($_GET['page'] == 'All') ? "<a class=\"current\" style=\"margin-left:10px\" href=\"#\">All</a> \n":"<a class=\"paginate\" style=\"margin-left:10px\" href=\"$_SERVER[PHP_SELF]?page=1&ipp=All\">All</a> \n";
        }
        else
        {
            for($i=1;$i<=$this->num_pages;$i++)
            {
                $this->return .= ($i == $this->current_page) ? "<a class=\"current\" href=\"#\">$i</a> ":"<a class=\"paginate\" href=\"$_SERVER[PHP_SELF]?page=$i&ipp=$this->items_per_page\">$i</a> ";
            }
            $this->return .= "<a class=\"paginate\" href=\"$_SERVER[PHP_SELF]?page=1&ipp=All\">All</a> \n";
        }
        $this->low = ($this->current_page-1) * $this->items_per_page;
        $this->high = ($_GET['ipp'] == 'All') ? $this->items_total:($this->current_page * $this->items_per_page)-1;
        $this->limit = ($_GET['ipp'] == 'All') ? "":" LIMIT $this->low,$this->items_per_page";
    }

    function display_items_per_page()
    {
        $items = '';
        $ipp_array = array(10,25,50,100,'All');
        foreach($ipp_array as $ipp_opt)    $items .= ($ipp_opt == $this->items_per_page) ? "<option selected value=\"$ipp_opt\">$ipp_opt</option>\n":"<option value=\"$ipp_opt\">$ipp_opt</option>\n";
        return "<span class=\"paginate\">Items per page:</span><select class=\"paginate\" onchange=\"window.location='$_SERVER[PHP_SELF]?page=1&ipp='+this[this.selectedIndex].value;return false\">$items</select>\n";
    }

    function display_jump_menu()
    {
        for($i=1;$i<=$this->num_pages;$i++)
        {
            $option .= ($i==$this->current_page) ? "<option value=\"$i\" selected>$i</option>\n":"<option value=\"$i\">$i</option>\n";
        }
        return "<span class=\"paginate\">Page:</span><select class=\"paginate\" onchange=\"window.location='$_SERVER[PHP_SELF]?page='+this[this.selectedIndex].value+'&ipp=$this->items_per_page';return false\">$option</select>\n";
    }

    function display_pages()
    {
        return $this->return;
    }
}
?>

Phew, that's a lot of code! But don't worry, I'll explain what all the different parts do and how they're used.

Have a Little Class

Let's begin at the beginning. First off we declare the class and give it a name. Paginator should do it. And while we're at it, let's set some variables, or properties in OOP speak, that our new paginator object will use.

class Paginator{
    var $items_per_page;
    var $items_total;
    var $current_page;
    var $num_pages;
    var $mid_range;
    var $low;
    var $high;
    var $limit;
    var $return;
    var $default_ipp = 25;

We start off our class by giving it a name, in this case "Paginator", and defining the variables (a.k.a the properties of an object) that we'll be using. When we create a new object using this class (a.k.a instantiating), the object will have these properties and one of them, $default_ipp (the default number of items per page), is also initialized to a value of 25.

Our class will have five methods, or member functions, which do the heavy lifting; and they're named Paginator, paginate, display_items_per_page, display_jump_menu, and display_pages.

function Paginator()
{
    $this->current_page = 1;
    $this->mid_range = 7;
    $this->items_per_page = (!empty($_GET['ipp'])) ? $_GET['ipp']:$this->default_ipp;
}

The Paginator function is also referred to as our constructor method, which just means when you create a new paginator object, this function is also called by default. When we instantiate a new paginator object, this initializes it with some default values. Here we set those variables and check to see if we've changed the number of items per page to display. If the items per page variable isn't set in the URL's query string ($_GET['ipp']), we use the default number when the class was created.

The next method, the paginate function, is the Arnold Schwarzenegger, the Jean Claude Van Damme, the meat of our class. The paginate method is what determines how many page numbers to display, figures out how they should be linked, and applies CSS for styling.

if($_GET['ipp'] == 'All')
{
    $this->num_pages = ceil($this->items_total/$this->default_ipp);
    $this->items_per_page = $this->default_ipp;
}
else
{
    if(!is_numeric($this->items_per_page) OR $this->items_per_page <= 0) $this->items_per_page = $this->default_ipp;
    $this->num_pages = ceil($this->items_total/$this->items_per_page);
}

The first part of this method determines the number of pages we'll be outputting and sets the number of items per page. First it tests to see if we want to display all the items on one page. If so, it simply displays all the items on one page and if not, it calculates the number of links it will need to output, based on the number of items per page and the total number of items. It also throws in some error checking to make sure that the number of items per page is a numeric value.

$this->current_page = (int) $_GET['page']; // must be numeric > 0
if($this->current_page < 1 Or !is_numeric($this->current_page)) $this->current_page = 1;
if($this->current_page > $this->num_pages) $this->current_page = $this->num_pages;
$prev_page = $this->current_page-1;
$next_page = $this->current_page+1;

The next part gets the page number we're on and checks to make sure that it's a number in a valid range. It also sets the previous and next page links.

The rest of the paginate method is what does all the hard work. We check to see if we have more than  ten pages (if($this->num_pages > 10)), ten being a number that you can easily change. If we don't have more than ten pages, we simply loop from one to however many pages we do have, and link them up accordingly. We don't display any previous page or next page links since we're displaying all page numbers and this would be a bit redundant, but we do display a link to all items. If we have more than ten pages, then instead of displaying links to each and every page (if we had say 200 pages to display, things might get a little ugly), we display links to the first and last page and then a range of pages around the current page that we're on. This is where the variable (property) $this->mid_range comes into play. This variable tells the paginator how many page numbers to display between the first and last pages. By default this is set to seven, however you can change it to anything you like. Just a note, the mid range value should be an odd number so the display is symmetrical, but it can be even if you like. For example, let's say we have 4000 rows of data in all, and we're viewing 50 rows of data per page. That gives us 79 pages to display, but aside from the first and last pages we're only going to display links to three pages above and below the page we're on. So if we're on page 29, the paginator will display links to page 1, 26, 27, 28, 29, 30, 31, 32, and 79 (don't worry, if you want to jump to a specific page not in that range I'll explain how to do that a little later on). As you move closer to the upper and lower page limits, the mid range adjusts itself so that you always have at least the number of page links that mid_range is set for.

The next method, display_items_per_page, is an optional method that will display a drop down menu that allows a visitor to change the number of items displayed per page. The default values for the drop down menu are 10, 25, 50, 100, and All. You can change the numeric values to anything you like, but if you want to retain the 'All' option, it must not be changed

.

function display_items_per_page()
{
    $items = '';
    $ipp_array = array(10,25,50,100,'All');
    foreach($ipp_array as $ipp_opt)    $items .= ($ipp_opt == $this->items_per_page) ? "<option selected value=\"$ipp_opt\">$ipp_opt</option>\n":"<option value=\"$ipp_opt\">$ipp_opt</option>\n";
    return "<span class=\"paginate\">Items per page:</span><select class=\"paginate\" onchange=\"window.location='$_SERVER[PHP_SELF]?page=1&ipp='+this[this.selectedIndex].value;return false\">$items</select>\n";
}

The next method, display_jump_menu, is another optional method that displays a drop down menu that will list all the page numbers available and allow a visitor to jump directly to any page. Using our previous example, if we had a total of 79 pages to display, this drop down menu would list them all so that when someone selects a page, it automatically will take them to it.

function display_jump_menu()
{
    for($i=1;$i<=$this->num_pages;$i++)
    {
        $option .= ($i==$this->current_page) ? "<option value=\"$i\" selected>$i</option>\n":"<option value=\"$i\">$i</option>\n";
    }
    return "<span class=\"paginate\">Page:</span><select class=\"paginate\" onchange=\"window.location='$_SERVER[PHP_SELF]?page='+this[this.selectedIndex].value+'&ipp=$this->items_per_page';return false\">$option</select>\n";
}

The last method, display_pages, may be the shortest method, but it's also one of the most important. This method displays the page numbers on your page. Without calling it, all the calculations would be done, but nothing would be shown to your visitor. You need to call this method at least once in order to display your pagination, but you can also use it more than once if you like. For example, you could display the page numbers above AND below your results for convenience. And convenience is what its all about, no?

So How Do I Use This Thing?

There are three things you need to do in your index.php file before being able to use your new paginator class.

1. First, include the paginator class in the page where you want to use it. I like to use require_once because it ensures that the class will only be included once and if it can’t be found, will cause a fatal error.
2. Next, make your database connections.
3. Finally, query your database to get the total number of records that you'll be displaying.

Step three is necessary so that the paginator can figure out how many records it has to deal with. Typically the query can be as simple as SELECT COUNT(*) FROM table WHERE blah blah blah.

You're almost there. Now it's time to create a new paginator object, call a few of its methods, and set some options. Once you have your total record count from step three above you can add the following code to index.php:

$pages = new Paginator;
$pages->items_total = $num_rows[0];
$pages->mid_range = 9;
$pages->paginate();
echo $pages->display_pages();

Let's break it down...

• The first line gives us a shiny new paginator object to play with and initializes the default values behind the scenes.
• The second line uses the query we did to get the total number of records and assigns it to our paginator's items_total property. $num_rows is an array containing the result of our count query (you could also use PHP's mysql_num_rows function to retrieve a similar count if you like).
• The third line tells the paginator the number of page links to display. This number should be odd and greater than three so that the display is symmetrical. For example if the mid range is set to seven, then when browsing page 50 of 100, the mid range will generate links to pages 47, 48, 49, 50, 51, 52, and 53. The mid range moves in relation to the selected page. If the user is at either the low or high end of the list of pages, it will slide the range toward the other side to accommodate the position. For example, if the user visits page 99 of 100, the mid range will generate links for pages 94, 95, 96, 97, 98, 99, and 100.
• The fourth line tell the paginator to get to work and paginate and finally the fifth line displays our page numbers.

If you decide to give your visitors the option of changing the number of items per page or jumping to a specific page, you can add this code to index.php:

echo "<span style="\"margin-left:25px\""> ". $pages->display_jump_menu() 
. $pages->display_items_per_page() . "</span>";

If you stopped here and viewed your page without adding anything else, you'd see your page numbers but no records. Aha! We haven't yet told PHP to display the specific subset of records we want. To do that you create a SQL query that includes a LIMIT statement that the paginator creates for you. For example, your query could look like:

SELECT title FROM articles WHERE title != '' ORDER BY title ASC $pages->limit

$pages->limit is critical in making everything work and allows our paginator object to tell the query to fetch only the limited number of records that we need. For example, if we wanted to see page seven of our data, and we're viewing 25 items per page, then $pages->limit would be the same as LIMIT 150,25 in SQL.

Once you execute your query you can display the records however you like. If you want to display the page numbers again at the bottom of your page, just use the display_pages method again:

echo $pages->display_pages();

More Features

As an added bonus, the paginator class adds "Previous", "Next", and "All" buttons around your page links. It even disables them when you're on the first and last pages respectively when there are no previous or next pages. If you like, you can also tell your visitors that they're viewing page x of y by using the code:

echo "Page $pages->current_page of $pages->num_pages";

Styling

Finally, you're free to customize the look of your pagination buttons as much as you want. With the exception of the current page button, all other page buttons have the CSS class "paginate" applied to them while the current page button has, can you guess, the "current" class applied to it. The "Previous" and "Next" buttons will also have the class "inactive" applied to them automatically when they're not needed so you can style them specifically. Using these three classes along with other CSS gives you tremendous flexibility to come up with a variety of styling choices.

discuss this topic to forum