PHP SeekableIterator : catch OutOfBoundsException or check valid() method? - php

Question

So I'm not sure if this is buggy design with PHP, or if there is an understood logic to handling inconsistent outcomes for the same interface.
The SeekableIterator interface has two methods (seek and valid) that are either in conflict with one another or should be working consistently with each other, but I'm seeing both.
The documentation for the interface says that seek should throw an exception of class OutOfBoundsException, but this seems to negate the usefulness of valid unless the iterator position is updated (making valid return false) before throwing the exception (which apparently must be caught).
Three test examples
Example 1.
Custom class implementing SeekableIterator, as provided by example in docs:
The class:
class MySeekableIterator implements SeekableIterator {
private $position;
private $array = array(
"first element",
"second element",
"third element",
"fourth element"
);
/* Method required for SeekableIterator interface */
public function seek($position) {
if (!isset($this->array[$position])) {
throw new OutOfBoundsException("invalid seek position ($position)");
}
$this->position = $position;
}
/* Methods required for Iterator interface */
public function rewind() {
$this->position = 0;
}
public function current() {
return $this->array[$this->position];
}
public function key() {
return $this->position;
}
public function next() {
++$this->position;
}
public function valid() {
return isset($this->array[$this->position]);
}
}
Example 1. Test :
echo PHP_EOL . "Custom Seekable Iterator seek Test" . PHP_EOL;
$it = new MySeekableIterator;
$it->seek(1);
try {
$it->seek(10);
echo $it->key() . PHP_EOL;
echo "Is valid? " . (int) $it->valid() . PHP_EOL;
} catch (OutOfBoundsException $e) {
echo $e->getMessage() . PHP_EOL;
echo $it->key() . PHP_EOL; // outputs previous position (1)
echo "Is valid? " . (int) $it->valid() . PHP_EOL;
}
Test 1 Output:
Custom Seekable Iterator seek Test
invalid seek position (10)
1
Is valid? 1
Example 2:
Using native ArrayIterator::seek
Test 2 Code:
echo PHP_EOL . "Array Object Iterator seek Test" . PHP_EOL;
$array = array('1' => 'one',
'2' => 'two',
'3' => 'three');
$arrayobject = new ArrayObject($array);
$iterator = $arrayobject->getIterator();
$iterator->seek(1);
try {
$iterator->seek(5);
echo $iterator->key() . PHP_EOL;
echo "Is valid? " . (int) $iterator->valid() . PHP_EOL;
} catch (OutOfBoundsException $e) {
echo $e->getMessage() . PHP_EOL;
echo $iterator->key() . PHP_EOL; // outputs previous position (1)
echo "Is valid? " . (int) $iterator->valid() . PHP_EOL;
}
Test 2 Output:
Array Object Iterator seek Test
Seek position 5 is out of range
1
Is valid? 1
Example 3:
Using native DirectoryIterator::seek
Test 3 Code:
echo PHP_EOL . "Directory Iterator seek Test" . PHP_EOL;
$dir_iterator = new DirectoryIterator(dirname(__FILE__));
$dir_iterator->seek(1);
try {
$dir_iterator->seek(500); // arbitrarily high seek position
echo $dir_iterator->key() . PHP_EOL;
echo "Is valid? " . (int) $dir_iterator->valid() . PHP_EOL;
} catch (OutOfBoundsException $e) {
echo $e->getMessage() . PHP_EOL;
echo $dir_iterator->key() . PHP_EOL;
echo "Is valid? " . (int) $dir_iterator->valid() . PHP_EOL;
}
Test 3 Output:
Directory Iterator seek Test
90
Is valid? 0
So how would one reasonably expect to know whether to use valid() to confirm valid position after seek($position) while also anticipating that the seek() might throw an Exception instead of updating the position, so that valid() returns true?

Answer 1

It seems that the directoryIterator::seek() method here is not implemented with an exception. Instead it will just return no value, and let valid() handle it.
Your other example, the ArrayObject::seek() does work "correctly" and throws an OutOfBoundsException.
The reasoning is simple: the ArrayObject (and most likely, most custom implementations too) will know beforehand how many elements it contains, and thus can quickly check its bounds. The DirectoryIterator however, must read the directory entities from disk one by one in order to reach the given position. It does so by literally calling valid() and next() in a loop. This is the reason why the key() has changed, and valid() returns 0.
The other iterators will not even touch the current iterator state, and can quickly decide if your request falls in its range or not.
On a sidenote: if you want to seek a position in the DirectoryIterator backwards, it will reset the iterator first, and then starts iterating each element again. So if you are on position 1000, and do a $it->seek(999), it will actually iterate 999 elements again.
IMHO, The DirectoryIterator is not a good implementation of the seekableIterator interface. It's intended to quickly jump to a certain element within the iterator and clearly, with a directoryIterator this is not something that is doable. Instead, a full iteration must be done, which results in a changed iterator state.
The seekableIterator interface is useful for filterIterators that do something with the range of the iterator. Within the SPL, this is only the LimitIterator. When you do:
$it = new ArrayIterator(range('a','z'));
$it = new LimitIterator($it, 5, 10));
When the limitIterator detects that the given iterator has implemented the seekableIterator interface, it will call seek() to quickly jump to the 5th element, otherwise it will just iterate until it reached the 5th element.
Conclusion: do not use the seekableIterator when you cannot quickly jump to a position or check bounds. At best you gain nothing, at worst you get iterators that change state without knowing why.
To answer your question: seek() should throw an exception and not change state. The directoryIterator (maybe some others too) should be changed to either not implementing seekableIterator, or by finding out how many entries there are prior to seek() (but that doesn't fix the 'rewind` when seeking backwards problem).