PHP array_first() Function: Usage and Examples

When working with PHP arrays, you may need to retrieve the first element without knowing its key. This is particularly useful when working with associative arrays or arrays whose numeric indexes are not sequential.

The array_first() function provides a simple way to retrieve the first value without manually accessing an array key.

PHP version requirement: array_first() was introduced in PHP 8.5.

What Is array_first() in PHP?

The array_first() function returns the value of the first element in an array.

Its syntax is:

array_first(array $array): mixed

The function accepts one parameter, $array, and returns:

• The first element's value if the array contains elements.
• null if the array is empty.

The return type is mixed because the first value can be a string, number, boolean, array, object, or another PHP type.

The original array remains unchanged.

Example 1: Getting the First Value

Let's retrieve the first programming language from an indexed array.

<?php

$languages = ["PHP", "Python", "JavaScript"];

$first = array_first($languages);

echo $first;

Output:

PHP

The function returns "PHP" because it is the first element in the array.

Unlike array_find(), array_first() does not accept a callback or test a condition. It simply retrieves the first value.

Example 2: Working with Associative Arrays

The function also works with associative arrays, where keys are strings or non-sequential integers.

<?php

$products = [
    20 => "Keyboard",
    5 => "Mouse",
    12 => "Monitor"
];

echo array_first($products);

Output:

Keyboard

The first value is "Keyboard", even though its key is 20.

Important: PHP arrays maintain an element order. The first element is not necessarily the one with the lowest numeric key or the first alphabetical key.

If the array is sorted or reordered, its first value may change.

Handling Empty Arrays and null Values

When the input array is empty, array_first() returns null.

<?php

$items = [];

var_dump(array_first($items));

Output:

NULL

However, null can also be a valid first value:

<?php

$items = [null, "Ready"];

var_dump(array_first($items));

This also outputs NULL.

If your application needs to distinguish between an empty array and an array whose first value is null, check whether the array is empty before retrieving the value.

if ($items !== []) {
    $first = array_first($items);
}

Practical Example: Displaying the First Available Product

Imagine you're building an online store. You have a list of products and want to display the first product that is currently in stock.

You can combine array_filter() with array_first() to accomplish this.

Create a file named first-product.php:

<?php

declare(strict_types=1);

$products = [
    "KB-101" => [
        "name" => "Keyboard",
        "stock" => 0
    ],
    "MS-102" => [
        "name" => "Mouse",
        "stock" => 6
    ],
    "HD-103" => [
        "name" => "Headset",
        "stock" => 3
    ]
];

// Keep products that are in stock.

$available = array_filter(
    $products,
    static fn(array $product): bool =>
        $product["stock"] > 0
);

// Retrieve the first available product.

$firstProduct = array_first($available);

if ($firstProduct !== null) {

    $message = $firstProduct["name"]
        . " - "
        . $firstProduct["stock"]
        . " in stock";

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

} else {

    echo "No products available.";
}

Browser output:

Mouse - 6 in stock

The Keyboard is excluded because its stock quantity is zero. The Mouse becomes the first element of the filtered array.

Notice that array_filter() preserves original keys. The array_first() function retrieves the first value regardless of those keys.

This combination works well when you need the first result from a filtered collection.

array_first() vs Related Functions

Unlike reset(), array_first() does not change the array's internal pointer.

Also, remember that array_first() returns a value, not its corresponding key.

Using PHP Versions Earlier Than 8.5

If you're using PHP 7.3 through PHP 8.4, you can achieve the same basic behavior with array_key_first():

<?php

$colors = [
    "primary" => "Blue",
    "secondary" => "Green"
];

$first = $colors === []
    ? null
    : $colors[array_key_first($colors)];

var_dump($first);

Output:

string(4) "Blue"

This approach first retrieves the key of the first element, then uses it to access the corresponding value. The empty-array check prevents an invalid lookup.

Key Takeaways

• array_first() was introduced in PHP 8.5.
• It returns the first value from an indexed or associative array.
• The first element is determined by array order, not by its key.
• An empty array returns null.
• The function does not modify the array or its internal pointer.
• Use array_key_first() when you need the first key instead of the value.
• For older PHP versions, combine array_key_first() with an array lookup.

The array_first() function provides a straightforward way to access the first value of a PHP array. It is especially useful when working with associative arrays, filtered collections, and data structures whose keys are not sequential.

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