PHPLIB-81: Add caching iterator

[alcaeus]

This is a shot at implementing an iterator like described in PHPLIB-81. It is designed to wrap any iterator, cache its results on the first run and the return the results on subsequent runs. It can be used to iterate multiple times over cursors.

I've also implemented Countable in the iterator, exposing a count method since this doesn't suffer from the original issue of MongoCursor::count (which could return a number that does not match the items returned in the cursor).

At this time, the iterator is not used anywhere and its use is left to the user of the library. Of course, operations could be changed to return a CachingIterator instead of a Cursor. The problem is that MongoDB\Driver\Cursor does not implement an interface (which CachingIterator could implement to provide a common parent class) and can't be extended due to its final constructor.

[jmikola]

Conflicts with composer.json requiring PHP >= 5.4. I'll see what we can do about bumping this for 1.2.0.

[alcaeus]

Right, I forgot about the PHP requirement. If you'd like to avoid bumping the minimum PHP version to 5.5 I could try rewriting it with an IteratorIterator.

[moderndeveloperllc]

@jmikola Is 1.2.0 still going to stay PHP 5.4 compatible, or move up to 5.6?

[jmikola]

Is 1.2.0 still going to stay PHP 5.4 compatible, or move up to 5.6?

We're planning to bump 1.2.0 to PHP 5.5 specifically for this feature.

[alcaeus]

@jmikola Rebased against master, let me know if there's anything else to do.

[bjori]

This isn't a caching iterator.
A caching iterator wouldn't fetch the individual results until asked for. As such, when a document is inserted, and picked up by the cursor later, is not picked up by this cachingiterator as it exhaust the cursor upfront.

This implementation mimics a buffered iterator (which is a good idea imo, rather than caching iterator).
I think it should be renamed to BufferedIterator, which would also help users coming from for example pdo_mysql to understand what this really does

[bjori]

Oh, it is caching iterator. My scroll through the class confused me, as I saw couple of $this->exhaustIterator(); calls :)

I think a BufferedIterator makes more sense then the caching iterator.
Each iteration doesn't accidentally cause a network IO, but rather has predictable cost paid upfront

[alcaeus]

Oh, it is caching iterator.

Yes, it is, but it's hybrid. The main idea was to have a way to iterate a cursor multiple times, without rerunning the query/command in question and without loading all data into memory upfront (e.g. if only the first result is consumed). Thus, the iterator behaves like a regular iterator until it's rewound for the first time, at which time it returns results from the cache.

[jmikola]

Closing, as I incorporated these commits into #424.