Changes

• No more SQL errors if using the class on a query with no results (although I fail to see the point of using it on an empty query anyway, but the bug is fixed)
• When selecting ‘ALL’ only one page is displayed, and if you are using the display_items_per_page drop-down menu, ‘ALL’ is now selected as well.
• If a page less than page one, or greater than the total number of pages is requested, no results are displayed and the appropriate prevous/next links are disabled
• The items per page array that populates the display_items_per_page drop-down menu is now an option that can be configured when instantiating the class. Previously this was hard-coded to the class.
• The $high option has been removed from the class (it was never used).

Note that if you receive a PHP notice about undefined indexes that you should turn down your error reporting. This notice may be displayed when loading the page for the first time when no $_GET variables are present. The class accounts for this, however PHP throws a notice about it.

Examples

• Basic example
• Form variables carry over example

I’ve also added license info at the head of the class (CC Attribution-ShareAlike 3.0 Unported (CC BY-SA 3.0)).

Download

• PHP Pagination Class v2

I’ve seen code wrapped at 80 columns plenty of times before, but something about picking apart this code at that moment made me suddenly ask why. What was so special about this 80 column “standard” and why was it seen throughout the programming world? When I first started out coding this was just assumed to be the way to do things but I had never fully heard an explanation as for why this was done.

As it turns out the answer lies in old technology and tradition. In the early days of coding,  text based terminal displays were only 80 characters wide, so any lines longer than 80 characters needed to be wrapped. There just wasn’t any choice in the matter. Remember that GUIs and mice didn’t exist back then and scrolling was typically done only vertically. Some people believe that the even older computing method of using punch cards, which also typically had 80 columns, is the reason for this style of coding, however while it may have influenced the design of those old terminals, I don’t believe that punch cards directly gave way to practice of coding text at 80 columns.

Now since virtually no one uses an old terminal to write code, and today’s monitors are larger and have larger display resolution than older machines, why do we still see this? The answer? Tradition. Well that and readability. While most modern code editors will let you type a single line for as long as you want, reading that line becomes a huge pain in the ass. You’re forced to scroll horizontally to the right to read the code or comment, and then scroll back to the left to get back to the rest of the code. While an 80 column limit might seem constrictive or limiting, it actually makes code easier to read, and can help you write better code by making you find ways to shrink your code down to fit in one line. Another advantage to limiting the characters per line is code comparison. By staying with the 80 column rule you can usually fit two files side by side and examine them line by line quite easily.

Oh and while 80 columns is sort of a standard, 72 and 76 column layout are also quite common, but slightly more restrictive. Personally I am lazier than I like to admit and I often don’t pay a load of attention to how many columns each line of my code takes up. But that’s being both a bit lazy and selfish. By making your code readable, it helps you and anyone else looking at it…and you just know you’re going to need another set of eyes looking at your code at some point to help ferret out a bug down the line. And while I’m no advocate for 80 columns, if you stick with a layout that makes your code easy to read why not pick something like 100, 120, or 132 columns now that most people have larger monitors? Being lazy I also don’t think that any of this should be a rule but more of a suggestion or guideline. Bottom line, once you get your code to work the way you want it to, why not make it look good and improve the readability at the same time?

a:6:{s:5:"width";i:250;s:6:"height";i:323;s:14:"hwstring_small";s:22:"height='96' width='74'";s:4:"file";s:72:"/uploads/2008/04/wireframes7.jpg";s:5:"sizes";a:2:{s:9:"thumbnail";a:3:{s:4:"file";s:23:"wireframes7-150x150.jpg";s:5:"width";i:150;s:6:"height";i:150;}s:6:"medium";a:3:{s:4:"file";s:23:"wireframes7-232x300.jpg";s:5:"width";i:232;s:6:"height";i:300;}}s:10:"image_meta";a:10:{s:8:"aperture";i:0;s:6:"credit";s:0:"";s:6:"camera";s:0:"";s:7:"caption";s:0:"";s:17:"created_timestamp";i:0;s:9:"copyright";s:0:"";s:12:"focal_length";i:0;s:3:"iso";i:0;s:13:"shutter_speed";i:0;s:5:"title";s:0:"";}}

Whoa. Looked like some sort of delimited data (it is) but not in a form I recognized. Now over the years I thought I had seen my share of input that is stored in a database. Like most PHP developers I didn’t learn PHP through a class, I learned it by reading and trial and error, but I don’t remember seeing something like this before. Now some of you already know what kind of data this is while others are probably scratching your head and wondering what kind of strange delimited data this is. Isn’t it obvious, that’s an array.

Serialization

According to Wikipedia, serialization “is the process of converting an object into a sequence of bits so that it can be persisted on a storage medium (such as a file, or a memory buffer) or transmitted across a network connection link. When the resulting series of bits is reread according to the serialization format, it can be used to create a semantically identical clone of the original object.”

Now that I’ve gotten the obligatory definition out of the way, let’s humanize exactly what we’re talking about with a real world example.

Let’s say that you have a feedback form on your website and you want to store all the feedback in a database so that you can analyze it later. Along with the feedback that visitors provide you’re also interested in storing the date and time of their visit, their IP address, and some other information. One way to do this would be to create a table where you had a column for each field in your form. Every record entered in the table would need to insert each field of your feedback form, and other data you wanted to store (e.g. IP address, time submitted), into the table with a long SQL statement. Later if you needed to change your form, say add or remove a field, then you would not only need to change your table schema, but you’d also have to alter your SQL statement. Managing the feedback data this way would also result in the database table growing quite large over time. Since you can’t insert an object or array into a MySQL database (you’ll see an error like Unknown column ‘Array’ in ‘field list’ ) it would be nice if there was another way to easily store all the values we receive, especially if the number of fields could change. So what’s the alternative? PHP’s serialize() function.

PHP’s serialize function was designed for just this sort of job. What it does is basically flatten an array or object into a string (according to php.net, it “Generates a storable representation of a value”). Using our feedback form example, we could pass the $_POST array through the serialize function, and end up with a string which we can store in our database. When the serialize function is done doing its magic with whatever you throw at it, the output is a whole bunch of curly braces and semicolons which looks similar to a:1:{i:0;s:7:"slugdiv";} and the example in the first paragraph. (Note that whenever you enter user submitted data its a good idea to run it through the PHP mysql_real_escape_string function first.) So serializing an array converts it from the array to a string:

All the array keys and values are preserved by the serialize function so that they can be reconstituted later. If we use serialize() to store our feedback form data, we can eliminate all the fields in our table and just keep the one field for our serialized string. That’s a big space saver. Plus, by storing just the one serialized string in our database we can greatly simplify our SQL statements and no matter how many times we change our form, all the array contents will neatly fit in our table without it or the SQL statements needing to be modified.

Right about now you might be asking, well that’s pretty cool but how do I get my data back out of the database when I need it? No need to fear, just use unserialize() to reverse the process. If you assign the output of unserialize() to a variable then that variable will be a clone of what the original input was. Unserialize will keep all the keys and values of our feedback form’s $_POST array so that they’re instantly available just as they were when they were first created. For example, if you retrieved a serialized row from our table, we could run it through the unserialize function and assign the output to a variable: $reconstituted = unserialize($row['feedback']);.

Sounds great, so what’s the down side? Well by storing our feedback form data in serialized form in the database we lose the ability to use SQL to manipulate the data. So if we wanted to run a query that returned only the email addresses for all of our feedback, then we’d be out of luck. We’d have to use PHP to pull all the data out of the table, unserialize it, and then search through it using PHP instead of MySQL. If our data was stored in unserialized form, where each column corresponded to a field in our feedback form, then searching through and manipulating the data would be far faster and easier with MySQL. So knowing when to use serialization is important. Storing user preferences, or say attributes for an image (like WordPress does), is a perfect use for serialization. If you’ll have the need to search, update or delete parts of serialized data, or otherwise manipulate parts of the data you’re storing, then serialization may not be the way to go. However if you simply need to store arrays or objects in a database so that they can be pulled out in their entirety later, it may be the perfect solution.

Note that the MySQL site seems to be undergoing some updates and the sample databases are hard to find. If the above links don’t work try http://dev.mysql.com/doc/index-other.html

echo "Your IP address is {$_SERVER['REMOTE_ADDR']}";

Why were those curly brackets in the echo statement and why wasn’t this giving me errors? I removed the curly brackets and as expected, I received syntax errors. Apparently the {} were magical. Now in my own code, I would typically write the above line like:

echo "Your IP address is " . $_SERVER['REMOTE_ADDR'];

or

echo "Your IP address is $_SERVER[REMOTE_ADDR]";

Now method one is perfectly valid code, but it’s a bit ugly having to starty and stop the string to insert a variable. Method 2 is somewhat wrong as the quotes have been removed from the server array key.  According to php.net, “Always use quotes around a string literal array index. For example, $foo['bar'] is correct, while $foo[bar] is not.” But with this new, more compact method, I could make my code cleaner.  I was off to learn more.

After some searching I discovered that PHP will allow you to place curly brackets around a variable in a string (either around the entire variable or with the dollar sign sticking out). “If a dollar sign ($) is encountered, the parser will greedily take as many tokens as possible to form a valid variable name. Enclose the variable name in curly braces to explicitly specify the end of the name. Similarly, an array index or an object property can be parsed. With array indices, the closing square bracket (]) marks the end of the index. The same rules apply to object properties as to simple variables. ” Who knew? I must’ve missed this day during PHP 101 class. Here’s the example from the manual:

<?php
$beer = 'Heineken';
echo "$beer's taste is great"; // works; "'" is an invalid character for variable names
echo "He drank some $beers";   // won't work; 's' is a valid character for variable names but the variable is "$beer"
echo "He drank some ${beer}s"; // works
echo "He drank some {$beer}s"; // works
?>

So in a nushell, when using variables in a string you are allowed to enclose the varable in curly brackets to allow variable expansion without having to jump in and out of quotes, or drop quotes. Who doesn’t love PHP?

if (hours < 24 && minutes < 60 && seconds < 60)
{
 return true;
}
else
{
 return false;
}

This is known as Allman style (named after Eric Allman, the developer of sendmail). The most common variant of this would be K&R style (from Kernighan and Ritchie’s book The C Programming Language) and the same code looks like this:

if (hours < 24 && minutes < 60 && seconds < 60) {
 return true;
} else {
 return false;
}

Equivalent in every way except readability. Some people call this “The One True Brace Style” because it’s been around so long. The major difference is that the opening bracket is placed at the end of the line that the control statement is on where in Allman style the brackets are each on their own line.

To me it makes sense to make code as readable as possible by lining up brackets to match the block they go with. It becomes apparent what blocks of code belong to what conditions.

Allman style

K&R style

If I was to have another condition nested within the example, it would look like this:

if (hours < 24 && minutes < 60 && seconds < 60)
{
 if(hours % 2 == 0)
 {
 	return true;
 }
 else
 {
 	return false;
 }
}

Again, very readable.

The funny thing about K&R style is that its roots seems to be based in the fact that programmers used to have to deal with limited screen space and by squishing the brackets together with the blocks that they belonged to, it saved precious screen real estate. Most programmers either picked up the style they use most often from learning coding in a class or by following the examples set by others, while other programmers code for readability, especially now that space isn’t the issue it once was.

While Allman and K&R are just two of the most popular styles (see
http://en.wikipedia.org/wiki/Indent_style and
http://en.wikipedia.org/wiki/Programming_style
for some others and a detailed explanation about the history of each)

(please pardon the less than perfect wordpress code formatting)

Pagination just means numbering pages. In the project that I was working on, I was retrieving large amounts of data from a MySQL database and realized that I would have to break the data up into pages for two main reasons, 1) there was so much data that it could hang the browser when it was loading and 2) from a user perspective (we still care about that right?) it was unruly to say the least. If I was returning 50,000 rows from a database query, I knew that I would need to slice that up into more manageable chunks. Now in the past, I had written basic pagination functions to handle this type of issue and sometimes copied and pasted functions from older scripts to cut down on development time, fixing and re-coding where necessary. But I realized that for this new project I could try to write a pagination class that I would be able to just plug into any script and have it do the pagination for me. I could write a pagination class that I could use for my projects and future projects, and learn OOP in the process. I love killing two birds with one stone.

Which brings me to our pagination class (paginator.class.php). Now I’m not claiming to be the first person to write a pagination class — far from it. But I do feel that this one is the most lightweight, feature-rich, and easy to use that I’ve seen. For an example of the pagination class in action, click here.

To download the pagination class, click here.

Update (Aug 4, 2009): Some of you have asked for more examples of the PHP pagination class I wrote, specifically the same examples I’m using here on the site. The database comes from MySQL’s free example databases available at http://dev.mysql.com/doc/#sampledb (my example uses the world database). The two examples I use here can be seen at http://www.catchmyfame.com/paginator/example.php and http://www.catchmyfame.com/paginator/example-form.php. You can download both PHP files in a zip file. You’ll need to setup the database yourself and fill in the example PHP files with your database info. Don’t forget to grab the sample database from MySQL.

Update (Oct 25, 2011): Version 2 now available for download. See here for more info. Note that the examples on this page still use an older version of the class.

In the example below, you can see the paginator used at the top and bottom of the database query.

In this example, you can see the mid range property which creates a range of pages around the current page and the use of … to distinguish the break between contiguous pages

In this example you can see the optional items per page drop down menu

In this example you can see the optional page jump menu

In this example we see how the previous and next buttons are sensitive to what the current page is.

This example shows how when there are less than 11 pages to display that the previous, next, and all links are not shown

This example shows an alternate styling of the pagination results. By default a Digg-like CSS scheme is used however you can style the menu in limitless ways

Paginator.class.php

The paginator class allows you to easily generate page numbers and restrict database results without having to create complex pagination code of your own.

Features:

• Easy to use and reuse.
• Dynamically creates page numbers based on the total number of items in a query and the desired number of items per page.
• Ability to select a number of pages to display around the currently select page.
• Links to show all results instead of paginated results.
• Easily styled via CSS.
• Returns SQL which can be used to modify the results in query.
• The items per page can be changed by the user using a build in method which generates a simple drop down menu.
• A ‘jump to page’ menu can be generated to give the user quick access to jump to any page of the results.
• Creates ‘previous’ and ‘next’ buttons when more than 10 pages are generated.

Properties:

• $items_per_page – The desired number of items to be shown on a page. If you use this and the display_items_per_page method at the same time, it will override anything the user chooses from the drop down menu created by display_items_per_page.
• $items_total – The total number of items you’ll be paginating. Typically set by querying a table for a count of rows.
• $current_page – The page the user is viewing. Will always be an integer >= 1.
• $num_pages – The total number of pages as generated by the paginator method.
• $mid_range – The number of pages to show ‘around’ the current page. See step 5 in How To Use below.
• $low – The offset to use in a SQL LIMIT statement (e.g. SELECT * FROM employees LIMIT 20,10).
• $high – The number of rows to select in a SQL LIMIT statement (e.g. SELECT * FROM employees LIMIT 20,10).
• $limit – A string used in an SQL statement to automatically handle the limiting of results based on the current page of results.
• $return – A string used to store the HTML containing the page numbers.Used in the display_pages method.
• $default_ipp = 25 – The default number of items to display per page.

Methods:

• Paginator. Constructor. Usage: $pages = new Paginator;
• paginate. Calculates pages to display. Usage: $pages->paginate();
• display_items_per_page. Returns a string of HTML used to display an items per page menu. Usage: echo  $pages->display_items_per_page();
• display_jump_menu. Returns a string of HTML used to display a page jump menu. Usage: echo $pages->display_jump_menu();
• display_pages. Returns a string of HTML used to display the pages generated by the paginator
  method. Usage: echo $pages->display_pages();

How to use:

1. Include paginator.class.php at the top of your scriptrequire_once 'paginator.class.php';Note: You could use include(), include_once(), or require() however using require_once ensures that the class will only be included once and if it can’t be found, will cause a fatal error.
2. Set the total number of items that you’ll be paginating.There are two ways to do this, 1) you can hard code the total, but that’s unrealistic since you’ll probably be using this class to paginate a database anyway (the whole point no?) but it can be a convenient way of testing or 2) make a quick call to your database to count the items you’ll be paginating. Ex: ‘SELECT COUNT(*) FROM table’ and save the total in a variable for use in step 4.$pages->items_total = $num_rows;
3. Create a new Paginator object.$pages = new Paginator;
4. Set the total items property of this new Paginator object.$pages->items_total = X where X is the total from step 2
5. Set the mid range property.The mid range is the number of pages that the paginator will display, centered around and including the selected page. For example, if the mid range is set to seven ($pages->mid_range = 7;) then when browsing page 50 of 100, the mid range generates 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.$pages->mid_range = X; where X is odd and >=3. The default mid_range property is 7.
6. That’s all for the configuration, now you can generate page numbers. To paginate, call the pagination method ($pages->paginate();). This generates no output so to show the page numbers call the display method ($pages->display_pages();).
   You MUST call the paginate method before calling the display method. You can call the display method more than once which can be handy for display page numbers both above and below a result set.echo $pages->display_pages();
7. Optionally, you can give the visitor features in addition to what is provided by the display method.
   1. A drop down page jump menu is available via the display_jump_menu method (echo $pages->display_jump_menu();). This is a simple select menu that lists all page numbers. When a user changes the page number, the page will automatically switch to the selected page.
   2. A drop down items per page menu is available via the display_items_per_page method(echo $pages->display_items_per_page();). This select menu allows visitors to change the number of items that are displayed on a page. By default, the list it generates is 10, 25, 50, 100, All. You can modify the class if needed to allow for other options however the All options is case-sensitive. Note that the drop down menu that this creates will not work if you also set the $items_per_page property. Using both at the same time doesn’t really make sense anyway
8. Once the paginate method has been called (see step 6), you can execute your db query to fetch the limited result set (or all results). Paginate creates the SQL used to limit results automatically so you can edit your query to take advantage of this. For example, if your query before pagination was SELECT id, name, address FROM table ORDER BY id ASC you would change it to be SELECT id, name, address FROM table ORDER BY id ASC $pages->limitWhen a user selects the ‘All’ option, they effectively set $pages->limit to nothing and any page selected automatically creates the appropriate limit.
   $pages->limit
9. Styles. The pagination class has been created so that it can be styles with CSS easily. The recommended CSS is<style type="text/css">
.paginate {
font-family: Arial, Helvetica, sans-serif;
font-size: .7em;
}
a.paginate {
border: 1px solid #000080;
padding: 2px 6px 2px 6px;
text-decoration: none;
color: #000080;
}
a.paginate:hover {
background-color: #000080;
color: #FFF;
text-decoration: underline;
}
a.current {
border: 1px solid #000080;
font: bold .7em Arial,Helvetica,sans-serif;
padding: 2px 6px 2px 6px;
cursor: default;
background:#000080;
color: #FFF;
text-decoration: none;
}
span.inactive {
border: 1px solid #999;
font-family: Arial, Helvetica, sans-serif;
font-size: .7em;
padding: 2px 6px 2px 6px;
color: #999;
cursor: default;
}
</style>

10. Basic example:<!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.0 Transitional//EN”
“http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd”>
<html xmlns=”http://www.w3.org/1999/xhtml”>
<head>
<meta http-equiv=”Content-Type” content=”text/html; charset=iso-8859-1? />
<title>Paginator</title>
<style type=”text/css”>
.paginate {
font-family: Arial, Helvetica, sans-serif;
font-size: .7em;
}
a.paginate {
border: 1px solid #000080;
padding: 2px 6px 2px 6px;
text-decoration: none;
color: #000080;
}
a.paginate:hover {
background-color: #000080;
color: #FFF;
text-decoration: underline;
}
a.current {
border: 1px solid #000080;
font: bold .7em Arial,Helvetica,sans-serif;
padding: 2px 6px 2px 6px;
cursor: default;
background:#000080;
color: #FFF;
text-decoration: none;
}
span.inactive {
border: 1px solid #999;
font-family: Arial, Helvetica, sans-serif;
font-size: .7em;
padding: 2px 6px 2px 6px;
color: #999;
cursor: default;
}
</style>
</head>
<body>
<?php
require_once ‘paginator.class.php’;
// Make your database connection here and retrieve your total number of
items (i.e. SELECT COUNT(*) FROM…)
$pages = new Paginator;
$pages->items_total = $db_count;
$pages->mid_range = 7;
$pages->paginate();echo $pages->display_pages();
// Make your db query here. Include $pages->limit as described in step 8.
(i.e. SELECT id,fname,lname FROM employees $pages->limit)
echo $pages->display_pages(); // Optional call which will display the page numbers after the results.
echo $pages->display_jump_menu(); // Optional – displays the page jump menu
echo $pages->display_items_per_page(); //Optional – displays the items per
page menu
?>
</body>
</html>

All in all you could add pagination to any database driven set of results with about five lines of code. To display the current page number in the format ‘Page X of Y’ where X is the current page and Y is the total number of pages, use the code:

echo "<p class=\"paginate\">Page: $pages->current_page of $pages->num_pages</p>\n";

To display the SQL that was generated, use the code:

echo "<p class=\"paginate\">SELECT * FROM table $pages->limit (retrieve
records $pages->low-$pages->high from table - $pages->items_total item total / $pages->items_per_page
items per page)";

if (empty($_POST['action']))
{
$action = 'default';
}
else
{
$action = $_POST['action'];
}

All we’re doing here is assigning one value to $action if the form variable action isn’t empty, and different variable if it is. This took up eight lines of code (OK, so you could argue that you could lower that by moving braces around but the code gets ugly fast). How can we clean this up? Enter ternary operators!
What’s a ternary operator you ask? In a nutshell, a ternary operator takes three elements and combines them into one. The basic syntax is (expression 1) ? (expression 2) : (expression 3); which means do expression 2 if expression 1 is true, otherwise do expression 3. It’s just an if/else condition rewritten in one simple line. Taking our previous example, we could consolidate it to this:

$action = (empty($_POST['action'])) ? 'default':$_POST['action'];

Voila! The exact same results in one easy to understand line. I am a huge fan of this shortcut and it comes in very handy when you have basic if/else conditions to check.