forPage — コレクションをページごとに切り出す

カテゴリ: collection
掲載バージョン: Laravel 12・PHP 8.4
名前空間 / FQCN: Illuminate\Support\Collection::forPage
関連: slice / skip / take / values / Pagination（LengthAwarePaginator）
変更履歴: Laravel 5.1 から提供（大きな仕様変更なし）。(Laravel)

要点（TL;DR）
概要
構文 / シグネチャ
使用例
よくある落とし穴・注意
代替・関連APIとの比較
テスト例（Pest）
トラブルシュート（エラー別）
コレクション固有情報
参考リンク
関連記事

要点（TL;DR）

指定ページ番号と件数で、対象ページ分だけを新しいコレクションとして返す。(Laravel)
最小コード：$pageItems = collect($items)->forPage($page, $perPage); (Laravel)
罠：Pager生成は別途（paginate()はビルダー専用）／キー再採番が必要になる場面あり（values()）。(Laravel, Stack Overflow)

概要

forPage($page, $perPage) は、コレクションを「nページ目に表示する要素群」に限定して返します。Eloquent の paginate() と異なり、リンク生成や総件数管理は行いません。配列処理や API レスポンスを手組みする際の軽量なページ分割に使います。(Laravel)

構文 / シグネチャ

public function forPage(int $page, int $perPage): Illuminate\Support\Enumerable

この定義は Collection が持つ EnumeratesValues トレイト由来です。(Laravel API)

引数（表）

引数	型	必須	既定値	説明
`$page`	int	✅	—	取得したいページ番号（1始まり）
`$perPage`	int	✅	—	1ページあたり件数

戻り値：Collection（Enumerable）— 指定ページに相当する要素だけを持つ新しいコレクション。(Laravel API)
例外/副作用：なし（非破壊）。※ページ外指定でも空コレクションを返す。

使用例

最小例

use Illuminate\Support\Collection;

$numbers = collect([1,2,3,4,5,6,7,8,9]);
$chunk   = $numbers->forPage(2, 3);

dump($chunk->all()); // [4, 5, 6]

この例は公式ドキュメントと同等です。(Laravel)

実務例：コレクションから手動ページネーション（LengthAwarePaginator）

use Illuminate\Pagination\LengthAwarePaginator;
use Illuminate\Support\Collection;
use Illuminate\Support\Facades\Request;

$items    = collect($rawArray);                 // なんらかの配列→コレクション
$page     = (int) Request::get('page', 1);
$perPage  = 20;

$paginatedItems = $items->forPage($page, $perPage)->values(); // 必要なら再採番
$paginator = new LengthAwarePaginator(
    $paginatedItems,
    $items->count(),                            // 総件数
    $perPage,
    $page,
    ['path' => Request::url(), 'query' => Request::query()]
);

return view('list', ['paginator' => $paginator]);

メモ：paginate() はクエリビルダー/Eloquent 専用。生の Collection では LengthAwarePaginator を自前生成します。キーが疎な場合は values() で再採番してから渡すと無難です。(Laravel, Stack Overflow, Gist)

よくある落とし穴・注意

リンクは出ない：forPage は要素の切り出しだけ。ページリンク等は LengthAwarePaginator で。(Laravel)
キーの扱い：slice 相当の動作では元キーが保存され得るため、ページャ渡し時は values() で連番化を推奨。(Laravel, Gist)
LazyCollection でも使用可：LazyCollection は Enumerable の非破壊メソッドを概ね利用可能（破壊的メソッドのみ不可）。forPage は非破壊のため使用できます。(Laravel)
計算量：内部はスライス相当で概ね O(n)。巨大配列では上流での絞り込み（DB側ページング）を優先。

代替・関連APIとの比較

paginate()（Query Builder/Eloquent）：SQL レベルで最小取得＋リンク生成。UI付きページングならこちら。(Laravel)
slice($offset, $length)：任意オフセット/長さで切り出し。ページ番号で扱うなら forPage が意図に沿う。(Laravel)
skip($n) + take($m)：チェーンで同等表現可。読みやすさは forPage。
values()：キーを0始まりに再採番（ページャと併用しやすい）。(Laravel)

テスト例（Pest）

<?php

use Illuminate\Support\Collection;

it('picks items for the given page', function () {
    $c = collect([1,2,3,4,5,6,7,8,9]);
    expect($c->forPage(3, 2)->all())->toBe([5,6]);
});

トラブルシュート（エラー別）

症状/エラー	原因	対処
`Call to undefined method Collection::paginate()`	`paginate()` はビルダー/Eloquent専用	`LengthAwarePaginator` を自前生成し、`forPage` + 総件数で組み立てる。(Laravel)
ページリンクが出ない	`forPage` はリンク生成をしない	`LengthAwarePaginator` を使い、Blade で `{{ $paginator->links() }}` を表示。(Laravel)
ページに表示される順序/インデックスが不自然	元キーが保持されている	`values()` で再採番してからページャに渡す。(Laravel, Gist)

コレクション固有情報

チェーン可否：可（非破壊）
破壊的/非破壊：非破壊
キー保持：状況により元キーを保持し得るため、必要に応じ values() で再採番推奨。(Laravel)
LazyCollection：利用可（非破壊メソッド）。(Laravel)
計算量の目安：O(n)（スライス相当）
入出力対応（例）

入力	呼び出し	出力
`[1..9]`	`forPage(2,3)`	`[4,5,6]` (Laravel)
`['a'=>10,'b'=>20,'c'=>30,'d'=>40]`	`forPage(2,2)->values()`	`[30,40]`（再採番後） (Laravel)

参考リンク

Laravel公式ドキュメント：Collections – forPage（使用例あり） (Laravel)
Laravel API：Illuminate\Support\Collection::forPage（シグネチャ） (Laravel API)
Laravel公式：Pagination（手動ページネーションの考え方） (Laravel)
（補足）slice とキー保持の説明（values()で再採番） (Laravel)
備考：コレクションからページャを作る際の注意（外部記事・Q&A） (Stack Overflow)