💡 忙しい人のための結論(3行まとめ)
  • 条件に合う最初の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 ⭕ 実務で使える正解コード

❌ やりがちなNGコード(バグ・警告の原因)Before
<?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 8.4 / 8.3+Polyfill対応)After
<?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つの注意点

1配列の値自体に null が含まれる場合は array_find_key() を使う

array_find() は未一致時に null を返しますが、一致した要素の値自体が null だった場合も null が返るため両者を区別できません。要素の値として null を取り得る配列を検索する場合は、array_find_key() !== null で判定してからキー指定で値を取得するのが安全です。

2空配列 [] に対する array_all() の戻り値は true(空真)になる

array_any([], $fn) は直感通り false を返しますが、array_all([], $fn) は論理学上の空真(反例が1つも存在しない)に基づき true を返します。注文明細などの空チェックを省いて array_all($items, $fn) だけを通すと0件データが「すべて正常」と判定されるため、必ず $items !== [] && array_all($items, $fn) と組み合わせましょう。

3コールバック引数は常に ($value, $key) 固定でモード定数は存在しない

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 してください。