hungnm144/laravel-paginateroute

Laravel outer extension to easily use laravel's paginator without the query string

Laravel Paginate Route

, _(*1)

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., _(*2)

Spatie is a webdesign agency in Antwerp, Belgium. You'll find an overview of all our open source projects on our website., _(*3)

Note: If you're upgrading to 2.0, check out the upgrade guide below., _(*4)

Postcardware

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., _(*5)

Our address is: Spatie, Samberstraat 69D, 2060 Antwerp, Belgium., _(*6)

The best postcards will get published on the open source page on our website., _(*7)

Install

Via Composer, _(*8)

``` bash $ composer require hungnm144/laravel-paginateroute, <sub>(*9)</sub>

First register the service provider and facade in your application.

```php
// config/app.php

'providers' => [
    ...
    'Spatie\PaginateRoute\PaginateRouteServiceProvider',
];

'aliases' => [
    ...
    'PaginateRoute' => 'Spatie\PaginateRoute\PaginateRouteFacade',
];

Then register the macros in App\Providers\RouteServiceProvider::boot()., <sub>(*10)</sub>

// app/Providers/RouteServiceProvider.php

use PaginateRoute;

// ...

public function boot()
{
    PaginateRoute::registerMacros();

    parent::boot();
}

Usage

The paginate route macro will register two routes for you., <sub>(*11)</sub>

// 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., <sub>(*12)</sub>

// 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., <sub>(*13)</sub>

``` bash $ php artisan vendor:publish --provider="Spatie\PaginateRoute\PaginateRouteServiceProvider", <sub>(*14)</sub>

### Generating Url's

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 --}}, <sub>(*15)</sub>

@if(PaginateRoute::hasPreviousPage()) Previous @endif, <sub>(*16)</sub>

@if(PaginateRoute::hasNextPage($users)) Next @endif, <sub>(*17)</sub>

The `nextPage` functions require the paginator instance as a parameter, so they can determine whether there are any more records.

```php
/**
 * @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)., <sub>(*18)</sub>

To retrieve the url of a specific page of a paginated route, that isn't the current route, there's the addPageQuery function., <sub>(*19)</sub>

/**
 * @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., <sub>(*20)</sub>

/**
 * @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">&raquo;</a></li>
</ul>

You can render link tags to mark previous and next page for SEO. Note that these functions require a LengthAwarePaginator., <sub>(*21)</sub>

/**
 * @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" />

Tests

The package contains some integration/smoke tests, set up with Orchestra. The tests can be run via phpunit., <sub>(*22)</sub>

$ phpunit

Upgrading

1.x => 2.0

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., <sub>(*23)</sub>

For example, action('FooController@bar', ['page' => 3]) is no longer possible, and should be replaced by PaginateRoute::addPageQuery(action('FooController@bar'), 3)., <sub>(*24)</sub>

Changelog

Please see CHANGELOG for more information what has changed recently., <sub>(*25)</sub>

Contributing

Please see CONTRIBUTING for details., <sub>(*26)</sub>

Security

If you discover any security related issues, please email freek@spatie.be instead of using the issue tracker., <sub>(*27)</sub>

Credits

• Sebastian De Deyne
• All Contributors

About Spatie

Spatie is a webdesign agency in Antwerp, Belgium. You'll find an overview of all our open source projects on our website., <sub>(*28)</sub>

License

The MIT License (MIT). Please see License File for more information., <sub>(*29)</sub>