📖 Pagination

Pagination in version 3 is illuminate/pagination. There is no PageBlocks Paginator class any more — paginate() returns a standard Illuminate\Pagination\LengthAwarePaginator.

Most of the time you want pbList

pbList already wires up a paginated list, including the AJAX part, without a controller. Reach for the paginator directly only when you are writing a controller of your own.

Paginating a query

Works the same on the query builder and on a model:

$paginator = query('site_content')
    ->where('template', 5)
    ->whereNotNull('publishedon')
    ->orderByDesc('publishedon')
    ->paginate(5);

$paginator = model('PbResource')->published()->paginate(10);

The current page is taken from the page query parameter.

What the paginator gives you

$paginator->items();        // array of rows on this page
$paginator->total();        // 92  - rows in total
$paginator->currentPage();  // 1
$paginator->lastPage();     // 19
$paginator->perPage();
$paginator->hasPages();
$paginator->links();        // rendered navigation

links() returns ready HTML with Bootstrap classes; its captions come from the lexicon, so they follow the manager language.

Keeping the query string

By default the page links carry only ?page=N and drop everything else — filters included. withQueryString() keeps the rest:

$paginator = query('site_content')->paginate(10)->withQueryString();

This is a common source of "the filter resets when I go to page 2".

In a template

{foreach $paginator->items() as $item}
    <article>
        <a href="{$item->uri}">{$item->pagetitle}</a>
    </article>
{/foreach}

<nav>{$paginator->links()}</nav>

A controller example

class NewsController
{
    public function index()
    {
        $paginator = query('site_content')
            ->where('template', 5)
            ->orderByDesc('publishedon')
            ->paginate(5)
            ->withQueryString();

        return view('file:templates/news', [
            'paginator' => $paginator,
        ]);
    }
}

AJAX

The paginator itself renders plain links. If you want page changes without a reload, either use pbList — it stores the query server-side under an opaque key and swaps the rows over AJAX — or drive the links yourself with pbPagination.