PHP array_find() Function: Usage and Examples

When working with PHP arrays, you sometimes need to find the first element that meets a specific condition. For example, you might want to find an available product, locate a user with a particular role, or identify the first number above a limit.

The array_find() function makes these searches easier without requiring a separate loop.

PHP version requirement: array_find() was introduced in PHP 8.4.

What Is array_find() in PHP?

The array_find() function searches an array and returns the value of the first element that satisfies a callback condition.

Its syntax is:

array_find(array $array, callable $callback): mixed

It accepts two arguments:

• $array — The array to search.
• $callback — A function that checks each element and returns a boolean result.

The callback receives the current element's value and its key. You can omit the key parameter when it isn't needed.

If an element matches, its value is returned immediately. If no element matches, the function returns null.

Example 1: Finding the First Matching Number

Let's find the first number greater than 20.

<?php

$numbers = [5, 12, 28, 35, 40];

$result = array_find(
    $numbers,
    fn(int $number): bool => $number > 20
);

var_dump($result);

Output:

int(28)

The function checks the numbers in array order. It returns 28 because that is the first value greater than 20.

Although 35 and 40 also match, they aren't examined after the first match is found. This behavior is called short-circuit evaluation.

Example 2: Searching Associative Arrays

You can also use an element's key when defining a search condition.

<?php

$temperatures = [
    "London" => 18,
    "Paris" => 24,
    "Rome" => 31
];

$result = array_find(
    $temperatures,
    fn(int $temperature, string $city): bool =>
        $city === "Rome" && $temperature > 30
);

var_dump($result);

Output:

int(31)

The callback receives the value first ($temperature) and the key second ($city).

Notice that array_find() returns the matching value, not its key. To retrieve the key instead, PHP 8.4 provides array_find_key().

What Happens When No Match Is Found?

If no element satisfies the callback condition, array_find() returns null.

<?php

$numbers = [4, 8, 12];

$result = array_find(
    $numbers,
    fn(int $number): bool => $number > 100
);

var_dump($result);

Output:

NULL

An empty input array also returns null because there are no elements to check.

Important: If null is a valid matching value, the result cannot distinguish between finding that value and finding nothing. Use array_find_key() when you need to distinguish those cases.

Practical Example: Finding an Available Product

Imagine you're developing an online store and want to recommend the first active product that costs $50 or less.

Create a file named find-product.php:

<?php

declare(strict_types=1);

$products = [
    [
        "name" => "Keyboard",
        "price" => 79,
        "active" => true
    ],
    [
        "name" => "Mouse",
        "price" => 25,
        "active" => true
    ],
    [
        "name" => "Headphones",
        "price" => 40,
        "active" => true
    ]
];

$maxPrice = 50;

// Find the first matching product.

$product = array_find(
    $products,
    static fn(array $item): bool =>
        $item["active"] === true
        && $item["price"] <= $maxPrice
);

// Display the result.

if ($product !== null) {

    $message = "Recommended product: "
        . $product["name"]
        . " ($"
        . $product["price"]
        . ")";

    echo htmlspecialchars(
        $message,
        ENT_QUOTES,
        "UTF-8"
    );

} else {

    echo "No matching products found.";
}

Browser output:

Recommended product: Mouse ($25)

The Keyboard exceeds the price limit, so it is skipped. The Mouse satisfies both conditions and is returned immediately.

The Headphones also meet the requirements, but they are never checked because a matching product was already found.

This example uses predefined product records. Validate external data before searching it with callbacks that expect specific fields and data types.

array_find() vs Related Array Functions

PHP provides several array functions that search or filter data. The appropriate choice depends on what you want returned.

The functions array_find(), array_find_key(), and array_any() were introduced in PHP 8.4.

Use array_find() when you need the actual matching value rather than every matching element or a simple yes-or-no answer.

Using PHP Versions Earlier Than 8.4

On older PHP versions, you can perform an equivalent search using foreach:

<?php

$numbers = [5, 12, 28, 35];

$result = null;

foreach ($numbers as $number) {

    if ($number > 20) {
        $result = $number;
        break;
    }
}

var_dump($result);

Output:

int(28)

The break statement stops the loop as soon as a match is found, reproducing the basic behavior of array_find().

Key Takeaways

• array_find() was introduced in PHP 8.4.
• It returns the value of the first element satisfying a callback condition.
• The callback can inspect both the element's value and its key.
• The search stops immediately after the first match.
• The function returns null when no match is found.
• Use array_find_key() when you need the matching key instead.
• The original array remains unchanged.

The array_find() function provides a readable way to retrieve the first matching element from a PHP array. It is especially useful for searching product records, user lists, and other structured collections without writing repetitive loops.

For additional details, see the official PHP array_find() documentation.