- カテゴリ: collection
- 掲載バージョン: Laravel 12・PHP 8.4
- 名前空間 / FQCN / コマンド:
Illuminate\Support\Collection::contains - 関連: containsStrict / containsOneItem / has / where / filter
- 変更履歴: —
要点（TL;DR）
- 配列/オブジェクトの集合に特定の値や条件を満たす要素があるかを
boolで返す - 最低限:
$collection->contains('status', 'active') - 罠: 「ゆるい比較（==）が既定」／
like等の演算子は不可→コールバックで対応／走査は O(n)（巨大データは注意）
概要
contains は、コレクション内に指定の値が存在するか、または各要素が条件を満たすものがあるかを判定します。
単純な値一致、key = value 形式、key operator value 形式、任意ロジックのコールバックに対応。Eloquent モデルの属性比較にもそのまま使えます。
構文 / シグネチャ
bool contains(mixed $key, mixed $operator = null, mixed $value = null);
bool contains(Closure $callback);
引数（使い分け）
| 引数 | 型 | 必須 | 既定値 | 説明 |
|---|---|---|---|---|
$value | mixed | 条件 | — | 1引数で値一致（== 比較）: contains(100) |
$key, $value | string/int, mixed | 条件 | — | 2引数でキー=値一致: contains('status', 'active') |
$key, $operator, $value | string/int, string, mixed | 条件 | — | 3引数で演算子比較: contains('age', '>=', 18)（=, ==, !=, <, >, <=, >=, ===, !==） |
$callback | Closure($item, $key): bool | 条件 | — | 任意ロジック。true を返した時点で true |
- 戻り値：
bool（少なくとも1件一致すればtrue） - 例外/副作用：例外なし／非破壊（チェーン不可）。早期終了あり。
使用例
最小例
<?php
use Illuminate\Support\Collection;
$numbers = collect([10, 20, 30]);
var_dump($numbers->contains(20)); // true（値一致）
var_dump($numbers->contains(25)); // false
$users = collect([
['id' => 1, 'status' => 'active', 'age' => 21],
['id' => 2, 'status' => 'inactive','age' => 17],
]);
var_dump($users->contains('status', 'active')); // true（key=value）
var_dump($users->contains('age', '>=', 18)); // true（演算子）
var_dump($users->contains(fn ($u) => $u['id'] === 3)); // false（コールバック）
実務例（Eloquent 結果の確認）
<?php
use App\Models\User;
use Illuminate\Support\Carbon;
$users = User::query()
->select(['id', 'email', 'last_login_at', 'is_admin'])
->get();
// 1) 管理者が最低1人いるか
if (! $users->contains('is_admin', true)) {
// アラートや初期化処理
}
// 2) 30日以上ログインなしのユーザーがいるか（任意ロジック）
$thirtyDaysAgo = Carbon::now()->subDays(30);
$hasDormant = $users->contains(function ($user) use ($thirtyDaysAgo) {
return $user->last_login_at === null || $user->last_login_at->lt($thirtyDaysAgo);
});
// 3) 指定IDが含まれているか（型を厳密にしたい場合は containsStrict も検討）
$targetId = 123;
$included = $users->contains('id', $targetId);
よくある落とし穴・注意
- ゆるい比較が既定：
contains(0)は'0'やfalseでも一致し得ます。厳密比較が必要ならcontains('key','===',value)かcontainsStrictを使用。 - 演算子の種類：
likeや正規表現は非対応。コールバックで記述してください。 - 計算量：線形探索 O(n)。巨大コレクションでは先に
keyでpluckしてからin_array相当で判定するなど最適化を検討。 - Eloquent の属性アクセス：アクセサ等で型変換されるため、比較の厳密性が必要なら
===やcontainsStrictを。 - LazyCollection：対応可。短絡評価で一致したら停止するためストリーム処理と相性良。
代替・関連APIとの比較
- containsStrict：厳密比較（
===）で一致判定。型の取り違えを防ぎたいときに最優先。 - has / hasAny：コレクションのキー（連想キー）存在判定。値の探索ではない点に注意。
- where / filter：一致する要素の抽出。件数や実体が欲しいときに使い、存在確認だけなら
containsが軽い。 - PHP
in_array：単純配列の値存在確認に速いが、key=valueや演算子・コールバック比較は不可。
テスト例（Pest）
<?php
use Illuminate\Support\Collection;
it('checks presence by key and operator', function () {
$c = collect([
['age' => 16],
['age' => 20],
]);
expect($c->contains('age', '>=', 18))->toBeTrue();
expect($c->contains('age', '>=', 30))->toBeFalse();
});
it('uses strict comparison when needed', function () {
$c = collect(['0', 1, 2]);
expect($c->containsStrict(0))->toBeFalse(); // '0' と 0 は別
});
トラブルシュート（エラー別）
| 症状/エラー | 原因 | 対処 |
|---|---|---|
想定外に true になる | 既定がゆるい比較（==）で型が一致していない | containsStrict か === 演算子の3引数形式を使用 |
like 相当の部分一致を判定したい | contains の演算子は限定的 | コールバックで Str::contains() や preg_match を使用 |
| 重い/遅い | 大量データで毎回線形探索 | 事前に pluck('id') して contains、もしくは DB 側で存在確認 (exists()） |
コレクション特性（カテゴリ追記）
- チェーン可否：不可（
boolで終了） - 破壊的/非破壊：非破壊
- キー保持：N/A（値探索）
- LazyCollection：対応（短絡評価）
- 計算量：O(n)
入出力対応（小サンプル）
| 入力 | 呼び出し | 出力 |
|---|---|---|
[10,20,30] | contains(20) | true |
[['age'=>16],['age'=>20]] | contains('age','>=',18) | true |
[['name'=>'Ann'],['name'=>'Bob']] | contains(fn($x)=>str_starts_with($x['name'],'A')) | true |
参考リンク
- Laravel公式ドキュメント：Collections「contains」
https://laravel.com/docs/collections#method-contains - Laravel公式ドキュメント：Collections「containsStrict」
https://laravel.com/docs/collections#method-containsstrict - ソースコード（Collection）
https://github.com/laravel/framework/blob/12.x/src/Illuminate/Support/Collection.php
