This package adds the paginate route method to support pagination via custom routes instead of query strings. This also allows for easily translatable pagination routes ex. /news/page/2, /nieuws/pagina/2.
Spatie is a webdesign agency in Antwerp, Belgium. You'll find an overview of all our open source projects on our website.
Note: If you're upgrading to 2.0, check out the upgrade guide below.
You're free to use this package (it's MIT-licensed), but if it makes it to your production environment you are required to send us a postcard from your hometown, mentioning which of our package(s) you are using.
Our address is: Spatie, Samberstraat 69D, 2060 Antwerp, Belgium.
The best postcards will get published on the open source page on our website.
Via Composer
$ composer require spatie/laravel-paginaterouteFirst register the service provider and facade in your application.
// config/app.php
'providers' => [
...
'Spatie\PaginateRoute\PaginateRouteServiceProvider',
];
'aliases' => [
...
'PaginateRoute' => 'Spatie\PaginateRoute\PaginateRouteFacade',
];Then register the macros in App\Providers\RouteServiceProvider::boot().
// app/Providers/RouteServiceProvider.php
use PaginateRoute;
// ...
public function boot(Router $router)
{
PaginateRoute::registerMacros();
parent::boot($router);
}The paginate route macro will register two routes for you.
// app/Http/routes.php
// Generates /users & /users/page/{page}
Route::paginate('users', 'UsersController@index');In your route's action you can just use Laravel's regular pagination methods.
// app/Http/Controllers/UsersController.php
public function index()
{
return view('users.index', ['users' => \App\User::simplePaginate(5)]);
}If you want to customize or add translations for the "page" url segment, you can publish the language files.
$ php artisan vendor:publish --provider="Spatie\PaginateRoute\PaginateRouteServiceProvider"Since Laravel's paginator url's will still use a query string, PaginateRoute has it's own url generator and page helper functions.
{{-- $users is an instance of \Illuminate\Contracts\Pagination\Paginator --}}
@if(PaginateRoute::hasPreviousPage())
<a href="{{ PaginateRoute::previousPageUrl() }}">Previous</a>
@endif
@if(PaginateRoute::hasNextPage($users))
<a href="{{ PaginateRoute::nextPageUrl($users) }}">Next</a>
@endif
The nextPage functions require the paginator instance as a parameter, so they can determine whether there are any more records.
/**
* @param \Illuminate\Contracts\Pagination\Paginator $paginator
* @return int|null
*/
public function nextPage(Paginator $paginator)/**
* @param \Illuminate\Contracts\Pagination\Paginator $paginator
* @return bool
*/
public function hasNextPage(Paginator $paginator)/**
* @param \Illuminate\Contracts\Pagination\Paginator $paginator
* @return string|null
*/
public function nextPageUrl(Paginator $paginator)/**
* @return int|null
*/
public function previousPage()/**
* @return bool
*/
public function hasPreviousPage()/**
* @param bool $full
* @return string|null
*/
public function previousPageUrl($full = false)/**
* @param int $page
* @param bool $full
* @return string
*/
public function pageUrl($page, $full = false)If $full is true, the first page will be a fully qualified url. Ex. /users/page/1 instead if just /users (this is the default).
To retrieve the url of a specific page of a paginated route, that isn't the current route, there's the addPageQuery function.
/**
* @param string $url
* @param int $page
* @param bool $full
* @return string
*/
public function addPageQuery($url, $page, $full = false)You can also retrieve an array with all available urls. These can be rendered as a plain html list with page numbers. Note that these functions require a LengthAwarePaginator.
/**
* @param \Illuminate\Contracts\Pagination\LengthAwarePaginator $paginator
* @param bool $full
* @return array
*/
public function allUrls(LengthAwarePaginator $paginator, $full = false)/**
* @param \Illuminate\Contracts\Pagination\LengthAwarePaginator $paginator
* @param bool $full
* @param string $class
* @param bool $additionalLinks
* @return string
*/
public function renderPageList(LengthAwarePaginator $paginator, $full = false, $class = null, $additionalLinks = false)<!-- Example output: -->
<ul class="pagination">
<li><a href="http://example.com/news">1</a></li>
<li><a href="http://example.com/news/page/2">2</a></li>
<li class="active"><a href="http://example.com/news/page/3">3</a></li>
<li><a href="http://example.com/news/page/4">4</a></li>
<li><a href="http://example.com/news/page/4">»</a></li>
</ul>You can render link tags to mark previous and next page for SEO. Note that these functions require a LengthAwarePaginator.
/**
* @param \Illuminate\Contracts\Pagination\LengthAwarePaginator $paginator
* @param bool $full
* @return string
*/
public function renderRelLinks(LengthAwarePaginator $paginator, $full = false)<!-- Example output: -->
<link rel="prev" href="http://example.com/news/page/2" />
<link rel="next" href="http://example.com/news/page/4" />The package contains some integration/smoke tests, set up with Orchestra. The tests can be run via phpunit.
$ phpunit
The 2.0 release changes the route macro to only register one route with the entire query in it, so providing a page parameter to the action link is no longer possible.
For example, action('FooController@bar', ['page' => 3]) is no longer possible, and should be replaced by PaginateRoute::addPageQuery(action('FooController@bar'), 3).
Please see CHANGELOG for more information what has changed recently.
Please see CONTRIBUTING for details.
If you discover any security related issues, please email freek@spatie.be instead of using the issue tracker.
Spatie is a webdesign agency in Antwerp, Belgium. You'll find an overview of all our open source projects on our website.
The MIT License (MIT). Please see License File for more information.