Earlier this week, I spent most of a day tracing through code in search of the source of a bug that was causing part of our application to fail in strange ways.
In the back end, we have models that connect to CouchDB. These models implement the Iterator pattern to allow easy traversal of a record’s keys.
When I wrote the code to implement Iterator several months
ago, I dutifully checked the PHP
Manual and adapted the reference example that I found there:
<?php
class Record implements Iterator
{
// (partial class, showing the iterator implementation only)
public $_data = array();
public function rewind()
{
reset($this->_data);
}
public function current()
{
return current($this->_data);
}
public function key()
{
return key($this->_data);
}
public function next()
{
return next($this->_data);
}
public function valid()
{
return (current($this->_data) !== false);
}
}Little did I realize that this implementation is very broken. I’ll explain why, below.
Over the past few years, I’ve implemented many iterators in
this way, using PHP’s implicit array manipulation functions
(reset(), current(), key(),
next()). These functions are very convenient because PHP
arrays are so powerful — arrays in PHP work like ordered hash tables in other
languages.
PHP’s implicit management of an array’s iteration index
(the value that is incremented by next() and
referenced by key()) is indeed convenient, but the convenience
can sometimes be offset by its very implicitness — the value is hidden from
you, the PHP programmer.
In PHP, generic array iteration (without the implicit iterator) isn’t actually as simple as it sounds. Remember that arrays aren’t arrays in the traditional sense, but ordered hash tables. Consider this:
$data = array('zero','one','two','three');
for ($i=0; $i<count($data); $i++) {
// yeah, don't calculate count() on every iteration
echo "{$data[$i]}\n";
}Output:
zero
one
two
threeThis first example is easy to iterate — the array contains sequential, numeric, zero-based keys. It gets more complicated when using non-sequential, and non-numeric keys:
$data = array(
'apple',
'cow' => 'moo',
'pig' => 'oink',
'orange'
);
for ($i=0; $i<count($data); $i++) {
echo "{$data[$i]}\n";
}Output:
apple
orange
Notice: Undefined offset: 2 in - on line 10
Notice: Undefined offset: 3 in - on line 10I could use foreach, but because a numeric loop illustrates the point more clearly, here’s how I might implement the above code so that it works:
$data = array(
'apple',
'cow' => 'moo',
'pig' => 'oink',
'orange'
);
$k = array_keys($data);
for ($i=0; $i<count($data); $i++) {
echo "{$data[$k[$i]]}\n";
}Output:
apple
moo
oink
orangeThis brings us back to the Iterator implementation. Why
isn’t the code above correct? Take a closer look at this:
public function valid()
{
return (current($this->_data) !== false);
}A value of false in the array is indistinguishable from a
false value returned by current(). Using the
above implementation with the following array would cause it to bail after
orange (and subsequently might cause you to waste a day
tracking down the cause):
array(
'apple',
'orange',
false,
'banana',
);On Tuesday night, I
updated the manual
to use an
improved Iterator implementation.
It’s probably a bit slower (so you
can use the internal-indexing implementation if you’re sure your arrays
will never contain false), but my implementation is more
robust.
<?php
/**
* A mixed-key iterator implementation
*
* Note: these array_keys() calls are slow. The array keys could be cached
* as long as the cache value is invalidated when $_data is changed.
*/
class It implements Iterator
{
public $_data = array();
protected $_index = 0;
public function rewind()
{
$this->_index = 0;
}
public function current()
{
$k = array_keys($this->_data);
return $this->_data[$k[$this->_index]];
}
public function key()
{
$k = array_keys($this->_data);
return $k[$this->_index];
}
public function next()
{
$k = array_keys($this->_data);
if (isset($k[++$this->_index])) {
return $this->_data[$k[$this->_index]];
} else {
return false;
}
}
public function valid()
{
$k = array_keys($this->_data);
return isset($k[$this->_index]);
}
}To use it:
$it = new It;
$it->_data = array(
'one' => 1,
'two' => 2,
false,
'four' => 4
);
foreach ($it as $k => $v) {
echo "{$k}: {$v}\n";
}Output:
one: 1
two: 2
0:
four: 4
