データベース：ペジネーション

イントロダクション
基本的な使用法
ペジネーション結果の表示
- 結果のJSON変換
ペジネーションビューのカスタマイズ
ペジネータインスタンスメソッド

イントロダクション

他のフレームワークのペジネーションは苦痛に満ちています。LaravelのペジネータはクエリビルダとEloquent ORMに統合されており、データベースの結果を簡単、お手軽にペジネーションできます。ペジネータが生成するHTMLは、Bootstrap CSSフレームワークコンパチブルです。

基本的な使用法

クエリビルダの結果

アイテムをペジネーションするには多くの方法があります。一番簡単な方法は、クエリビルダとEloquent queryへpaginateメソッドを使う方法です。paginateメソッドは、ユーザーが表示している現在のページに基づき、正しいアイテム数とオフセットを指定する面倒を見ます。デフォルトではHTTPリクエストのpageクエリ文字列引数の値により現在ページが決められます。もちろんこの値はLaravelが自動的に探し、さらにペジネーターが挿入するリンクを自動的に生成します。

以下の例では、paginateに一つだけ引数を渡しており、「ページごと」に表示したいアイテム数です。この例ではページごとに15アイテムを表示するように指定しています。

<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\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]);
    }
}

{note} 現在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に対応しています。

{note} 自前でペジネーターインスタンスを生成する場合、ペジネーターに渡す結果の配列を自分で”slice”する必要があります。その方法を思いつかなければ、array_slice PHP関数を調べてください。

ペジネーション結果の表示

paginateメソッドを呼び出す場合、Illuminate\Pagination\LengthAwarePaginatorインスタンスを受け取ります。simplePaginateメソッドを呼び出すときは、Illuminate\Pagination\Paginatorインスタンスを受け取ります。これらのオブジェクトは結果を表すたくさんのメソッドを提供しています。こうしたヘルパメソッドに加え、ペジネーターインスタンスはイテレータでもあり、配列としてループ処理できます。つまり結果を取得したら、その結果とページリンクをBladeを使い表示できます。

<div class="container">
    @foreach ($users as $user)
        
    @endforeach
</div>

linksメソッドは結果の残りのページヘのリンクをレンダーします。それらの各リンクにはpageクエリ文字列変数が含まれています。linksメソッドが生成するHTMLはBootstrap CSSフレームワークと互換性があることを覚えておいてください。

ペジネーターURIのカスタマイズ

withPathメソッドにより、ペジネーターがリンクを生成するときに使用するURIをカスタマイズできます。たとえばペジネーターでhttp://example.com/custom/url?page=Nのようなリンクを生成したい場合、withPathメソッドにcustom/urlを渡してください。

Route::get('users', function () {
    $users = App\User::paginate(15);

    $users->withPath('custom/url');

    //
});

ペジネーションリンクの追加

ペジネーションリンクにクエリ文字列を付け加えたいときは、appendsメソッドを使います。たとえばsort=votesを各ペジネーションリンクに追加する場合には、以下のようにappendsを呼び出します。

ペジネーションのURLに「ハッシュフラグメント」を追加したい場合は、fragmentメソッドが使用できます。例えば各ペジネーションリンクの最後に#fooを追加したい場合は、以下のようにfragmentメソッドを呼び出します。

結果のJSON変換

Laravelのペジネーター結果クラスはIlluminate\Contracts\Support\Jsonableインターフェイス契約を実装しており、toJsonメソッドを提示しています。ですからペジネーション結果をJSONにとても簡単に変換できます。またルートやコントローラアクションからシンプルにペジネーターインスタンスを返せば、JSONへ変換されます。

Route::get('users', function () {
    return App\User::paginate();
});

ペジネーターのJSON形式はtotal、current_page、last_pageなどのメタ情報を含んでいます。実際の結果オブジェクトはJSON配列のdataキーにより利用できます。ルートから返されたペジネーターインスタンスにより生成されるJSONの一例を見てください。

{
   "total": 50,
   "per_page": 15,
   "current_page": 1,
   "last_page": 4,
   "first_page_url": "http://laravel.app?page=1",
   "last_page_url": "http://laravel.app?page=4",
   "next_page_url": "http://laravel.app?page=2",
   "prev_page_url": null,
   "path": "http://laravel.app",
   "from": 1,
   "to": 15,
   "data":[
        {
            // 結果のオブジェクト
        },
        {
            // 結果のオブジェクト
        }
   ]
}

ペジネーションビューのカスタマイズ

デフォルトで、ペジネーションリンクを表示するためのビューはBootstrap CSSフレームワークを用いてレンダーされます。しかし、Bootstrapを使っていない場合でも、そうしたリンクをレンダーする独自のビューを自由に定義できます。ペジネータインスタンスのlinksメソッドを呼び出す際に、ビュー名をメソッドの最初の引数として渡してください。

// ビューへデータを渡す

しかし、vendor:publishコマンドを使用し、resources/views/vendorディレクトリへペジネーションビューを作成し、カスタマイズする方法が一番簡単でしょう。

php artisan vendor:publish --tag=laravel-pagination

このコマンドは、resources/views/vendor/paginationディレクトリへビューを設置します。このディレクトリのdefault.blade.phpファイルが、デフォルトペジネーションビューに対応します。ペジネーションのHTMLを変更するには、ただこのファイルを編集するだけです。

ペジネータインスタンスメソッド

ペジネータインスタンスは以下の追加ペジネーション情報を提供しています。

$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)