PHP Iterator

PHP arrays are generally very powerful object container. But still, we can easily add a little more fuel to them. Imagine Iterator object that is a kind of wrapper around our arrays. What we will try to accomplish here is to create unique interface for traversing arrays and to add a little more control over how our objects are created and finally, to support lazy loading.

Interface

#

Iterator has a very simple and many times seen interface.

function Iterator($array) - Constructor. Takes array to be traversed as a parameter.
function reset() - Sets internal pointer to the first element
function end() - sets internal pointer to the last element
function seek($position) - Sets internal pointer to desired position
function next() - Returns next element in the iteration
function previous() - Returns previous element in the iteration

With the interface like this you can easily finish all your daily tasks (such as traversing arrays in any way you want and from any position you want). One advantage of using this approach against native PHP array functions is that you have one interface for all of your array tasks. You will not use foreach() construct in one case, list-each combination in other and yet next() and prev() functions in third any more. One more advantage is that now you can easily position on any particular element and start traversing from there (in any way you want). Here are few code examples:

// $array = ?. // initialize the array

$iterator = new Iterator($array);
// traverse the array
while ($elem = $iterator->next()) {
	echo $elem;
}

// traverse array in reverse order
$iterator->end();
while ($elem = $iterator->previous()) {
	echo $elem;
}

// traverse array from fifth element on
$iterator->seek(5);

while ($elem = $iterator->next()) {
	echo $elem;
}

OK, you say, this is all nice but there is nothing I can’t do with combination of native PHP functions. Beside that you are accessing all your arrays through unique interface, another (and most important) advantage is that Iterator’s object structure allows you to easily expand its functionality.

ObjectIterator interface

#

Often I ended up with situations where my object methods had to return array of some other object as a result. Usually that object are loaded from the database, but some other situation are possible such as obtaining objects through some RPC protocol (XML-RPC, SOAP, …) or endless other situation combinations that you experience every day. In this article we will focus on the first problem and briefly explain how to empower Iterator for the any purpose you’d need.

Suppose that you are developing address-book part of some large web application. Your address-book will work with companies and persons. In addition, companies could have endless number of employees (that are also kind of persons). So far we have recognized two objects in our application: Company and Person. Also, it is clear that the company will have method getEmployees() that returns array of Person objects. There are number of possible implementation of this method. Here are some usual implementations.

First, you could write a query to collect all ids of the company employees. Then you could make array that contains all this objects and return this array. This would look something like this (supposing you have a database wrapper):

function getEmployees() {
$query = "SELECT id FROM persons WHERE companyid = $this->companyid";
$stmt = execute_query($query); // creates statement object
$this->employees = array();
while ($row = fetch_object($stmt) {
	$this->employess[$row->id] = new Person($row->id); // object creation
}

return $this->employees;
}

and the usage would be:

$company = new Company("Datagate");
$employees = $company->getEmployees();
foreach ($employees as $id =>$employee)
	$employee->addVacationDays(3); // object usage

OK, this looks like obvious solutions. But, it has few big flaws. All objects are created but we don’t know if we’ll going to use them all. There are two performance problems here. First accessing relational database (for creating these objects) are very time expensive. And if company have 500 employees and you need to access data of only 50, that is lot of time wasted. Imagine now, that we are loading this objects through RPC that is even slower. This could seriously affect application performance. Now, even if all objects are needed we don’t need them at the same time, we need objects one by one as we are traversing the array. The solution above is a huge waste of resources (memory and time).

Solution to these performance problems looks so obvious. Let’s return just array of employee ids. Code would look something like this:

function getEmployees() {
$query = "SELECT id FROM persons WHERE companyid = $this->companyid";
$stmt = execute_query($query); // creates statement object
$this->employees = array();
while ($row = fetch_object($stmt) {
	$this->employess[$row->id] = $row->id;
}

return $this->employees;
}

and the usage would be:

$company = new Company("Datagate");
$employees = $company->getEmployees();
foreach ($employees as $id) {
	$employee = new Employee($id); // object creation
	$employee->addVacationDays(3); // object usage
}

This looks fine at the first sight. We have saved time and memory space, but another problem arised. Suppose that the code for creating Employee object changes, for example you need to add extra argument to the constructor or some extra initialization (these are things that are happening on real projects). In that case you’ll need to modify your code on many places (wherever you have used getEmployees() method), And that is a problem.

The third solution is to use ObjectIterator class that is extended from Iterator. On this example we will see how easy it is to extend Iterator class to serve your purposes. When you are using ObjectIterator your getEmployee() function will stay the same as in second solution. So, we have saved our resources. No unnecessary objects are created and everything looks just fine. Now let’s look at the usage code:

$company = new Company("Datagate");
$iterator = new Iterator($company->getEmployees(), "Employee");
while ($employee = $iterator->next()) {
	$employee->addVacationDays(3);
}

We see now that the object creation code is hidden in ObjectIterator class so it is now easy to support changes.

ObjectIterator implementation

#

The code for ObjectIterator is quite simple.

/**
 * Implements iterator for traversing collection of objects
 * for the given array od object identifiers
 *
 * @version 1.0
 * @author Dejan Bosanac
 */

class ObjectIterator extends Iterator {
	var $_objectName;

	/**
	 * Constructor
	 * Calls initialization method (@see Iterator::_initialize())
	 * and do some specific configuration
	 * @param array $array array of object ids to be traversed
	 * @param string $objectName class of objects to be created
	 * @access public
	 */

	function ObjectIterator($array, $objectName) {
		$this->_initialize($array);
		$this->_objectName = $objectName;
	}

	/**
	 * Returns object with given id
	 * @param Object $id identifier of the object
	 * @return Object next object in the collection
	 * @access private
	 */

	function _fetchObject($id) {
		return new $this->_objectName($id);
	}

}

It has $_objectName class member that represent class of the object that have to be returned by next() and previous() methods. Constructor sets this internal variable and calls initialization function (defined in Iterator class). The most important thing is _fetchObject() function. It encapsulates code for object creation. It is called from next() and previous() methods and takes object id as a parameter. So all yours object creation code is localized here, thus makes it easy to change and expand.

So, here are instructions for creating new type of iterators. First, make your constructor (which has to have array for parameter) calls _initialize() function from Iterator class. Second, override _fetchObject method to do whatever you have to do to make your objects. And, that would be all.

In conclusion

#

Iterator will not slow down your application in that way that it will need new hardware to run it. It has some overhead, but for that price you get clean and easy readable code that is flexible enough for future software enhancements.

You can download PHP Iterator from here