イントロダクション
他のフレームワークのペジネーションは苦痛に満ちています。Laravelはこれを簡単にしました。現在のページ位置に基づいて賢い「ページ範囲」のリンクを生成します。生成されるHTMLはBootstrap CSSフレームワークへ適応しています。
基本的な使用法
クエリビルダの結果
アイテムをページ分けするには多くの方法があります。一番シンプルな方法はクエリビルダかEloquentクエリに、paginate
メソッドを用いることです。Laravelが提供するpaginate
メソッドは、ユーザが表示している現在のページに基づき、正しいアイテム数とオフセットを指定する面倒を見ます。デフォルトではHTTPリクエストの?page
クエリ文字列引数の値により現在ページが決められます。もちろんこの値はLaravelが自動的に探し、さらにペジネーターが挿入するリンクを自動的に生成します。
最初にクエリに対するpaginate
メソッドの呼び出しに注目しましょう。以下の例ではpaginate
に一つだけ引数を渡しており、「ページごと」に表示したいアイテム数です。この例ではページごとに15
アイテムを表示するように指定しています。
<?php
namespace App\Http\Controllers;
use DB;
use App\Http\Controllers\Controller;
class UserController extends Controller
{
/**
* アプリケーションの全ユーザー表示
*
* @return Response
*/
public function index()
{
$users = DB::table('users')->paginate(15);
return view('user.index', ['users' => $users]);
}
}
注意: 現在
groupBy
メソッドを使用したペジネーション操作は、Laravelで正しく実行できません。groupBy
を使用したペジネーションを使用する必要がある場合はデータベースクエリを実行し、その結果を元にペジネーターを自前で作成してください。
シンプル・ペジネーション
「次」と「前」のリンクだけのシンプルなペジネーションビューを表示したい場合はsimplePaginate
メソッドを使用し、より効率的にクエリすべきでしょう。これはビューに正確なページ番号を表示する必要がない、巨大なデータセットを扱う場合に便利です。
$users = DB::table('users')->simplePaginate(15);
Eloquentの結果
さらにEloquentモデルもペジネーションできます。例としてUser
モデルの15
アイテムをページ付け表示してみましょう。ご覧の通り、クエリビルダ結果のペジネーションを行う記法はきれいでわかりやすいものです。
$users = App\User::paginate(15);
もちろんwhere
節のような制約をクエリに指定した後にpaginate
を呼び出すこともできます。
$users = User::where('votes', '>', 100)->paginate(15);
Elqouentモデルをページづけするときにも、simplePaginate
メソッドを使用できます。
$users = User::where('votes', '>', 100)->simplePaginate(15);
独自ペジネータ作成
渡された配列を元にして、ペジネーションインスンタンスを作成したいこともあります。必要に応じてIlluminate\Pagination\Paginator
か、Illuminate\Pagination\LengthAwarePaginator
インスタンスを生成することで実現できます。
Paginator
クラスは結果にセットされているアイテムの総数を知る必要はありません。そのためクラスは最終ページのインデックスを取得するメソッドを持っていません。LengthAwarePaginator
はPaginator
とほとんど同じ引数を取りますが、結果にセットされているアイテム総数も指定する必要がある点が異なっています。
言い換えれば、Paginator
はクエリビルダとEloquentに対するsimplePaginate
メソッドに対応し、一方のLengthAwarePaginator
はpaginate
に対応しています。
自前でペジネーターインスタンスを生成する場合、ペジネーターに渡す結果の配列を自分で"slice"する必要があります。その方法を思いつかなければ、array_slice PHP関数を調べてください。
ビューでの結果表示
クエリビルダかEloquentクエリでpaginate
やsimplePaginate
メソッドを呼び出す場合、Illuminate\Pagination\LengthAwarePaginator
のインスタンスを受け取ります。simplePaginate
メソッドを呼び出した場合はIlluminate\Pagination\Paginator
インスタンスを受け取ります。これらのオブジェクトは結果を表すたくさんのメソッドを提供しています。こうしたヘルパメソッドに加え、ペジネーターインスタンスはイテレータでもあり、配列としてループ処理できます。
つまり結果を取得したら、その結果とページリンクをBladeを使い表示できます。
<div class="container">
@foreach ($users as $user)
{{ $user->name }}
@endforeach
</div>
{{ $users->links() }}
links
メソッドは他のページヘのリンクをレンダーします。それらの各リンクには?page
クエリー文字列変数が含まれています。links
メソッドが生成するHTMLはBootstrap
CSSフレームワークと互換性があることを覚えておいてください。
ペジネーターURIのカスタマイズ
setPath
メソッドにより、ペジネーターがリンクを生成するときに使用するURIをカスタマイズできます。たとえばペジネーターでhttp://example.com/custom/url?page=N
のようなリンクを生成したい場合、setPath
メソッドにcustom/url
を渡してください。
Route::get('users', function () {
$users = App\User::paginate(15);
$users->setPath('custom/url');
//
});
ペジネーションリンクの追加
ペジネーションリンクにクエリ文字列を付け加えたいときは、appends
メソッドを使います。たとえば&sort=votes
を各ペジネーションリンクに追加する場合には、以下のようにappends
を呼び出します。
{{ $users->appends(['sort' => 'votes'])->links() }}
ペジネーションのURLに「ハッシュフラグメント」を追加したい場合は、fragment
メソッドが使用できます。例えば各ペジネーションリンクの最後に#foo
を追加したい場合は、以下のようにfragment
メソッドを呼び出します。
{{ $users->fragment('foo')->links() }}
その他のヘルパメソッド
さらに以下のようなペジネーターインスタンスのメソッドにより、追加のペジネーション情報へアクセスできます。
$results->count()
$results->currentPage()
$results->firstItem()
$results->hasMorePages()
$results->lastItem()
$results->lastPage() (simplePaginateでは使用不可)
$results->nextPageUrl()
$results->perPage()
$results->previousPageUrl()
$results->total() (simplePaginateでは使用不可)
$results->url($page)
結果のJSON変換
Laravelのペジネーター結果クラスはIlluminate\Contracts\Support\JsonableInterface
契約を実装しており、toJson
メソッドを提示しています。ですからペジネーション結果をJSONにとても簡単に変換できます。
またルートやコントローラーアクションからシンプルにペジネーターインスタンスを返せば、JSONへ変換されます。
Route::get('users', function () {
return App\User::paginate();
});
ペジネーターのJSON形式はtotal
、current_page
、last_page
などのメタ情報を含んでいます。実際の結果オブジェクトはJSON配列のdata
キーにより利用できます。ルートから返されたペジネーターインスタンスにより生成されるJSONの一例を見てください。
ペジネーターJSONの一例
{
"total": 50,
"per_page": 15,
"current_page": 1,
"last_page": 4,
"next_page_url": "http://laravel.app?page=2",
"prev_page_url": null,
"from": 1,
"to": 15,
"data":[
{
// 結果のオブジェクト
},
{
// 結果のオブジェクト
}
]
}