{
    "slug": "php84_array_find",
    "term": "array_find() / array_find_key() (PHP 8.4)",
    "category": "php",
    "difficulty": "beginner",
    "short": "PHP 8.4 adds array_find() and array_find_key() — built-in functions that return the first element (or key) matching a callback predicate, replacing verbose foreach loops or array_filter() + reset() patterns.",
    "long": "Finding the first matching element in an array was always awkward in PHP — either a foreach with a break, or array_filter() which returns all matches followed by reset() or current() to grab the first. PHP 8.4 adds four related functions: array_find() returns the first value where the callback returns true, array_find_key() returns its key, array_any() returns true if any element matches, and array_all() returns true if all elements match. These mirror JavaScript's Array.find(), Array.findIndex(), Array.some(), and Array.every(). All four short-circuit — they stop iterating as soon as the result is determined.",
    "aliases": [
        "array_find",
        "array_find_key",
        "array_any",
        "array_all",
        "PHP 8.4 arrays"
    ],
    "tags": [
        "php8.4",
        "arrays",
        "functional",
        "php-stdlib"
    ],
    "misconception": "array_find() returns an array of matches like array_filter(). It returns only the first matching value (or null if none match). For all matches, use array_filter().",
    "why_it_matters": "These functions make intent clearer and eliminate boilerplate. A foreach-with-break for 'find first matching' is four to six lines of code with a mutable variable; array_find() expresses the same intent in one line. array_any() and array_all() replace common patterns like 'count(array_filter(...)) > 0' with readable, short-circuiting alternatives.",
    "common_mistakes": [
        "Expecting array_find() to return false on no match like reset() — it returns null, so check with '=== null' not '=== false'.",
        "Using array_find() when you need all matches — use array_filter() for multiple results.",
        "Forgetting array_any() and array_all() exist — 'count(array_filter(...)) > 0' is a common pattern these replace cleanly.",
        "Using these functions in PHP < 8.4 — they are not available; polyfill with a helper function or upgrade."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "php8",
        "array_functions",
        "php_array_functions_fp",
        "arrow_functions"
    ],
    "prerequisites": [],
    "refs": [
        "https://www.php.net/releases/8.4/en.php",
        "https://wiki.php.net/rfc/array_find"
    ],
    "bad_code": "<?php\n// ❌ Verbose first-match patterns\n$firstAdmin = null;\nforeach ($users as $user) {\n    if ($user['role'] === 'admin') {\n        $firstAdmin = $user;\n        break;\n    }\n}\n\n// Or the filter+reset hack\n$admins = array_filter($users, fn($u) => $u['role'] === 'admin');\n$firstAdmin = reset($admins); // false if empty, not null",
    "good_code": "<?php\n// ✅ PHP 8.4 — clean, intent-revealing\n$firstAdmin = array_find($users, fn($u) => $u['role'] === 'admin');\n// Returns null if not found (not false)\n\n$adminKey = array_find_key($users, fn($u) => $u['role'] === 'admin');\n\n$hasAdmin  = array_any($users, fn($u) => $u['role'] === 'admin');\n$allActive = array_all($users, fn($u) => $u['active'] === true);\n\n// Null-safe chaining when element may not exist\n$email = array_find($users, fn($u) => $u['id'] === 42)?->email;",
    "quick_fix": "Replace 'foreach ($arr as $v) { if ($cond) { $found = $v; break; } }' with '$found = array_find($arr, fn($v) => $cond);'",
    "effort": "low",
    "created": "2026-03-23",
    "updated": "2026-03-23",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/php84_array_find",
        "html_url": "https://codeclaritylab.com/glossary/php84_array_find",
        "json_url": "https://codeclaritylab.com/glossary/php84_array_find.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[array_find() / array_find_key() (PHP 8.4)](https://codeclaritylab.com/glossary/php84_array_find) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/php84_array_find"
            }
        }
    }
}