array_key_first()

Purpose

array_key_first() tells you which key sits at the beginning of an array. PHP arrays are ordered maps, so "first" means the first element in the array's current order, which is normally the order in which the elements were inserted. The function reads that key and nothing else. It does not return the value, and it does not move the internal array pointer.

Before this function existed, developers often reached for reset() plus key(), or called array_keys() and took element zero. The first approach disturbs the pointer, and the second builds a whole new array just to read one item. array_key_first() avoids both problems.

Signature

Parameters and defaults

• $array: the array to inspect. It is required and has no default. The array is not modified.

Return value and failure cases

The function returns the first key as an int or a string, because those are the only key types a PHP array can hold. If the array is empty, it returns null.

The function has no error return value. If you pass something that is not an array, such as null or a string, PHP throws a TypeError. Always pass a real array, or check with is_array() first when the input comes from outside your code.

Example 1: basic usage

With a string-keyed array, the result is a string.

<?php
$array = ['a' => 1, 'b' => 2, 'c' => 3];

$firstKey = array_key_first($array);

var_dump($firstKey);

string(1) "a"

The var_dump() output shows the exact type and length of the key, which is useful when you are unsure whether you have an integer or a string.

Example 2: integer keys and empty arrays

The first key is not necessarily 0. It is whichever key was placed first.

<?php
$queue = [5 => 'email', 2 => 'sms', 9 => 'push'];
$empty = [];

echo json_encode([
    'queue' => array_key_first($queue),
    'empty' => array_key_first($empty),
], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), "\n";

{"queue":5,"empty":null}

The key 5 comes back because it was inserted first, even though 2 is numerically smaller. The empty array gives null.

Example 3: the internal pointer stays put

The documentation stresses that the internal pointer is unaffected. This example moves the pointer forward first, then asks for the first key.

<?php
$items = ['x' => null, 'y' => 'second', 'z' => 'third'];

next($items);

$first = array_key_first($items);

echo json_encode([
    'first' => $first,
    'value' => $items[$first],
    'current' => current($items),
], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), "\n";

{"first":"x","value":null,"current":"second"}

After next(), current() still reports second, so the call to array_key_first() left the pointer where it was. Notice also that the value stored under the first key is null. The key exists even though its value is null.

Edge cases

• Empty array: returns null, never false or an empty string.
• A null value is not an empty array: ['x' => null] has the first key 'x'. Only the key decides the result.
• Numeric string keys: a key written as '10' is stored by PHP as the integer 10, so you get an int back. A key like '010' stays a string.
• Order matters: after sorting functions such as ksort() or asort(), the first key changes because the order changed. Removing the first element with unset() makes the next element the first.
• Keys can be falsy: 0 and '' are valid keys, so a plain truthiness test can mislead you.

Common mistakes

1. Testing the result with if ($key). A first key of 0 or '' is falsy. Use $key === null to detect an empty array.
2. Expecting the value. The function returns a key. To read the value, index the array with that key, but only after confirming the result is not null.
3. Assuming the first key is 0. This holds only for lists built in the usual way. Filtered or re-keyed arrays often start elsewhere.
4. Passing a non-array. A null from an earlier lookup raises a TypeError. Validate input first.
5. Using reset() just to peek. That moves the pointer and can surprise code that iterates with current() and next().

Related functions

• array_key_last() returns the last key in the same way.
• array_keys() returns every key as a list.
• array_key_exists() checks whether a specific key is present.
• reset() moves the internal pointer to the first element and returns its value.
• key() returns the key at the current pointer position.

Recap

array_key_first() returns the first key of an array as an int or string, or null when the array is empty. It leaves the array and its internal pointer untouched. Compare the result strictly with null, remember that the first key depends on element order rather than numeric value, and pass only arrays to avoid a TypeError.