Laravel: Overwriting the Default Pagination System

by Ivica Jangelovski

5 min read · May 5, 2020

As you may already know, Laravel is the most-widely used framework in the PHP developers community. It comes with many out-of-the-box features that allow every Laravel developer to accomplish rapid application development process.

Some of the best features include:

  • Security and Authentication Implementation
  • Validation of the HTTP Requests
  • Database Migration System
  • CLI with Artisan
  • Templating Engine (Blade)
  • Pagination
  • and more

Another thing that makes Laravel so attractive is the flexibility it provides for the developers.

Almost all the features are highly customizable and can be adjusted to fit your needs in different scenarios as per your requirements.

In this post, we'll explore pagination with Laravel. Personally, I believe it's one of the best Laravel features that comes right out of the box and that you can use with just a few lines of code.

Read on to learn how you can implement pagination on your records and pick up a few tips for customization.

Types of Pagination

There are two types of pagination methods that are currently supported by default for the Query Builder results and the Eloquent ORM queries. They include:

  • simplePaginate()
  • paginate()

The difference between these two is that the first one displays only the Prev and Next buttons for navigating through the results, while the second one also includes the page numbers in between.

If you want to manually create a pagination system for other types of results apart from the Query Builder and the Eloquent ORM, checkout this Laravel Manual Paginatior example.

Controller Example Method

<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
use Illuminate\Support\Facades\DB;
use App\Invoice;

class InvoicesController extends Controller
{
    public function index()
    {
        //We will place the results fetch in this method
    }
}

Assuming you have created a view index directory for the Invoices in views/invoices we'll fetch the results in the index method and send them to the blade view.

Paginating Query Builder Results

Using the paginate() method:

public function index()
{
    $invoices = DB::table('invoices')->paginate(10);
    
    return view('invoices.index', ['invoices' => $invoices]);
}

Using the simplePaginate() method:

public function index()
{
    $invoices = DB::table('invoices')->simplePaginate(10);
    
    return view('invoices.index', ['invoices' => $invoices]);
}

Paginating Eloquent Results

Using the paginate() method:

$invoices = App\Invoice::paginate(10);

Using the simplePaginate() method:

$invoices = App\Invoice::simplePaginate(10);

Important thing to note is that the paginate() and simplePaginate() methods should be called after all the operations and constraints you made over the query.

How to Render the Pagination Results in the View

Only 1 line of code is necessary to be written in the view by default. So, in order to display the HTML that's generated from the paginating methods you should write:

{{ $invoices->links() }}

You may wrap this in nested HTML or place it wherever you want in your Blade view. If you used the paginate() method, you'll notice that the pagination is rendered with links (or numbers + navigation buttons combo.

Customizing the Pagination HTML

The default Laravel installation is shipped with BootstrapCSS as a primary CSS framework.

For this reason, the generated HTML for the pagination is Bootstrap compatible (as already noted in the docs).

However, not everyone wants to utilize this default behavior and Bootstrap generated HTML.

Some of you may want to use your custom HTML/CSS or any other CSS framework (like TaliwindCSS).

This is why the Laravel core provides a convenient way to reuse some of the existing HTML views for the pagination by getting them into your views folder and make changes over them.

The path for the pagination view in the Laravel core is the following:

/vendor/laravel/framework/src/Illuminate/Pagination/resources/views

As it's not recommended to make changes in the Laravel core code, you will need to "grab" this folder and copy it to your resources/views/vendor folder by running:

php artisan vendor:publish --tag=laravel-pagination

This command will automatically create the folder /resources/views/vendor/pagination.

If you open it, you'll notice a few blade files. We need the file named resources/views/vendor/pagination/bootstrap-4.blade.php because this is the one used by the paginate() method.

If you want to customize the simple Paginate() method output you'll have to do it in the resources/views/vendor/pagination/simple-bootstrap-4.blade.php.

Now, whatever you change here will reflect in your original view and you are free to customize it according to your needs.

Bonus Tip(s)

Maybe you want to get rid of the files that are generated by default. Or, perhaps you want to assign another file to be responsible for your default pagination view.

All of this is possible, but you will need to inform the AppServiceProvider for this action by calling the new pagination views in the boot() method:

use Illuminate\Pagination\Paginator;

public function boot()
{
    Paginator::defaultView('your-pagination-view-name');

    Paginator::defaultSimpleView('your-pagination-view-name');
}

This will make your-pagination-view-name and your-pagination-view-name your default pagination views for paginate() and simplePaginate().

Another thing you might want to know is that the Paginator class has numerous methods that are used to manipulate your pagination.

You can check them all on the Laravel docs page for the Pagination. Try to make tweaks on the example from above to see how all of these methods are working.

Good luck!

Additional Reading: Using Corcel in Laravel to CRUD Wordpress Data