PHP array_find_key() Function: Usage and Examples

Sometimes you need to find the position or key of an array element that meets a specific condition. For example, you might want to locate the first available product, identify an unanswered question, or find a support ticket requiring attention.

PHP provides the array_find_key() function to perform these searches without writing a separate loop.

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

What Is array_find_key() in PHP?

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

Its syntax is:

array_find_key(
    array $array,
    callable $callback
): int|string|null

It accepts two parameters:

• $array — The array to search.
• $callback — A function that checks each element and determines whether it matches.

The callback receives the element's value first and its key second.

When a match is found, PHP returns the corresponding integer or string key. If no element matches, the result is null.

Example 1: Finding a Numeric Array Key

Let's find the index of the first number greater than 20.

<?php

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

$key = array_find_key(
    $numbers,
    fn(int $number): bool => $number > 20
);

var_dump($key);

Output:

int(2)

The first matching number is 28, which has the array key 2.

Unlike array_find(), which returns the matching value, array_find_key() returns its key.

You can use that key to retrieve the value:

if ($key !== null) {
    echo $numbers[$key];
}

Output:

28

Example 2: Searching Associative Arrays

The function also works with associative arrays containing named keys.

<?php

$stock = [
    "Keyboard" => 0,
    "Mouse" => 7,
    "Monitor" => 4
];

$key = array_find_key(
    $stock,
    fn(int $quantity, string $product): bool =>
        $quantity > 0 &&
        str_starts_with($product, "M")
);

var_dump($key);

Output:

string(5) "Mouse"

The callback checks both the stock quantity and the product name.

Since Mouse is the first product matching both conditions, its key is returned.

PHP stops searching immediately after finding a match. Later elements are not checked.

What Happens When No Match Is Found?

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

<?php

$numbers = [10, 20, 30];

$key = array_find_key(
    $numbers,
    fn(int $number): bool => $number > 100
);

var_dump($key);

Output:

NULL

An empty array also returns null.

Always use a strict check such as $key !== null to determine whether a match was found.

This is important because 0 is a valid array key. Checking if ($key) would incorrectly treat a match at index zero as a failed search.

Finding Elements That Contain null

One advantage of array_find_key() is that it can distinguish a missing result from an element whose value is null.

<?php

$answers = [
    "question1" => "A",
    "question2" => null,
    "question3" => "C"
];

$key = array_find_key(
    $answers,
    fn($answer): bool => $answer === null
);

echo $key;

Output:

question2

The function finds the unanswered question and returns its key. Because PHP array keys cannot be null, a returned null always means no match was found.

Practical Example: Finding a Support Ticket That Needs Attention

Imagine you're developing a helpdesk application. Each ticket has a unique ID, priority, status, and subject.

We want to find the first ticket that has high priority and is still open.

Create a file named find-ticket.php:

<?php

declare(strict_types=1);

$tickets = [
    "SUP-101" => [
        "subject" => "Password reset",
        "priority" => "low",
        "status" => "open"
    ],
    "SUP-102" => [
        "subject" => "Server offline",
        "priority" => "high",
        "status" => "open"
    ],
    "SUP-103" => [
        "subject" => "Disk warning",
        "priority" => "high",
        "status" => "resolved"
    ]
];

// Find the first high-priority open ticket.

$ticketId = array_find_key(
    $tickets,
    static fn(array $ticket): bool =>
        $ticket["priority"] === "high"
        && $ticket["status"] === "open"
);

if ($ticketId !== null) {

    $ticket = $tickets[$ticketId];

    $message = $ticketId
        . " - "
        . $ticket["subject"];

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

} else {

    echo "No high-priority open tickets found.";
}

Browser output:

SUP-102 - Server offline

The function returns the ticket ID rather than the complete ticket record. We then use that ID to access the matching ticket.

Remember: The function searches in array iteration order. It does not automatically sort tickets by priority or creation time.

array_find_key() vs Related Functions

Use array_find_key() when your search requires a custom condition and you need the matching key. Use array_search() when you're looking for a particular value.

Using PHP Versions Earlier Than 8.4

For PHP 8.3 or earlier, you can reproduce the basic behavior using foreach:

<?php

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

$foundKey = null;

foreach ($numbers as $key => $value) {

    if ($value > 20) {
        $foundKey = $key;
        break;
    }
}

var_dump($foundKey);

Output:

int(2)

The loop stops after finding the first matching element, just like array_find_key().

Key Takeaways

• array_find_key() was introduced in PHP 8.4.
• It returns the key of the first element that satisfies a callback condition.
• The callback receives the value first and the key second.
• Both integer and string keys are supported.
• The search stops after the first match.
• The function returns null when no match exists.
• Use !== null to check the result correctly, including matches at index zero.

The array_find_key() function is a convenient way to locate matching array keys without writing manual loops. It's especially useful when working with associative records, identifying specific entries, and retrieving data by its original key.

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