PHPCR

From David Buchmann:

iterators are a bit different between java and php. in java, next() advances the iterator one step and then returns the current element. advancing behind the end throws an exception. usually, you do

while(iterator.hasNext()) {
  item = iterator.next();
  ...
}

in php, next() only advances the pointer to the next element, its return type is void. getting the element is done using current(), it is an error to call current() if you are not at an element. to check if next() moved you past the end, there is the valid() method. iterators can be used in the foreach construct, that relies on this semantics. this typically looks like

foreach($iterator as $item) {
  ...
}

PHPCR_IteratorInterface extends the php Iterator. in my opinion, it should follow the php iterator semantics, not the java ones. then it could be used with the foreach construct and it would be less confusing.

we should however define the nextNode() and the other nextXY to follow the java semantics, as they are actually discribed in the jcr
specifications. so they would internally do

nextNode() {
 $this->next();
 return $this->current();
}

and, while criticizing: do we need append method? if the base php iterator does not have it, i do not really see why we should have it here. those iterators are typically used in a search result. we can not add anything to the jcr workspace there, as we do not know where to put it. at least, it should be optional and allowed to throw something like a NotImplemented exception.