ペジネーション 5.2 Laravel

イントロダクション

他のフレームワークのペジネーションは苦痛に満ちています。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":[
        {
            //  結果のオブジェクト
        },
        {
            //  結果のオブジェクト
        }
   ]
}

Laravel 5.2 ペジネーション