Paginator

The paginator is a special sort of a collection. Paginator allows you to easily retrieve paginated results from the database and works together with query builder. Paginator uses the collection class for storing items. It also provides a predictable data structure of paginated entries which can be easily reused across different services.

It implements the Iterator interface and therefore you can loop over the items in the paginator with foreach.

The paginate() function of the query builder returns a paginator instance but you can also use the paginator standalone, passing a builder instance to it.

The builder supports two modes:

  • Simple
  • Full

Simple

The simple mode does not need to count anything it will just work with a page number and the number of items per page.

This is useful if, for example, you want to implement a "load more" button to load the next set of results without the need to know how many pages there are.

$page = 1; 
$per_page = 10;

// the builder can return a simple paginator
$paginator = builder::table('user')
   ->load_more($page, $per_page);


// Or the paginator can be used standalone
$query = builder::table('user')
   ->where('deleted', 1);

$paginator = new paginator($query, $page, $per_page, true);

print_r($paginator->to_array());

/* prints:

Array
(
    [items] => Array
        (
            [0] => Array
                (
                    ...
                )

            [1] => Array
                (
                    ...
                )
            ...
        )

    [page] => 1
    [items_per_page] => 10
)

*/

Full

This mode support full pagination, including next and previous, number of pages and total number of items.

$page = 1; 
$per_page = 10;

// the builder can return a paginator 
$paginator = builder::table('user')
    ->paginate($page, $per_page);

// Or the paginator can be used standalone 
$query = builder::table('user')
   ->where('deleted', 1);

$paginator = new paginator($query, $page, $per_page);

print_r($paginator->to_array());

/* prints:

Array
(
    [items] => Array
        (
            [0] => Array
                (
                    ...
                )

            [1] => Array
                (
                    ...
                )
            ...
        )

    [page] => 1
    [pages] => 3
    [items_per_page] => 10
    [next] => 2
    [prev] => null
    [total] => 23
)

*/

Functions

FunctionPurposeNotes

get_items()

Returns the items as a collection-

to_array()

Converts the items to arrays (cast to array or call to_array() on items if possible) and returns them along with metadata about the paging.See examples above.

get_page()

Returns the current page.-

get_pages()

Returns the total amount of pages. Only available in full mode.

get_items_per_page()

Returns the number of items per page.-

get_prev()

Returns the next page number. Returns null if the current page is the last page. Only available in full mode.

get_next()

Returns the previous page number. Returns null if the current page is the first page.Only available in full mode.

get_total()

Returns the total number of items. Only available in full mode.