next()

Purpose

Every PHP array carries a hidden internal pointer that marks one element as the current one. next() moves that pointer forward by one position and then returns the value now under it. It works like current(), except that current() only reads the value and never moves anything.

This makes next() useful for manual, step-by-step walks through an array, for example when you want to peek at the following item or pull values one at a time from different places in your code. For ordinary loops, foreach is almost always clearer.

Signature

Parameters

• $array: the array whose pointer should move. It is passed by reference, so you must supply a variable. The pointer lives inside that variable, and the call changes it. There is no default value and the argument is required.

Passing an object is deprecated as of PHP 8.1. If you have an object, convert it first with get_mangled_object_vars(), or use a class that implements Iterator, such as ArrayIterator.

Return value and failure cases

next() returns the value at the new pointer position. If the pointer moves past the last element, there is nothing left to return and the function gives false. Once the pointer is beyond the end, further calls keep returning false.

The catch is that false is also a perfectly valid array value. If an element itself is false, next() returns false for it, and you cannot tell that apart from reaching the end by looking at the return value alone. The reliable check is key(): it returns null when the pointer is off the end of the array.

Example 1: stepping forward and back

This shows current(), next() and prev() working with the same pointer.

<?php
$transport = ['foot', 'bike', 'car', 'plane'];
echo current($transport), PHP_EOL;
echo next($transport), PHP_EOL;
echo next($transport), PHP_EOL;
echo prev($transport), PHP_EOL;

foot
bike
car
bike

A new array starts with the pointer on its first element. Each next() call advances one place, and prev() steps back.

Example 2: traversing an array that contains false

When values may be false, test the key as well as the returned value.

<?php
$flags = [true, false, true];
$result = [];
do {
    $result[] = ['key' => key($flags), 'value' => current($flags)];
} while (next($flags) !== false || key($flags) !== null);
echo json_encode($result);

[{"key":0,"value":true},{"key":1,"value":false},{"key":2,"value":true}]

The second element is false, so next() returns false there, yet the loop correctly continues because key() is still 1. At the real end, next() returns false and key() returns null, so the loop stops. Note that this do/while form assumes the array is not empty, because the body runs once before any check.

Example 3: associative arrays and running off the end

<?php
$stock = ['apple' => 3, 'pear' => 0, 'plum' => 5];
$out = [];
$out[] = key($stock);
$out[] = next($stock);
$out[] = key($stock);
$out[] = next($stock);
$out[] = next($stock);
$out[] = key($stock);
echo json_encode($out);

["apple",0,"pear",5,false,null]

next() returns values, never keys, so use key() to learn the name of the current element. After the last element, next() returns false and key() returns null.

Edge cases

• Empty arrays: there is no element to move to, so next() returns false.
• Single-element arrays: the first next() call already goes past the end and returns false.
• Falsy but valid values: 0, '' and null are legitimate values. In Example 3 the value 0 is returned for pear. Comparing with == or using the result as a condition would wrongly treat it as the end, so compare with === false and confirm with key().
• Pointer state is per variable: the pointer is stored with the array value you pass in, so reading it elsewhere requires using the same variable.
• Objects: deprecated since PHP 8.1, as noted above. Do not rely on them.

Common mistakes

1. Treating false as proof of the end. Use key($array) === null when the array might contain false.
2. Using a loose condition such as while ($v = next($a)). This stops early on 0, '', '0', null and false values.
3. Forgetting that next() moves first. If you call it at the start of a loop, you skip the first element, because the pointer already sits on it. Read with current() first, or use reset() to make that position explicit.
4. Passing an expression. Because the parameter is a reference, give it a variable, not a function call result or literal.
5. Assuming the pointer was reset. Earlier calls leave the pointer where it was. Call reset() before a fresh manual traversal.
6. Reaching for it when foreach would do. Manual pointer handling is easy to get subtly wrong.

Related functions

• current(): read the current element without moving.
• key(): get the current key, or null past the end.
• prev(): move the pointer back one place.
• reset(): move the pointer to the first element.
• end(): move the pointer to the last element.

Recap

next() advances an array's internal pointer by one and returns the new current value, or false when no elements remain. Because false can also be a stored value, confirm the end with key() === null. Pass a variable, avoid objects, and prefer foreach unless you truly need manual control.