contains — コレクションに値/条件が含まれるか判定する

カテゴリ: collection
掲載バージョン: Laravel 12・PHP 8.4
名前空間 / FQCN / コマンド: Illuminate\Support\Collection::contains
関連: containsStrict / containsOneItem / has / where / filter
変更履歴: —

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

要点（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