head
Return the first element of an array, or false when the array is empty.
head(array $array): mixedParameters
| Parameter | Type | Description |
|---|---|---|
$array | array | The array to read from. Passed by value, so the caller's internal array pointer is not moved. |
Return value
mixedThe first element of the array in insertion order, or false when the array is empty.
Errors
Throws a TypeError when given anything that is not an array, including a Collection or an ArrayAccess object.
head() returns the first element of an array in insertion order. Keys are irrelevant — it does not look for key 0, it takes whatever element comes first, which makes it correct for filtered arrays and string-keyed arrays where $array[0] would fail.
Why it exists
The docblock says "useful for method chaining", and that is the point: PHP's own reset() requires a variable it can take by reference, so reset(array_filter($rows)) is not valid in older PHP and reads badly in any version. head(array_filter($rows)) works on any expression.
By value, not by reference
Unlike reset(), head() receives a copy, so the caller's internal array pointer is untouched. Two consecutive head() calls return the same element; two consecutive reset()/next() sequences do not.
The false return
An empty array yields false, not null. That is ambiguous whenever the array might legitimately contain false, 0 or ''. When the distinction matters, check the array first, or use collect($array)->first(), which returns null and accepts a default.
Arrays only
Passing a Collection, a generator or an ArrayAccess object raises a TypeError. Call ->first() on a Collection instead.
Example
When to use it
- Take the first row of a filtered array without assigning it to a variable first.
- Read the first value of a string-keyed array where $array[0] does not exist.
- Pull the first match out of a preg_grep or array_filter result inline.
Frequently asked questions
What is the difference between head() and reset()?
head() takes the array by value, so it does not move the caller's internal array pointer and can be applied to any expression, including a function's return value. reset() needs a variable it can reference and leaves the pointer on the first element.
Why does head() return false instead of null for an empty array?
It mirrors reset(), which returns false when there is nothing to return. That makes an empty array indistinguishable from an array whose first element is false, 0 or '' — use collect($array)->first() when you need null or a default.
Can I call head() on a Collection?
No, it raises a TypeError because the parameter must be an array. Use the Collection's own ->first() method, which additionally accepts a truth-test closure and a default value.
More examples
Where $array[0] would fail
This is the classic bug head() avoids: array_filter keeps the original keys, so the filtered array has no index 0 and $published[0] raises an undefined-key warning. head() reads the first element regardless of its key.
<?php
$rows = [
['id' => 10, 'status' => 'draft'],
['id' => 11, 'status' => 'published'],
['id' => 12, 'status' => 'published'],
];
// array_filter preserves keys, so the result starts at index 1.
$published = array_filter($rows, fn ($r) => $r['status'] === 'published');
var_dump(array_key_exists(0, $published)); // bool(false)
print_r(head($published));
// Array ( [id] => 11 [status] => published )The ambiguous false
Both head() calls return false for entirely different reasons. Collection::first() distinguishes them by returning null for an empty source and accepting a default, which is why it is the safer choice for data that may contain falsy values.
<?php
$flags = [false, true];
$none = [];
var_dump(head($flags)); // bool(false) - a real stored value
var_dump(head($none)); // bool(false) - the empty-array signal
// Indistinguishable. Check the array, or use a Collection.
var_dump(collect($flags)->first()); // bool(false)
var_dump(collect($none)->first()); // NULL
var_dump(collect($none)->first(null, 'n/a')); // string(3) "n/a"Arrays only
head() is an array-only helper — a Collection, generator or ArrayAccess object raises a TypeError. Either call ->first() on the Collection or unwrap it with ->all() before passing it in.
<?php
var_dump(head(['a', 'b']));
// string(1) "a"
try {
head(collect(['a', 'b']));
} catch (\TypeError $e) {
echo 'TypeError: head() does not accept a Collection', "\n";
}
// Use the Collection's own method instead.
var_dump(collect(['a', 'b'])->first());
// string(1) "a"
// Or unwrap first.
var_dump(head(collect(['a', 'b'])->all()));
// string(1) "a"
Discussion