pos()

In PHP, the pos() function is a built-in array function that returns the value of the element at the array's internal pointer position. Every PHP array carries an internal pointer that tracks which element is "current"; pos() reads the value sitting under that pointer without moving it.

pos() is an alias of current(), and the two behave identically. Because aliases can be discouraged or removed in future PHP versions, current() is the name you should prefer in new code — pos() is documented here mainly so you recognise it in legacy projects.

This page covers the function's syntax, what it returns (including the empty-array edge case), how it relates to the other pointer functions, and when reaching for the pointer is the right choice at all.

Syntax of the pos() Function

pos() takes a single argument — the array to inspect — and returns the value of the element the internal pointer currently points to.

pos(array $array): mixed

• $array — the array to read from. It is passed by reference, so the array variable must be assignable (you cannot pass a literal).
• Return value — the value of the current element, or false if the array is empty or the pointer has moved past the last element.

Because an element can legitimately hold the value false, never use the return value alone to test "did this fail?". Use key() (which returns null past the end) when you need to detect the end of an array reliably.

Example Usage of the pos() Function

Let's take a look at some practical examples of how the pos() function can be used to retrieve the value at the internal pointer's current position.

Example Usage of the pos() Function

<?php

$colors = ['red', 'green', 'blue'];

// Set the current position to the first element
reset($colors);

// Retrieve the value of the element at the current position
echo pos($colors) . '-'; // Output: red

// Move the current position to the next element
next($colors);

// Retrieve the value of the element at the current position
echo pos($colors) . '-'; // Output: green

// Move the current position to the next element
next($colors);

// Retrieve the value of the element at the current position
echo pos($colors); // Output: blue

In this example, we have an array called $colors, which contains three elements. We set the internal pointer to the first element using reset() and then retrieve the value at that position using pos(). We then advance the pointer with next() and read the value again, repeating once more to reach the last element. The key point: pos() itself never moves the pointer — only reset(), next(), prev(), and end() do.

Reading past the end

Once the pointer is advanced beyond the final element, pos() returns false. This is why false is ambiguous as a "current value" — it can mean either "the element is false" or "we ran off the end":

When you genuinely need to know whether you have reached the end, pair pos() with key(): key() returns null past the last element, while a real key (0, 1, …) means the pointer is still valid.

pos() and the Other Pointer Functions

pos() is one piece of PHP's internal-pointer toolkit. Each function plays a distinct role:

When to Use the Internal Pointer

For most array traversal, a foreach loop is clearer and safer — it does not touch the array's internal pointer at all. Reach for pos()/current() and friends only when you need fine-grained, manual control over position: for example, peeking at the current element inside a while (key($arr) !== null) loop, or stepping through an array in two directions. If you just want every element in order, prefer foreach.

Conclusion

The pos() function returns the value at an array's internal pointer without moving it, and is a legacy alias for current(). In new code prefer current(); combine it with next(), prev(), reset(), and end() to walk through an array manually — and remember that a false return can mean either a false value or the end of the array, so use key() when the distinction matters.

Practice