before — 直前の要素を取得するメソッド

カテゴリ: collection
対応バージョン: Laravel 11・12／PHP 8.2
名前空間 / FQCN / コマンド: Illuminate\Support\Collection::before
関連: after / search / first / last / slice
変更履歴: Laravel 11で追加（10には未収録）。(Laravel)

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

要点（TL;DR）

指定要素の直前の値を返す（見つからない／先頭なら null）。(Laravel)
使い方：collect([1,2,3])->before(2); // 1 (Laravel)
罠：厳密比較を使わないと "2" と 2 が等しいとみなされる／最初の一致のみ対象／戻り値は値でキーは返らない。(Laravel)

概要

before() はコレクション内で与えた要素の直前にある値を返します。見つからない、または対象が先頭の場合は null を返します。検索は既定で緩やかな比較（==）で行われ、必要に応じて strict: true で厳密比較（===）に切り替えられます。値の代わりに条件クロージャを渡して「条件に合致する最初の要素の直前」を取得することも可能です。(Laravel)

構文 / シグネチャ

// 値を指定して検索（既定は緩やかな比較）
mixed|null Collection::before(mixed $item, bool $strict = false);

// 条件クロージャで検索（最初に合致した要素の直前）
mixed|null Collection::before(Closure $callback);

引数（表） 引数型必須既定値説明 $item mixed いずれか — 直前を取得したい要素の“値”。$callbackと排他 $strict bool いいえ false trueで厳密比較（===）。既定は緩やか（==） $callback Closure(int $value, int string $key): bool いずれか —
戻り値：mixed|null（直前の値。存在しなければ null）(Laravel)
例外/副作用：なし（非破壊）。検索は線形走査。

使用例

最小例

<?php

use Illuminate\Support\Collection;

$numbers = collect([10, 20, 30, 40]);

echo $numbers->before(30);          // 20（直前）
var_dump($numbers->before(10));     // null（先頭の直前はない）
echo $numbers->before('30', true);  // null（厳密比較で不一致）

(Laravel)

実務例：記事一覧で「前の記事」を取得

<?php

use App\Models\Post;

// 公開日の昇順に並んだコレクション
$posts = Post::orderBy('published_at')->get();

// 現在の記事ID
$currentId = (int) request('post_id');

// 条件に一致する（= 現在の記事）要素の「直前」を取得
$prevPost = $posts->before(fn (Post $p) => $p->id === $currentId);

if ($prevPost) {
    // 前の記事の詳細へリンク
    return redirect()->route('posts.show', $prevPost);
}

（条件クロージャで「現在の記事の直前」を安全に取得）(Laravel)

よくある落とし穴・注意

比較の既定は緩やか（==）：文字列 "2" と数値 2 は等しい。数値や真偽値を扱うときは strict: true を付ける。(Laravel)
最初の一致のみが基準：重複値がある場合、最初に見つかった要素の直前を返す。重複を区別したいならクロージャで条件を絞る。(Laravel)
キーは返らない：戻り値は値。キーが必要なら keys()->search($item) で位置を求めてから slice() 等で扱う。
バージョン差分：Laravel 10 には未収録。Call to undefined method before() はバージョン不一致の可能性が高い。(Laravel)
計算量：O(n)（先頭から順に探索）。

代替・関連APIとの比較

after：指定要素の直後の値を返す。前後ナビを構成するなら before と対で使用。(Laravel)
search：要素のキー/位置を返す。キー起点で前要素を取りたいときは search() → slice(0, $index) などが明示的。
slice / takeUntil：部分コレクションが欲しい場合に有効（before は値ひとつのみ）。(Laravel)

テスト例（Pest）

<?php

use Illuminate\Support\Collection;

it('gets previous item', function () {
    $c = collect([1, 2, 3]);
    expect($c->before(2))->toBe(1);
    expect($c->before(1))->toBeNull();
});

it('respects strict comparison', function () {
    $c = collect([2, 4, 6, 8]);
    expect($c->before('4', strict: true))->toBeNull();
});

(Laravel)

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

症状/エラー	原因	対処
`Call to undefined method Illuminate\Support\Collection::before()`	Laravel 10系以下	フレームワークを11以上へ更新、または代替実装（`search()`＋`slice()`）を使用。(Laravel)
期待と異なる要素が返る	緩やかな比較により型が混在	`strict: true` を付与、またはクロージャで条件を厳密化。(Laravel)
重複値で意図しない結果	最初の一致のみが基準	クロージャで「どの要素を基準にするか」を明示。(Laravel)

参考リンク

Laravel公式ドキュメント：Collections（before() の説明と例） — laravel.com/docs/12.x/collections#before (Laravel)
Laravel公式ドキュメント：Collections 11.x（メソッド一覧に before を掲載） — laravel.com/docs/11.x/collections (Laravel)
Laravel公式ドキュメント：Collections 10.x（before 未掲載の比較用） — laravel.com/docs/10.x/collections (Laravel)

チェーン可否：不可（値を返すためチェーンは終了）／破壊性：非破壊／キー保持：戻り値は値のみ
LazyCollection：before は標準 Collection のメソッド。大規模処理で直前要素の値が必要なら、cursor()->collect()->before(...) のように通常コレクションへ変換して利用するのが安全。(Laravel)