- 条件に合う最初の1件(要素)を取得するなら、PHP 8.4新設の
array_find($array, $callback)を使うのが最も安全かつ高速 - 従来の
array_filter($array, ...)[0]は元の配列キーが保持されるためUndefined array key 0の原因になり、さらに末尾まで全件走査してしまう - 存在判定には
array_any()、全件一致判定にはarray_all()を使い分けることで、foreachとフラグ変数のボイラープレートを排除できる
1. 発生する症状・やりたいこと(前提条件)
APIレスポンスやDBから取得した連想配列のリストから、「特定のIDや条件に一致する最初の1件だけを取り出したい」「条件を満たす要素が1つでもあるか判定したい」という場面は実務で頻出します。
- ユーザーや商品一覧の配列から、条件に一致する最初の要素(またはキー)を1件だけ取得したい
array_filter()の結果に添字[0]でアクセスしてWarning: Undefined array key 0が発生する事故を防ぎたい- 数万件の配列でも、一致した時点で即座にループを抜ける(短絡評価)省メモリ・高速なコードを書きたい
// 従来の array_filter($users, ...)[0] で頻発する警告
Warning: Undefined array key 0 in /app/src/UserService.php on line 18
// 期待する動作:一致した最初の要素(連想配列)を直接返し、未一致なら null を返す
['id' => 102, 'name' => 'Sato', 'role' => 'admin', 'active' => true]
2. ❌ やりがちなNGコード vs ⭕ 実務で使える正解コード
<?php
$users = [
['id' => 101, 'name' => 'Tanaka', 'role' => 'editor'],
['id' => 102, 'name' => 'Sato', 'role' => 'admin'],
['id' => 103, 'name' => 'Suzuki', 'role' => 'admin'],
];
// ❌ 2番目(添字1)がヒットするため、キー [1] が保持され [0] は存在しない!
$admin = array_filter($users, fn(array $u): bool => $u['role'] === 'admin')[0];
// Warning: Undefined array key 0 (さらに102番で見つかっても最後まで全件走査される)
array_filter() は元の配列キー(この例では添字 1 と 2)を維持するため、[0] で参照すると Undefined array key 0 が発生します。また reset() を使う場合も未一致時に false が返るうえ、最初の1件が見つかっても配列末尾まで全件走査が続いてしまいます。
<?php
declare(strict_types=1);
$users = [
['id' => 101, 'name' => 'Tanaka', 'role' => 'editor', 'active' => true],
['id' => 102, 'name' => 'Sato', 'role' => 'admin', 'active' => true],
['id' => 103, 'name' => 'Suzuki', 'role' => 'admin', 'active' => false],
];
// 1. 最初に一致した「要素(値)」を取得(見つからない場合は null)
// ※コールバック引数は ($value, $key) の順。一致した時点で即座に走査終了(短絡評価)
$firstAdmin = array_find(
$users,
static fn(array $user, int|string $key): bool => $user['role'] === 'admin' && $user['active']
);
// 結果: ['id' => 102, 'name' => 'Sato', 'role' => 'admin', 'active' => true]
// 2. 最初に一致した「配列キー(添字)」を取得(見つからない場合は null)
$adminIndex = array_find_key(
$users,
static fn(array $user): bool => $user['id'] === 102
); // 結果: 1
// 3. 条件を満たす要素が「1件でも存在するか」を真偽値で判定
$hasInactiveAdmin = array_any(
$users,
static fn(array $user): bool => $user['role'] === 'admin' && !$user['active']
); // 結果: true
// 4. 「すべての要素」が条件を満たしているかを真偽値で判定
$allActive = array_all(
$users,
static fn(array $user): bool => $user['active'] === true
); // 結果: false
3. 仕様・使い分けの比較早見表
PHP 8.4で追加された array_find 系4関数と、従来の配列検索関数の戻り値・走査範囲(短絡評価の有無)の比較一覧です。
| 関数名(対応バージョン) | 一致時の戻り値 / 未一致時 | 短絡評価(途中終了) | おすすめな実務シーン |
|---|---|---|---|
array_find()PHP 8.4+ |
最初の要素(mixed)未一致: null |
⭕ あり(1件目で即終了) | 連想配列のリストから条件に合う最初の1件を取り出すとき |
array_find_key()PHP 8.4+ |
最初のキー(int|string)未一致: null |
⭕ あり(1件目で即終了) | 条件に合う要素のインデックスや連想キーを特定して更新・削除するとき |
array_any()PHP 8.4+ |
true / false(空配列は false) |
⭕ あり(true で即終了) |
「在庫切れの商品が1つでも含まれるか」などの存在チェック |
array_all()PHP 8.4+ |
true / false(空配列は true) |
⭕ あり(false で即終了) |
「全明細が承認済みステータスか」などの一括バリデーション |
array_filter()PHP 4.0+ |
一致した全要素の配列 未一致: [](空配列) |
❌ なし(常に全件走査) | 条件に合う要素を複数件すべて抽出して一覧表示するとき |
in_array($v, $a, true)PHP 4.0+ |
true / false |
⭕ あり(C言語実装で高速) | コールバック不要な一次元配列の単純な値一致を判定するとき |
4. 実務でハマりやすい3つの注意点
array_find() は未一致時に null を返しますが、一致した要素の値自体が null だった場合も null が返るため両者を区別できません。要素の値として null を取り得る配列を検索する場合は、array_find_key() !== null で判定してからキー指定で値を取得するのが安全です。
array_any([], $fn) は直感通り false を返しますが、array_all([], $fn) は論理学上の空真(反例が1つも存在しない)に基づき true を返します。注文明細などの空チェックを省いて array_all($items, $fn) だけを通すと0件データが「すべて正常」と判定されるため、必ず $items !== [] && array_all($items, $fn) と組み合わせましょう。
array_filter() には第3引数に ARRAY_FILTER_USE_KEY などのフラグがありますが、array_find 系4関数にはモード定数がなく、常に第1引数が $value、第2引数が $key の順で渡されます。キーのみを使って判定したい場合でも fn(mixed $_, int|string $key): bool => ... のように第1引数を受け取る形で記述してください。
5. よくある質問(FAQ)
Q. PHP 8.3以前の環境で array_find と同じ処理を安全に書くにはどうすればいいですか?
array_filter() は全件走査してしまうため、小規模なヘルパー関数に切り出して foreach で最初の1件が見つかった瞬間に return $item;(ループ終了後は return null;)とするか、Composerで symfony/polyfill-php84 を導入するのが最適です。ポリフィルを使えばPHP 8.4へアップグレードした際もコードを書き換えずにそのままネイティブ関数へ移行できます。
Q. Laravelの Arr::first() や Collection::first() との違いは何ですか?
Laravelの Arr::first($array, $callback) と用途はほぼ同じですが、array_find() はPHP本体のC言語実装(標準関数)であるため、フレームワーク非依存かつ関数呼び出しのオーバーヘッドが最小限です。なお Arr::first() は第3引数で未一致時のデフォルト値を渡せますが、array_find() は常に null を返すため array_find($items, $fn) ?? $default のようにNull合体演算子と組み合わせます。
Q. Generator(yield)や ArrayIterator などの Traversable オブジェクトも渡せますか?
いいえ、array_find() 系4関数の第1引数は array 型のみを受け付け、Iterator や Generator を渡すと TypeError がスローされます。イテレータやストリームに対して短絡検索を行いたい場合は、従来通り foreach ループで回して条件一致時に break または return してください。