Laravel 9.x データベース：ペジネーション

イントロダクションIntroduction

他のフレームワークでは、ペジネーション（ページ付け）は非常に苦労することがあります。Laravelのペジネーションへのアプローチがが簡単であると思っていただけるよう願っています。LaravelのペジネーションはクエリビルダおよびEloquent ORMと統合されており、設定をしなくても便利で使いやすいペジネーションを提供します。In other frameworks, pagination can be very painful. We hope Laravel's approach to pagination will be a breath of fresh air. Laravel's paginator is integrated with the query builder[/docs/{{version}}/queries] and Eloquent ORM[/docs/{{version}}/eloquent] and provides convenient, easy-to-use pagination of database records with zero configuration.

デフォルトでは、ペジネータによって生成されたHTMLはTailwind CSSフレームワークと互換性があります。ただし、Bootstrapペジネーションのサポートも利用できます。By default, the HTML generated by the paginator is compatible with the Tailwind CSS framework[https://tailwindcss.com/]; however, Bootstrap pagination support is also available.

Tailwind JITTailwind JIT

LaravelのデフォルトのTailwind pagination viewとTailwind JITエンジンを使用している場合、アプリケーションのtailwind.config.jsファイルのcontentキーで、Laravelのペジネーションビューを参照し、そのTailwindクラスがパージされないようにする必要があります。If you are using Laravel's default Tailwind pagination views and the Tailwind JIT engine, you should ensure your application's tailwind.config.js file's content key references Laravel's pagination views so that their Tailwind classes are not purged:

content: [
    './resources/**/*.blade.php',
    './resources/**/*.js',
    './resources/**/*.vue',
    './vendor/laravel/framework/src/Illuminate/Pagination/resources/views/*.blade.php',
],

基本的な使い方Basic Usage

ペジネーションクエリビルダ結果Paginating Query Builder Results

アイテムをペジネーションする方法はいくつかあります。最も簡単な方法は、クエリビルダまたはEloquentクエリでpaginateメソッドを使用することです。paginateメソッドは、ユーザーが表示している現在のページに基づいて、クエリの"limit"と"offset"の設定を自動的に処理します。デフォルトでは、現在のページはHTTPリクエストのpageクエリ文字列引数の値から検出されます。この値はLaravelによって自動的に検出され、ペジネータが生成するリンクにも自動的に挿入されます。There are several ways to paginate items. The simplest is by using the paginate method on the query builder[/docs/{{version}}/queries] or an Eloquent query[/docs/{{version}}/eloquent]. The paginate method automatically takes care of setting the query's "limit" and "offset" based on the current page being viewed by the user. By default, the current page is detected by the value of the page query string argument on the HTTP request. This value is automatically detected by Laravel, and is also automatically inserted into links generated by the paginator.

この例では、paginateメソッドへ渡す引数は、唯一「ページごと」に表示するアイテムの数です。例として、ページごとに「１５」個のアイテムを表示するように指定してみましょう。In this example, the only argument passed to the paginate method is the number of items you would like displayed "per page". In this case, let's specify that we would like to display 15 items per page:

<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
use Illuminate\Support\Facades\DB;

class UserController extends Controller
{
    /**
     * アプリケーションのすべてのユーザーを表示
     *
     * @return \Illuminate\Http\Response
     */
    public function index()
    {
        return view('user.index', [
            'users' => DB::table('users')->paginate(15)
        ]);
    }
}

シンプルなペジネーションSimple Pagination

paginateメソッドは、データベースからレコードを取得する前に、クエリで一致するレコードの総数をカウントします。これは、ペジネータが合計で何ページ分のレコードがあるかを知るために行います。ただし、アプリケーションのUIに合計ページ数を表示する予定がない場合は、レコード数のクエリは不要です。The paginate method counts the total number of records matched by the query before retrieving the records from the database. This is done so that the paginator knows how many pages of records there are in total. However, if you do not plan to show the total number of pages in your application's UI then the record count query is unnecessary.

したがって、アプリケーションのUIに単純な「次へ」リンクと「前へ」リンクのみを表示する必要がある場合は、simplePaginateメソッドを使用して、単一で効率的なクエリが実行できます。Therefore, if you only need to display simple "Next" and "Previous" links in your application's UI, you may use the simplePaginate method to perform a single, efficient query:

$users = DB::table('users')->simplePaginate(15);

Eloquent結果のペジネーションPaginating Eloquent Results

Eloquentクエリをページ分割することもできます。この例では、App\Models\Userモデルをページ分割し、ページごとに１５レコードを表示するプランであることを示します。ご覧のとおり、構文はクエリビルダの結果のペジネーションとほぼ同じです。You may also paginate Eloquent[/docs/{{version}}/eloquent] queries. In this example, we will paginate the App\Models\User model and indicate that we plan to display 15 records per page. As you can see, the syntax is nearly identical to paginating query builder results:

use App\Models\User;

$users = User::paginate(15);

もちろん、where句など、クエリに他の制約を設定した後、paginateメソッドを呼び出すこともできます。Of course, you may call the paginate method after setting other constraints on the query, such as where clauses:

$users = User::where('votes', '>', 100)->paginate(15);

EloquentモデルをペジネーションするときにsimplePaginateメソッドを使用することもできます。You may also use the simplePaginate method when paginating Eloquent models:

$users = User::where('votes', '>', 100)->simplePaginate(15);

同様に、cursorPaginateメソッドをEloquentモデルのカーソルページングに使用できます。Similarly, you may use the cursorPaginate method to cursor paginate Eloquent models:

$users = User::where('votes', '>', 100)->cursorPaginate(15);

１ページ上のマルチペジネータインスタンスMultiple Paginator Instances Per Page

アプリケーションがレンダするひとつの画面上で、 2つの別々のぺジネータをレンダする必要がある場合があります。しかし、両方のペジネータのインスタンスが現在のページを格納するのにpageというクエリ文字列パラメータを使っていると、２つのペジネータが衝突してしまいます。この衝突を解決するにはpaginate、simplePaginate、cursorPaginateの各メソッドの第３引数に、ペジネータの現在のページを格納するために使いたいクエリストリングパラメータの名前を渡してください。Sometimes you may need to render two separate paginators on a single screen that is rendered by your application. However, if both paginator instances use the page query string parameter to store the current page, the two paginator's will conflict. To resolve this conflict, you may pass the name of the query string parameter you wish to use to store the paginator's current page via the third argument provided to the paginate, simplePaginate, and cursorPaginate methods:

use App\Models\User;

$users = User::where('votes', '>', 100)->paginate(
    $perPage = 15, $columns = ['*'], $pageName = 'users'
);

カーソルページングCursor Pagination

paginateとsimplePaginateがSQLの"offset"句を使用してクエリを作成するのに対し、カーソルペジネーションは "where"句を使い制約し、効率的なデータベースパフォーマンスを実現します。このペジネーションの方法は、特に大規模なデータセットや、「無限」にスクロールするユーザーインターフェイスに適しています。While paginate and simplePaginate create queries using the SQL "offset" clause, cursor pagination works by constructing "where" clauses that compare the values of the ordered columns contained in the query, providing the most efficient database performance available amongst all of Laravel's pagination methods. This method of pagination is particularly well-suited for large data-sets and "infinite" scrolling user interfaces.

ペジネイタが生成するURLのクエリ文字列にページ番号を含めるオフセットベースのペジネーションとは異なり、カーソルベースのペジネーションでは、クエリ文字列に「カーソル」文字列を配置します。カーソルは、ページ処理した次のクエリがページ処理を開始すべき場所と、ページ処理すべき方向を示すエンコードした文字列です。Unlike offset based pagination, which includes a page number in the query string of the URLs generated by the paginator, cursor based pagination places a "cursor" string in the query string. The cursor is an encoded string containing the location that the next paginated query should start paginating and the direction that it should paginate:

http://localhost/users?cursor=eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0

カーソルベースのペジネータインスタンスを作成するには，クエリビルダが提供するcursorPaginateメソッドを使用します。このメソッドは，Illuminate\Pagination\CursorPaginatorインスタンスを返します。You may create a cursor based paginator instance via the cursorPaginate method offered by the query builder. This method returns an instance of Illuminate\Pagination\CursorPaginator:

$users = DB::table('users')->orderBy('id')->cursorPaginate(15);

カーソルページネータインスタンスを取得したら、paginateやsimplePaginateメソッドを使うときと同様に、ペジネーションの結果を表示します。カーソルペジネータが提供するインスタンスメソッドの詳細は、カーソルペジネータインスタンスのドキュメントを参照してください。Once you have retrieved a cursor paginator instance, you may display the pagination results[#displaying-pagination-results] as you typically would when using the paginate and simplePaginate methods. For more information on the instance methods offered by the cursor paginator, please consult the cursor paginator instance method documentation[#cursor-paginator-instance-methods].

warning Warning!
カーソルのペジネーションを利用するには、クエリに "order by"句を含める必要があります。Warning
Your query must contain an "order by" clause in order to take advantage of cursor pagination.

カーソル vs. オフセットペジネーションCursor vs. Offset Pagination

オフセットページングとカーソルページングの違いを説明するために、いくつかのSQLクエリの例を見てみましょう。以下のクエリはどちらも、usersテーブルの結果をidで並べた「２ページ目」を表示します。To illustrate the differences between offset pagination and cursor pagination, let's examine some example SQL queries. Both of the following queries will both display the "second page" of results for a users table ordered by id:

# オフセットページング
select * from users order by id asc limit 15 offset 15;

# カーソルページング
select * from users where id > 15 order by id asc limit 15;

カーソルページングクエリは、オフセットページングに比べて以下の利点があります。The cursor pagination query offers the following advantages over offset pagination:

• 大規模なデータセットの場合、"order by"のカラムにインデックスが付けられている場合、カーソルページングはパフォーマンスが向上します。これは、"offset"句が以前に一致したデータをすべてスキャンするためです。For large data-sets, cursor pagination will offer better performance if the "order by" columns are indexed. This is because the "offset" clause scans through all previously matched data.
• 頻繁な書き込みを伴うデータセットの場合、直前にレコードが追加／削除されている場合、ユーザーが現在閲覧しているページの結果からレコードが飛ばされたり、二重に表示されたりする可能性があります。For data-sets with frequent writes, offset pagination may skip records or show duplicates if results have been recently added to or deleted from the page a user is currently viewing.

ただし、カーソルペジネーションには以下の制限があります。However, cursor pagination has the following limitations:

• simplePaginateのように、カーソルのペジネーションは"次へ"と"前へ"のリンクを表示するためにのみ使用でき、ページ番号付きのリンクの生成をサポートしていません。Like simplePaginate, cursor pagination can only be used to display "Next" and "Previous" links and does not support generating links with page numbers.
• ソート順は少なくとも１つの一意なカラム、または一意なカラムの組み合わせに基づく必要があります。null値を持つカラムはサポートしていません。It requires that the ordering is based on at least one unique column or a combination of columns that are unique. Columns with null values are not supported.
• "order by"句のクエリ表現はエイリアス化され、"select"句にも同様に追加されている場合のみサポートします。Query expressions in "order by" clauses are supported only if they are aliased and added to the "select" clause as well.
• パラメータを含むクエリ表現は、サポートしていません。Query expressions with parameters are not supported.

ペジネータの手作業生成Manually Creating A Paginator

場合によっては、ペジネーションインスタンスを手作業で作成し、メモリ内にすでにあるアイテムの配列を渡すことができます。必要に応じて、Illuminate\Pagination\Paginator、Illuminate\Pagination\LengthAwarePaginator、Illuminate\Pagination\CursorPaginatorインスタンスを生成することでこれが行えます。Sometimes you may wish to create a pagination instance manually, passing it an array of items that you already have in memory. You may do so by creating either an Illuminate\Pagination\Paginator, Illuminate\Pagination\LengthAwarePaginator or Illuminate\Pagination\CursorPaginator instance, depending on your needs.

PaginatorとCursorPaginatorクラスは結果セットのアイテムの総数を知る必要はありません。しかしこのため、これらのクラスには最後のページのインデックスを取得するメソッドがありません。LengthAwarePaginatorはPaginatorとほぼ同じ引数を取りますが、結果セットのアイテムの総数をカウントする必要があります．The Paginator and CursorPaginator classes do not need to know the total number of items in the result set; however, because of this, these classes do not have methods for retrieving the index of the last page. The LengthAwarePaginator accepts almost the same arguments as the Paginator; however, it requires a count of the total number of items in the result set.

つまり，PaginatorはクエリビルダのsimplePaginateメソッドに、CursorPaginatorはcursorPaginateメソッドに，LengthAwarePaginatorはpaginateメソッドに、それぞれ対応しています。In other words, the Paginator corresponds to the simplePaginate method on the query builder, the CursorPaginator corresponds to the cursorPaginate method, and the LengthAwarePaginator corresponds to the paginate method.

warning Warning!
ペジネーションインスタンスを手作業で作成する場合は、ペジネーションに渡す結果の配列を手作業で「スライス」する必要があります。これを行う方法がわからない場合は、array_slicePHP関数を確認してください。Warning
When manually creating a paginator instance, you should manually "slice" the array of results you pass to the paginator. If you're unsure how to do this, check out the array_slice[https://secure.php.net/manual/en/function.array-slice.php] PHP function.

ペジネーションURLのカスタマイズCustomizing Pagination URLs

デフォルトでは、ペジネータにが生成するリンクは、現在のリクエストのURIと一致します。ただし、ペジネータのwithPathメソッドを使用すると、リンクを生成するときにペジネータが使用するURIをカスタマイズできます。たとえば、ペジネータでhttp://example.com/admin/users？page=Nのようなリンクを生成したい場合は、/admin/usersをwithPathメソッドに渡します。By default, links generated by the paginator will match the current request's URI. However, the paginator's withPath method allows you to customize the URI used by the paginator when generating links. For example, if you want the paginator to generate links like http://example.com/admin/users?page=N, you should pass /admin/users to the withPath method:

use App\Models\User;

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

    $users->withPath('/admin/users');

    //
});

クエリ文字列の追加Appending Query String Values

appendsメソッドを使用して、ペジネーションリンクのクエリ文字列へ追加できます。たとえば、各ペジネーションリンクにsort=votesを追加するには、appendsを以下のように呼び出します。You may append to the query string of pagination links using the appends method. For example, to append sort=votes to each pagination link, you should make the following call to appends:

use App\Models\User;

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

    $users->appends(['sort' => 'votes']);

    //
});

現在のリクエストのすべてのクエリ文字列値をペジネーションリンクに追加する場合は、withQueryStringメソッドを使用できます。You may use the withQueryString method if you would like to append all of the current request's query string values to the pagination links:

$users = User::paginate(15)->withQueryString();

ハッシュフラグメントの追加Appending Hash Fragments

paginatorによって生成されたURLに「ハッシュフラグメント」を追加する必要がある場合は、fragmentメソッドを使用できます。たとえば、各ペジネーションリンクの最後に#usersを追加するには、次のようにfragmentメソッドを呼び出します。If you need to append a "hash fragment" to URLs generated by the paginator, you may use the fragment method. For example, to append #users to the end of each pagination link, you should invoke the fragment method like so:

$users = User::paginate(15)->fragment('users');

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

paginateメソッドを呼ぶと、Illuminate\Pagination\LengthAwarePaginatorインスタンスが返され，simplePaginateメソッドを呼ぶと、Illuminate\Pagination\Paginatorインスタンスが返されます。そして、cursorPaginateメソッドを呼び出すと、Illuminate\CursorPaginatorインスタンスが返されます。When calling the paginate method, you will receive an instance of Illuminate\Pagination\LengthAwarePaginator, while calling the simplePaginate method returns an instance of Illuminate\Pagination\Paginator. And, finally, calling the cursorPaginate method returns an instance of Illuminate\Pagination\CursorPaginator.

これらのオブジェクトは、結果セットを表示するメソッドをいくつか提供しています。これらヘルパメソッドに加え、ペジネータインスタンスはイテレータであり、配列としてループ処理も可能です。つまり、結果を取得したら、Blade を使って結果を表示したり、ページリンクをレンダしたりできるのです。These objects provide several methods that describe the result set. In addition to these helper methods, the paginator instances are iterators and may be looped as an array. So, once you have retrieved the results, you may display the results and render the page links using Blade[/docs/{{version}}/blade]:

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

{{ $users->links() }}

linksメソッドは、結果セットの残りのページへのリンクをレンダします。これらの各リンクには、適切なpageクエリ文字列変数がすでに含まれています。linksメソッドが生成するHTMLは、Tailwind CSSフレームワークと互換性があることを忘れないでください。The links method will render the links to the rest of the pages in the result set. Each of these links will already contain the proper page query string variable. Remember, the HTML generated by the links method is compatible with the Tailwind CSS framework[https://tailwindcss.com].

ペジネーションリンクウィンドウの調整Adjusting The Pagination Link Window

ページネータがページ処理用のリンクを表示する際には、現在のページ番号に加え、現在のページの前後３ページ分のリンクが表示されます。onEachSideメソッドを使用して、ページネータが生成するリンクの中央のスライディングウィンドウ内の現在のページの両側に表示する追加のリンク数を制御できます。When the paginator displays pagination links, the current page number is displayed as well as links for the three pages before and after the current page. Using the onEachSide method, you may control how many additional links are displayed on each side of the current page within the middle, sliding window of links generated by the paginator:

{{ $users->onEachSide(5)->links() }}

結果のJSONへの変換Converting Results To JSON

LaravelペジネータクラスはIlluminate\Contracts\Support\Jsonableインターフェイスコントラクトを実装し、toJsonメソッドを提供しているため、ペジネーションの結果をJSONに変換するのは非常に簡単です。ルートまたはコントローラアクションから返すことで、ペジネーションインスタンスをJSONに変換することもできます。The Laravel paginator classes implement the Illuminate\Contracts\Support\Jsonable Interface contract and expose the toJson method, so it's very easy to convert your pagination results to JSON. You may also convert a paginator instance to JSON by returning it from a route or controller action:

use App\Models\User;

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

ペジネーターからのJSONは、total、current_page、last_pageなどのメタ情報を持っています。結果レコードは、JSON配列のdataキーを介して利用できます。ルートからペジネーションインスタンスを返すことによって作成されたJSONの例を以下で紹介します。The JSON from the paginator will include meta information such as total, current_page, last_page, and more. The result records are available via the data key in the JSON array. Here is an example of the JSON created by returning a paginator instance from a route:

{
   "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":[
        {
            // レコード…
        },
        {
            // レコード…
        }
   ]
}

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

デフォルトでは、ペジネーションリンクを表示するためにレンダリングされたビューは、Tailwind CSSフレームワークと互換性があります。ただし、Tailwindを使用しない場合は、これらのリンクをレンダするために独自のビューを自由に定義できます。paginatorインスタンスでlinksメソッドを呼び出すとき、メソッドの最初の引数としてビュー名を渡すことができます。By default, the views rendered to display the pagination links are compatible with the Tailwind CSS[https://tailwindcss.com] framework. However, if you are not using Tailwind, you are free to define your own views to render these links. When calling the links method on a paginator instance, you may pass the view name as the first argument to the method:

{{ $paginator->links('view.name') }}

<!-- 追加データをビューへ渡す -->
{{ $paginator->links('view.name', ['foo' => 'bar']) }}

ただし、ペジネーションビューをカスタマイズする最も簡単な方法は、vendor:publishコマンドを使用してresources/views/vendorディレクトリにエクスポートすることです。However, the easiest way to customize the pagination views is by exporting them to your resources/views/vendor directory using the vendor:publish command:

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

このコマンドは、ビューをアプリケーションのresources/views/vendor/paginationディレクトリに配置します。このディレクトリ内のtailwind.blade.phpファイルが、デフォルトのペジネーションビューに対応しています。このファイルを編集して、ペジネーションHTMLを変更できます。This command will place the views in your application's resources/views/vendor/pagination directory. The tailwind.blade.php file within this directory corresponds to the default pagination view. You may edit this file to modify the pagination HTML.

別のファイルをデフォルトのペジネーションビューとして指定する場合は、App\Providers\AppServiceProviderクラスのbootメソッド内でペジネーションのdefaultViewメソッドとdefaultSimpleViewメソッドを呼び出すことができます。If you would like to designate a different file as the default pagination view, you may invoke the paginator's defaultView and defaultSimpleView methods within the boot method of your App\Providers\AppServiceProvider class:

<?php

namespace App\Providers;

use Illuminate\Pagination\Paginator;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * 全アプリケーションサービスの初期起動処理
     *
     * @return void
     */
    public function boot()
    {
        Paginator::defaultView('view-name');

        Paginator::defaultSimpleView('view-name');
    }
}

Bootstrapの使用Using Bootstrap

Laravelは、Bootstrap CSSを使用し構築した、ペジネーションビューを用意しています。デフォルトのTailwindビューの代わりにこのビューを使うには、App\Providers\AppServiceProviderクラスのbootメソッドないから、ペジネータのuseBootstrapFourまたはuseBootstrapFiveメソッドを呼び出してください。Laravel includes pagination views built using Bootstrap CSS[https://getbootstrap.com/]. To use these views instead of the default Tailwind views, you may call the paginator's useBootstrapFour or useBootstrapFive methods within the boot method of your App\Providers\AppServiceProvider class:

use Illuminate\Pagination\Paginator;

/**
 * 全アプリケーションサービスの初期起動処理
 *
 * @return void
 */
public function boot()
{
    Paginator::useBootstrapFive();
    Paginator::useBootstrapFour();
}

Paginator／LengthAwarePaginatorインスタンスのメソッドPaginator / LengthAwarePaginator Instance Methods

各ペジネーションインスタンスは、以下のメソッドで追加のペジネーション情報を提供します。Each paginator instance provides additional pagination information via the following methods:

カーソルPaginatorインスタンスのメソッドCursor Paginator Instance Methods

各カーソルペジネータインスタンスは、以降のメソッドで追加のペジネーション情報を提供します。Each cursor paginator instance provides additional pagination information via the following methods: