The benefit of using any full-stack web application framework is that you don't have to worry about the common tasks like input handling, form validation and the like, as the framework already provides wrappers for those features. Thus, it allows you to concentrate on the business logic of the application rather than reinventing the wheel over and over again.

Today, we're going to explore an important library in the CodeIgniter framework—the pagination library.

Let me highlight the topics that we're going to cover in the course of this article:

• Demonstration of basic paging
  
• Explore the customization options
• Pagination configuration

Demonstration of Basic Paging

In this section, we'll go through an example that demonstrates the use of pagination in CodeIgniter. It's the best way to understand how things work altogether.

In our example, we'll build a pretty simple user listing in which we'll fetch records from the users MySQL table. In order to successfully run this example, make sure that you have the uid and uname fields in your users table.

With that set up, we're ready to roll.

Go ahead and create a controller file controllers/Paging.php with the following contents.

<?php
defined('BASEPATH') OR exit('No direct script access allowed');

class Paging extends CI_Controller {
    public function __construct()
	{
		parent::__construct();

		// load Pagination library
		$this->load->library('pagination');

		// load URL helper
		$this->load->helper('url');
	}

	public function index()
	{
		// load db and model
		$this->load->database();
		$this->load->model('Users');

		// init params
		$params = array();
		$limit_per_page = 1;
		$start_index = ($this->uri->segment(3)) ? $this->uri->segment(3) : 0;
		$total_records = $this->Users->get_total();

		if ($total_records > 0)
		{
			// get current page records
			$params["results"] = $this->Users->get_current_page_records($limit_per_page, $start_index);

			$config['base_url'] = base_url() . 'paging/index';
			$config['total_rows'] = $total_records;
			$config['per_page'] = $limit_per_page;
			$config["uri_segment"] = 3;

			$this->pagination->initialize($config);

			// build paging links
			$params["links"] = $this->pagination->create_links();
		}

		$this->load->view('user_listing', $params);
	}

	public function custom()
	{
		// load db and model
		$this->load->database();
		$this->load->model('Users');

		// init params
		$params = array();
		$limit_per_page = 2;
		$page = ($this->uri->segment(3)) ? ($this->uri->segment(3) - 1) : 0;
		$total_records = $this->Users->get_total();

		if ($total_records > 0)
		{
			// get current page records
			$params["results"] = $this->Users->get_current_page_records($limit_per_page, $page*$limit_per_page);

			$config['base_url'] = base_url() . 'paging/custom';
			$config['total_rows'] = $total_records;
			$config['per_page'] = $limit_per_page;
			$config["uri_segment"] = 3;

			// custom paging configuration
			$config['num_links'] = 2;
			$config['use_page_numbers'] = TRUE;
			$config['reuse_query_string'] = TRUE;

			$config['full_tag_open'] = '<div class="pagination">';
			$config['full_tag_close'] = '</div>';

			$config['first_link'] = 'First Page';
			$config['first_tag_open'] = '<span class="firstlink">';
			$config['first_tag_close'] = '</span>';

			$config['last_link'] = 'Last Page';
			$config['last_tag_open'] = '<span class="lastlink">';
			$config['last_tag_close'] = '</span>';

			$config['next_link'] = 'Next Page';
			$config['next_tag_open'] = '<span class="nextlink">';
			$config['next_tag_close'] = '</span>';

			$config['prev_link'] = 'Prev Page';
			$config['prev_tag_open'] = '<span class="prevlink">';
			$config['prev_tag_close'] = '</span>';

			$config['cur_tag_open'] = '<span class="curlink">';
			$config['cur_tag_close'] = '</span>';

			$config['num_tag_open'] = '<span class="numlink">';
			$config['num_tag_close'] = '</span>';

			$this->pagination->initialize($config);

			// build paging links
			$params["links"] = $this->pagination->create_links();
		}

		$this->load->view('user_listing', $params);
	}
}

Next, we'll need a model file models/Users.php that fetches records from the users table.

<?php
// models/Users.php
defined('BASEPATH') OR exit('No direct script access allowed');

class Users extends CI_Model
{
    function __construct()
	{
	  parent::__construct();
	}

	public function get_current_page_records($limit, $start)
	{
		$this->db->limit($limit, $start);
		$query = $this->db->get("users");

		if ($query->num_rows() > 0)
		{
			foreach ($query->result() as $row)
			{
				$data[] = $row;
			}

			return $data;
		}

		return false;
	}

	public function get_total()
	{
		return $this->db->count_all("users");
	}
}

Finally, let's create a view file at views/user_listing.php that displays the user listing.

<!-- views/user_listing.php -->
<html>
    <head>
		<title>Paging Example-User Listing</title>
	</head>

	<body>
		<div class="container">
			<h1 id='form_head'>User Listing</h1>

			<?php if (isset($results)) { ?>
				<table border="1" cellpadding="0" cellspacing="0">
					<tr>
						<th>ID</th>
						<th>NAME</th>
					</tr>

					<?php foreach ($results as $data) { ?>
						<tr>
							<td><?php echo $data->uid ?></td>
							<td><?php echo $data->uname ?></td>
						</tr>
					<?php } ?>
				</table>
			<?php } else { ?>
				<div>No user(s) found.</div>
			<?php } ?>

			<?php if (isset($links)) { ?>
				<?php echo $links ?>
			<?php } ?>
		</div>
	</body>
</html>

Now, go ahead and access our custom page at http://your-code-igniter-site/paging/index and you should see the user listing along with the pagination! So, that's it, we've done it! Don't worry, I won't leave you that soon, as we'll start dissecting each part of the code now.

We'll start with the model file models/Users.php as that's something will be called from our controller methods. There are two important methods, get_current_page_records and get_total, that our model implements in order to build the pagination links.

Let's go through the get_total method. It's used to count the number of records in the users table.

public function get_total()
{
    return $this->db->count_all("users");
}

Next, there's a get_current_page_records method.

public function get_current_page_records($limit, $start)
{
    $this->db->limit($limit, $start);
    $query = $this->db->get("users");

    if ($query->num_rows() > 0)
    {
        foreach ($query->result() as $row)
        {
            $data[] = $row;
        }

        return $data;
    }

    return false;
}

There are two important arguments that you should note in the get_current_page_records method. The first argument, $limit, is used to specify the number of records that will be returned during the query run. And the second argument, $start, acts as the starting index of the record.

So, as you can see, given the values of $start and $limit we can fetch records by page. That's the essence of paging, and meanwhile we've implemented the most important method of this article!

So, that was our model—simple and elegant!

Moving ahead, let's switch our attention to the controller file. Go ahead and grab the code of the constructor method.

public function __construct()
{
    parent::__construct();

    // load Pagination library
    $this->load->library('pagination');

    // load URL helper
    $this->load->helper('url');
}

In order to use pagination in CodeIgniter, the first thing you need to do is to load the pagination library. And we can do it by using $this->load->library('pagination').

We've also loaded the URL helper so that we can use global helper functions provided by that helper.

Now, we're ready to go through the heart of our controller—the index method.

public function index()
{
		// load db and model
		$this->load->database();
		$this->load->model('Users');

		// init params
		$params = array();
		$limit_per_page = 1;
		$start_index = ($this->uri->segment(3)) ? $this->uri->segment(3) : 0;
		$total_records = $this->Users->get_total();

		if ($total_records > 0)
		{
			// get current page records
			$params["results"] = $this->Users->get_current_page_records($limit_per_page, $start_index);

			$config['base_url'] = base_url() . 'paging/index';
			$config['total_rows'] = $total_records;
			$config['per_page'] = $limit_per_page;
			$config["uri_segment"] = 3;

			$this->pagination->initialize($config);

			// build paging links
			$params["links"] = $this->pagination->create_links();
		}

		$this->load->view('user_listing', $params);
	}

To start with, we make sure that the database is loaded properly. Following that, we load the Users model so that we can use the model methods.

$this->load->database();
$this->load->model('Users');

Next, we initialize a couple of important variables.

// init params
$params = array();
$limit_per_page = 1;
$start_index = ($this->uri->segment(3)) ? $this->uri->segment(3) : 0;
$total_records = $this->Users->get_total();

The variable $limit_per_page defines the limit per page. Of course, you could set it as you wish; it's set to 1 at the moment for example purposes.

The $start_index variable holds the starting index of the MySQL record. When CodeIgniter builds the pagination links, it appends the starting index of the page as the third segment in the URL by default. You can change this default behavior, but that's something we'll reserve for the last section of this article, where we'll discuss customization options.

Finally, we call the get_total method of the Users model to get the total records of the users table, and it's assigned to the $total_records variable.

Next, we fetch the records of the current page using the get_current_page_records method.

// get current page records
$params["results"] = $this->Users->get_current_page_records($limit_per_page, $start_index);

Before we can actually go ahead and build pagination links, we need to initialize the minimal paging configuration using the initialize method of the paging library.

$config['base_url'] = base_url() . 'paging/index';
$config['total_rows'] = $total_records;
$config['per_page'] = $limit_per_page;
$config["uri_segment"] = 3;

$this->pagination->initialize($config);

And that's the set of minimum parameters to build the pagination links.

• base_url: The URL that will be used while building pagination links
• total_rows: Total number of records
• per_page: Record count per page

Finally, we use the create_links method to build pagination links.

// build paging links
$params["links"] = $this->pagination->create_links();

The rest is just the formality to call our view user_listing and render the output! Run the URL http://your-code-igniter-site/paging/index to see the user listing along with the pagination links.

So that's a very simple yet useful pagination example at your disposal that you could extend to fit your requirements.

In the next section, we'll explore how you could customize the default pagination in terms of appearance and functionality.

Explore Customization Options

In this section, we'll explore the options available that you could use should you wish to customize the default pagination links.

URI Segment

Although the CodeIgniter paging library automatically detects the paging-related parameter from the URL, you could define a custom value if you have different URL pattern.

$config["uri_segment"] = 4;

Number of Digit Links

The num_links option allows you to define the number of digit links that will be displayed before and after the active page number in the pagination links.

$config['num_links'] = 2;

Page Number as URI Segment

When you access the paging URI segment, it's a starting index by default. For example, if you have ten records per page, the paging URI segment is 20 for the third page. Instead, if you want to show actual page numbers in the paging links, you can set use_page_numbers to TRUE.

$config['use_page_numbers'] = TRUE;

Of course, you need to make sure that you calculate the proper starting index based on the page number you retrieve from the URL.

Preserve Query String

More often than not, you end up in the situation where you want to preserve query string parameters that are not related to pagination. You can use the reuse_query_string option to enable that facility.

$config['reuse_query_string'] = TRUE;

These were a few options that you could use to alter the default pagination functionality. Next, we'll look at a couple of other options that allow you to alter the way pagination links are displayed.

Wrapper Tag

If you want to wrap the pagination code with any other HTML tag then you could do it using the full_tag_open and full_tag_close options.

$config['full_tag_open'] = '<div class="pagination">';
$config['full_tag_close'] = '</div>';

It could be really useful should you wish to apply custom styling to the pagination links.

First, Last, Next, and Previous

If you want to change the text that will be displayed for the first, last, next and previous links, you could do that as well.

$config['first_link'] = 'First Page';
$config['last_link'] = 'Last Page';
$config['next_link'] = 'Next Page';
$config['prev_link'] = 'Prev Page';

Also, if you want to wrap those individual links with any HTML tag, you could do that in the same way as we did it to wrap the whole paging code.

$config['first_tag_open'] = '<span class="firstlink">';
$config['first_tag_close'] = '</span>';

$config['last_tag_open'] = '<span class="lastlink">';
$config['last_tag_close'] = '</span>';

$config['next_tag_open'] = '<span class="nextlink">';
$config['next_tag_close'] = '</span>';

$config['prev_tag_open'] = '<span class="prevlink">';
$config['prev_tag_close'] = '</span>';

Active Link and Number Link

Sometimes, you want to style the active link differently. You could do that by applying wrapper tags as shown below.

$config['cur_tag_open'] = '<span class="curlink">';
$config['cur_tag_close'] = '</span>';

In the same way, if you want to wrap digit links with something:

$config['num_tag_open'] = '<span class="numlink">';
$config['num_tag_close'] = '</span>';

And that ends the story of customization. In fact, you could go ahead and look at the customization example at http://your-code-igniter-site/paging/custom that's already included in our controller file!

Paging Configuration

Now you're aware of the configuration that's required to set up a decent pagination with any model listing. And most of the time, you want to keep it the same throughout the site. What are you going to do to achieve that? You might be tempted to copy the configuration code and paste it into each action that requires the pagination configuration.

In fact, there's a better way you could handle this scenario. You can create a paging configuration file at application/config/pagination.php and use the $config variable to define your settings.

<?php
$config['per_page'] = 10;
$config["uri_segment"] = 3;

$config['full_tag_open'] = '<div class="pagination">';
$config['full_tag_close'] = '</div>';

$config['first_link'] = 'First Page';
$config['first_tag_open'] = '<span class="firstlink">';
$config['first_tag_close'] = '</span>';

$config['last_link'] = 'Last Page';
$config['last_tag_open'] = '<span class="lastlink">';
$config['last_tag_close'] = '</span>';

$config['next_link'] = 'Next Page';
$config['next_tag_open'] = '<span class="nextlink">';
$config['next_tag_close'] = '</span>';

$config['prev_link'] = 'Prev Page';
$config['prev_tag_open'] = '<span class="prevlink">';
$config['prev_tag_close'] = '</span>';

$config['cur_tag_open'] = '<span class="curlink">';
$config['cur_tag_close'] = '</span>';

$config['num_tag_open'] = '<span class="numlink">';
$config['num_tag_close'] = '</span>';

Based on that, the revised index action method should look like this:

public function index()
{
    // load db and model
    $this->load->database();
    $this->load->model('Users');

    // init params
    $params = array();
    $start_index = ($this->uri->segment(3)) ? $this->uri->segment(3) : 0;
    $total_records = $this->Users->get_total();

    // load config file
    $this->config->load('pagination', TRUE);
    $settings = $this->config->item('pagination');
    $settings['total_rows'] = $this->Users->get_total();
    $settings['base_url'] = base_url() . 'paging/config';

    if ($total_records > 0)
    {
        // get current page records
        $params["results"] = $this->Users->get_current_page_records($settings['per_page'], $start_index);

        // use the settings to initialize the library
        $this->pagination->initialize($settings);

        // build paging links
        $params["links"] = $this->pagination->create_links();
    }

    $this->load->view('user_listing', $params);
}

Of course, the total_rows and base_url variables change from action to action, so you need to set them explicitly in every action.

To accomplish that, you need to load the pagination configuration in the first place.

$this->config->load('pagination', TRUE);
$settings = $this->config->item('pagination');

Next, you can override the action specific settings.

$settings['total_rows'] = $this->Users->get_total();
$settings['base_url'] = base_url() . 'paging/config';

And you're done with that!

So that was the story of the pagination configuration, and that ends this article as well!

Conclusion

Today, we went through the pagination library in CodeIgniter.

In the first part of this article, I demonstrated how you can use the pagination library by providing a very simple yet useful example.

Following that, we discussed the customization options that are available at your disposal while setting up the pagination.

Finally, we discussed the pagination configuration in the last section.

CodeIgniter is a powerful PHP platform. Whether you're just getting started or you're starting with the next version, don't forget to check out what we have available for you, as well.

I would love to know your feedback in the form of queries and comments using the feed below!