next
Advances an array's internal pointer one position and returns the value found there.
next(array|object &$array): mixed- Added in PHP 4.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$array | array|object | The array whose internal pointer is advanced. Passed by reference. Passing an object is deprecated as of PHP 8.1. |
Return value
mixedThe value at the new pointer position, or false if the pointer has moved past the end of the array.
Errors
Nothing is thrown. Passing an object emits an E_DEPRECATED notice as of PHP 8.1.0.
Changelog
- PHP 8.1Calling this function on objects is deprecated. Convert the object with get_mangled_object_vars() first, or use a class implementing Iterator such as ArrayIterator.
- PHP 7.4Instances of SPL classes are treated like empty objects with no properties instead of calling the Iterator method of the same name.
Every PHP array carries an internal pointer. next moves that pointer forward one slot and returns whatever value is now under it. If the pointer walks off the end, it returns false and stays there — it does not wrap around.
When to reach for it
Manual pointer walking is niche now that foreach exists. It earns its place when you need to consume an array irregularly: a token stream where one branch swallows the following item, a parser reading a line and then peeking at the next, or a state machine that sometimes skips ahead. It also pairs with current and key when you are stepping through data across several function calls instead of in one loop.
What trips people up
The false return is ambiguous. An array element that genuinely holds false, null, 0 or '' reads the same as the end of the array in a while (next($a)) loop, which stops early. Test key($array) !== null to detect the real end.
Because the parameter is by reference, you cannot pass a function's return value or a literal directly — assign it to a variable first. And foreach in PHP 7 and later iterates over its own copy of the pointer, so calling next inside a foreach does not skip an iteration the way it did in PHP 5.
Example
When to use it
- Walk a token list in a small parser where handling one token sometimes consumes the one after it.
- Read a header row with current(), then advance to the first data row before a processing loop.
- Step through a queue array across separate method calls without tracking an index yourself.
Frequently asked questions
What is the difference between next and current?
current() returns the value at the pointer without moving it; next() moves the pointer forward first, then returns the value there. Calling next() on a fresh array therefore gives you the second element.
Does calling next inside a foreach loop skip an element?
No, not since PHP 7. foreach iterates over its own internal position, so moving the array pointer with next() has no effect on the loop.
How do I move the pointer back to the start?
Call reset($array), which rewinds the pointer to the first element and returns its value. end($array) jumps to the last element instead.
More examples
Why while(next()) is a trap
The naive loop prints an empty array: next() returns 10 first, but the very next value is 0, which is falsy, so the while condition ends the loop with 30 still unread. Checking key() !== null is the only reliable end-of-array test, because it cannot confuse a falsy value with the end.
<?php
$values = [10, 0, 30];
// The trap: 0 is falsy, so the loop stops early even though 30 remains.
$naive = [];
while ($v = next($values)) {
$naive[] = $v;
}
print_r($naive);
// key() is null only at the real end of the array.
reset($values);
$safe = [];
while (next($values) !== false || key($values) !== null) {
if (key($values) === null) { break; }
$safe[] = current($values);
}
print_r($safe);Peeking ahead and stepping back
next() advances to 'x' and returns it, then prev() rewinds so current() reports 'SET' again — the standard peek-then-restore pattern for hand-written parsers.
<?php
$tokens = ['SET', 'x', '=', '5'];
reset($tokens);
$cmd = current($tokens);
$peek = next($tokens);
prev($tokens);
echo "command: $cmd\n";
echo "peeked: $peek\n";
echo "back at: ", current($tokens), "\n";
Discussion