GitHub Project: PHP-Pagination

And here we are in the series on my GitHub Projects, with PHP-Pagination.

What is this?

Oh, pagination.
This library provides a clean, decoupled "API" for developers to integrate pagination markup into their site or application.

It provides simple methods to control the settings for the generated pagination markup, including the number of items per page, the total number of items and more.

Why did I develop it?

Well, that's a good question. There are plenty of pagination scripts out there, but they all felt increasingly complicated for what I was trying to do. I wanted a library that decoupled it's processing logic from the view that would be rendered for the pagination markup.

One where you could define an instance of the Pagination class, define it's properties programmatically, and have the rendered markup use the object to generate clean, semantic, valid markup.

What's included?

This library contains two files:

• Pagination Instantiable class for pagination objects/settings
• render.inc.php View which generates the pagination markup

The relevant public methods for a Pagination instance are:

• parse Returns a string of the generated pagination markup
• setCrumbs Sets the pagination to exclude page numbers, and only output preview/next markup. The counter-method of this is the setFull method
• setCurrent Sets the maximum number of 'crumbs' (eg. numerical page items) that are shown
• setCrumbs Sets the current page being viewed
• setFull Sets the pagination to include numbers (counter-method of setCrumbs)
• setKey Sets the key of the _GET array that contains, and ought to contain, paging information (eg. which page is being viewed)
• setNext Sets the copy of the next anchor
• setPrevious Sets the copy of the previous anchor
• setRPP Sets the number of records per page (used for determining total number of pages)
• setTarget Sets the leading path for anchors
• setTotal Sets the total number of records available for pagination

How do I use it?

Using the Pagination library requires only a few lines of PHP, which will take you to a point whereby you have a variable that contains valid markup for your pagination list items/links.

This markup will not, however, be styled.. at all. For this, you'll have to use the provided light.css stylesheet. Moving it over to your webroot/static folder and including it should do the trick.

Hopefully over time, I'll be able to add some more themes :)

Why did I abstract it out?

I'm starting to question the efficacy and information that this section can offer. Anyway.

I abstracted this library out in the way that I did, because I wanted the application and view logic to be independent of one another.

I've seen pagination libraries before where a PHP class will generate markup inside of a massively-escaped method/function. I found this to be pretty inefficient, and made reading the view logic really difficult. Not to mention how difficult it was to make changes to the markup that would be generated.

This is a library that can be used independently from any framework.

Yup. Next up, PHP-MySQL.

Update (11.October.2012)

I've updated the library in order for it to be compatible with Twitter Bootstrap. I've made the following changes:

• Changed the current class to active
• Moved this class from the anchor level to the list-item level
• Moved the disabled class from the anchor level to the list-item level
• Added two methods in PHP (addClasses and setClasses) to allow you to specify UI-classes for the top-level pagination div (eg. adding the pagination-centered class)

See http://twitter.github.com/bootstrap/components.html#pagination for more.