Introduction to SPL

Introduction to Standard PHP Library (SPL)

By Kevin Waterson

Contents

• What is SPL
• What are Iterators
• Apply Callback Function to Iterator
• ArrayAccess
• Directory Iterator
• Extending the DirectoryIterator
• ArrayObject
• Array Iterator
• RecursiveArrayIterator
• Something useful
• Overloading
• Filter Iterator
• Simple XML Iterator
• Caching Iterator
• Limit Iterator
• SplFileObject
• SPL Autoload
• Conclusions
• Credits

What is SPL.

SPL provides a standard set of interfaces for PHP5. The aim of SPL is to implement some efficient data access interfaces and classes for PHP. Functionally it is designed to traverse aggregate structures (anything you want to loop over). These may include arrays, database result sets, xml trees, directory listings or any list at all. Currently SPL deals with Iterators. To see all the classes available to SPL, this simple snippet will show you.

This will provide you with a list something like this:

• AppendIterator -> AppendIterator
• ArrayIterator -> ArrayIterator
• ArrayObject -> ArrayObject
• BadFunctionCallException -> BadFunctionCallException
• BadMethodCallException -> BadMethodCallException
• CachingIterator -> CachingIterator
• Countable -> Countable
• DirectoryIterator -> DirectoryIterator
• DomainException -> DomainException
• EmptyIterator -> EmptyIterator
• FilterIterator -> FilterIterator
• InfiniteIterator -> InfiniteIterator
• InvalidArgumentException -> InvalidArgumentException
• IteratorIterator -> IteratorIterator
• LengthException -> LengthException
• LimitIterator -> LimitIterator
• LogicException -> LogicException
• NoRewindIterator -> NoRewindIterator
• OuterIterator -> OuterIterator
• OutOfBoundsException -> OutOfBoundsException
• OutOfRangeException -> OutOfRangeException
• OverflowException -> OverflowException
• ParentIterator -> ParentIterator
• RangeException -> RangeException
• RecursiveArrayIterator -> RecursiveArrayIterator
• RecursiveCachingIterator -> RecursiveCachingIterator
• RecursiveDirectoryIterator -> RecursiveDirectoryIterator
• RecursiveFilterIterator -> RecursiveFilterIterator
• RecursiveIterator -> RecursiveIterator
• RecursiveIteratorIterator -> RecursiveIteratorIterator
• RecursiveRegexIterator -> RecursiveRegexIterator
• RegexIterator -> RegexIterator
• RuntimeException -> RuntimeException
• SeekableIterator -> SeekableIterator
• SimpleXMLIterator -> SimpleXMLIterator
• SplFileInfo -> SplFileInfo
• SplFileObject -> SplFileObject
• SplObjectStorage -> SplObjectStorage
• SplObserver -> SplObserver
• SplSubject -> SplSubject
• SplTempFileObject -> SplTempFileObject
• UnderflowException -> UnderflowException
• UnexpectedValueException -> UnexpectedValueException

What are iterators?

An Iterator is an object that traverses a structure eg: an array or a directory listing or possibly a set of database result sets or other resource. This is not an accurate discription, but more will become clear later by way of example. There are different types of iterators for dealing with different types of data such as array Iterators, Directory Iterators and more. Here we will begin to get familiar with them beginning with the DirectoryIterator. What is important to note is they can all be accessed with a standard interface. This means that regardless of the data type, access to the information is standardised. This is a real step forward for PHP.

Apply Callback Function to Iterators

As Iterators are read-only, a callback cannot act directly on iterator values. But this does not limit the use of a callback in being able to affect the output iterator elements. In this example, a simple array is used and a callback function applied to the each element of the iterator with the iterator_apply() method.

Note that the addCaps function returns bool true. If this does happen, only the first element will be affected because the iterator_apply() function will continue to execute only while the return value is bool true. The results from the script above produce results with the first letter of the array elements caplitalized.

Dingo
Wombat
Wallaby

Extending the DirectoryIterator class.

The code above demonstrates how we can overload the Iterator methods to reduce the logic within the user code. This creates great opportunities to make portable classes for re-use, thus reducing user code and speeding up development time. Once again the use of Exceptions shows how easy it can be to catch errors and deal with them. We could, of course, use the isFile() method in place of isDir() to show only files. The possibilities are endless.

Lets go over what we have done here. First we have created a small class to extend the internal DirectoryIterator class. In the constructor we have passed the $path variable and called the parent class constructor. The parent class is of course the SPL DirectoryIterator class.

The valid method checks if the file meets a criteria. This begins with the parent::valid checking to see that the current iteration has a value. From there we check if the current Iteration is a directory by calling the parent::isDir() method. If this is not a directory, the iterator is advanced with theparent::next() method and checks again if the next value is valid. We could have used the FilterIterator to achieve the same goal, but more on that later.

ArrayObject

The ArrayObject allows for external traversal of arrays and to create instances of ArrayIterator. Much like the Directory iterator, we can see the methods available to the Array Iterator with a simple snippet.

Again we see the class methods in a list as follows.

• 0 -> __construct
• 1 -> offsetExists
• 2 -> offsetGet
• 3 -> offsetSet
• 4 -> offsetUnset
• 5 -> append
• 6 -> getArrayCopy
• 7 -> count
• 8 -> getFlags
• 9 -> setFlags
• 10 -> asort
• 11 -> ksort
• 12 -> uasort
• 13 -> uksort
• 14 -> natsort
• 15 -> natcasesort
• 16 -> getIterator
• 17 -> exchangeArray
• 18 -> setIteratorClass
• 19 -> getIteratorClass

We will see in the following code snippets, various ways to use some of these methods along with the ArrayIterator class. First a simple ArrayObject and ArrayIterator.

In the above script we have externally traversed the array object with getIterator(). We could have used a foreach on the array and the getInstance() method would be called implicitly. The key() and current() methods also belong to the ArrayIterator Instance. From the above code snippet we get a simple array output as follows

• 0 => koala
• 1 => kangaroo
• 2 => wombat
• 3 => wallaby
• 4 => emu
• 5 => kiwi
• 6 => kookaburra
• 7 => platypus

You might be getting the swing of this by now, so to keep it simple we will use the same code from above and append, or add, a value to the array and iterate over it. Note that the ArrayObject::getIterator returns an ArrayIterator instance working on the original ArrayObject instance. It's only method getIterator() is automatically called in iteration, thus if you put an ArrayObject which implements that interface into a foreach() construct that method is being executed automatically. Since the ArrayObject returns an ArrayIterator interface the foreach() Construct will reset that iterator and work on it.

Now we see that the list has the value 'dingo' on the end of it and we begin to see the usefulness of an Object Oriented approach. Our list looks like this.
0 -> koala
1 -> kangaroo
2 -> wombat
3 -> wallaby
4 -> emu
5 -> kiwi
6 -> kookaburra
7 -> platypus
8 -> dingo

We can sort the array with one of the array sort methods available to the array object. In this instance, we will sort alphabetically using the natcasesort() method.

Now we see our array has changed and the output now looks like this:
4 -> emu
1 -> kangaroo
5 -> kiwi
0 -> koala
6 -> kookaburra
7 -> platypus
3 -> wallaby
2 -> wombat
As you can see, the order has changed but not the keys. We could sort them similarly with asort, usort or any of the other sorting methods listed by get_class_methods(). To see a count of the total number of members in our array object is a trivial matter of using the count() method as shown below.

We see the return value from the count() method is 8. We may also note that one of the beasts in our array of animals does not belong. This is an array of animals native to Australia (straya), but the kiwi is a New Zealand critter. To remove this undesirable from the array we use theoffsetUnset() method. Lets see how it works.

The above code will produce this output..
0 -> koala
1 -> kangaroo
2 -> wombat
3 -> wallaby
4 -> emu
6 -> kookaburra
7 -> platypus
The offending New Zealand critter has been removed from the array but the array is not re-indexed.

To check for the existance of an offset within the array, we use the offsetExists() method as demonstrated below.

The above snippet tells us the offset Exists and runs the code in the if{} block. This has the same functionality as array_key_exists(). It is possible to change the value of an array member with the offsetSet method. Here we show how by changing the kiwi to the Australian native bird 'galah'.

We see that when we iterate over the array object the kiwi has been set to 'galah'. We can also get a value from the array object by using the offsetGet() method.

The script above prints 'emu' as this is the value of the offset 4.

There are times you may need a copy of an array to edit or to do comparisons, to this end the method getArrayCopy() is provided for just that purpose. Here we show a simple array copy.

When you run the above code you will get an error message similar to this..
Fatal error: Call to a member function getIterator() on a non-object in /www/spl.php on line 13
This is because the copy of the array is just a copy of the array, it is NOT an array object that SPL can iterate over, so we must create a new array object as shown here:

Now of course, we can safely iterate over the newly create array and array object, the results will be as before:
0 -> koala
1 -> kangaroo
2 -> wombat
3 -> wallaby
4 -> emu
5 -> kiwi
6 -> kookaburra
7 -> platypus

The ArrayObject class also comes with several flags..

• ARRAY_AS_PROPS
• STD_PROP_LIST

These flags are quite funky the ARRAY_AS_PROPS constant allows array indexes to be accessed as properties in read/write, while the STD_PROP_LIST allows properties of the object to have their normal functionality. Lets begin with a short demonstration of ARRAY_AS_PROPS.

ArrayIterator

If you have not read the previous section on ArrayObject it is highly recommended you do so, as this section is really an addition to the previous where we have been using the ArrayIterator to traverse ArrayObjects.. The ArrayIterator makes use of the ArrayObject to traverse arrays and an understanding of this is important. Much like the Directory iterator, we can see the methods available to the Array Iterator with a simple snippet.

The above snippet will produce a list of methods available to the ArrayIterator class as shown below.

• 0 -> __construct
• 1 -> offsetExists
• 2 -> offsetGet
• 3 -> offsetSet
• 4 -> offsetUnset
• 5 -> append
• 6 -> getArrayCopy
• 7 -> count
• 8 -> getFlags
• 9 -> setFlags
• 10 -> asort
• 11 -> ksort
• 12 -> uasort
• 13 -> uksort
• 14 -> natsort
• 15 -> natcasesort
• 16 -> rewind
• 17 -> current
• 18 -> key
• 19 -> next
• 20 -> valid
• 21 -> seek

Some of this should look familiar if you have read the DirectoryIterator section. Remember the 'S' in SPL is for 'Standard' and here we see why. From here, using the ArrayIterator is quite simple given any array. Here we iterate over a simple array and output the variables to the browser. The ArrayIterator takes an ArrayObject as its arguement, so, before we can use the ArrayIterator class we must create the ArrayObject to be able to iterate over it.

We have already seen the ArrayIterator in action with the ArrayObject. Lets see a simple array iteration.

Of course, the script above iterates over the array and produces a list of the array keys and values, it shows how we have manually called the ArrayIterator to traverse the array of animals. We could however, call the ArrayIterator implicitly like this:

Above we see the ArrayIterator is implicitly used but we the difference is hidden from us. A traditional array traversal allocates every member of the array to memory. The iterator assigns memory for the current element only. This can be a huge benifit when dealing with large arrays.

Array offsets may be checked for and acquired using the offSetExists() and offSetGet() methods as shown below.

The above code checks for the existence of the offset 2 with the offSetExists() method. When it is found, the value of the offset is used to display it using offSetGet(). We can also set and unset array members within the array.

Now we see some interesting behaviour along with our expected behaviour. Using the offsetSet() method the value at the offset of 2 has been changed from wombat to Goanna. The a simple foreach to iterate over the array. The output looks like this..

• 0 - koala
• 1 - kangaroo
• 2 - Goanna
• 3 - wallaby
• 4 - emu
• 5 - kiwi
• 1 - kangaroo
• 2 - Goanna
• 3 - wallaby
• 4 - emu
• 6 - kookaburra
• 7 - platypus

Notice here how the iterator pointer has been re-wound back to the beginning of the array when we used the offsetUnset() method to unset the array whose key had the value of kiwi. The iteration begins again and as you can see, the key of 5 with the value of kiwi is missing from the object. The internal point can be re-wound intentionally should we wish, using the rewind() method.

The code above will produce a list like this:

The iterator has traversed the array successfully, then we have used the $object->rewind method to rewind the internal pointer back to the beginning of the array and display the value of the current member, which is koala.

If we wanted to get the size of the object, it is a trivial matter of using the count method as follows.

The above will return a value of 8 as there are 8 members in our array object.

Recursive Array Iterator

The array iterator above is great for traversing single dimensional arrays. Of course not all arrays are like this, quite often we are presented with a multi-dimensional array. In the bad old days to get around this we might have used 2 foreach() loops, which would have been very costly. To traverse a multi-dimensional array we use the RecursiveArrayIterator(). Lets take a quick at how it looks.

The output from the above code will produce the following..

• 0 -- Array
• 1 -- Array
• 2 -- Array

You might be saying WTF! about now as all we see is an array of arrays. This is because we need to iterate recursively over the recursive iterator object. To do this we need an iterator, that will recursively iterate over an iterator. The RecursiveIteratorIterator is the correct tool for this. Lets adjust our code a little to see how it works.

In the above code, the RecursiveIteratorIterator() takes an iterator as its argument, in this instance, a RecursiveArrayIterator(), which in turn takes a multi-dimensional array as its arguement. This is a far more graceful way of traversing a multi-dimensional array than we have previously been used to. The above code will now recursively iterate over the multi-dimensional array, and give us output like this below.

• name -- butch
• sex -- m
• breed -- boxer
• name -- fido
• sex -- m
• breed -- doberman
• name -- girly
• sex -- f
• breed -- poodle

Something useful.

We have seen a few implementations of iterators above,but other than iterating over an aggregate structure, such as an array, what can we do with them? The power of iterators comes in that they will iterate over _any_ aggregate structure or list as mentioned above. Here we will use PDO and SPL to create a HTML table fromdatabase results. For those not familiar with PDO it is highly recommended you get aquainted with this database interface. An Introduction to PDO is available to get you started. Lets start with the database, we will use SQLite for this excersize. A SQLite database file is availble with a periodic table of elements that will be used in this tutorial. We will see in the three examples below an increasing degree of complexity when using iterators. Each level of complexity allows better control or extensibility. To start with, we will use

The above code uses PDO to access the SQLite database, the SQL statement is then "prepared" and executed. Then SPL takes over to deal with the fetching of information from the executed query. Again we see here the ArrayObject::getIterator returns an ArrayIterator() working on the original ArrayOject instance. It's only method getIterator() is automatically called in iteration, thus if you put an ArrayObject which implements that interface into a foreach() construct that method is being executed automatically. Since the ArrayObject returns an ArrayIterator interface the foreach() Construct will reset that iterator and work on it.

Using the IteratorIterator we can take a PDO instance and convert it allowing us to use any of the iterator functions we have seen in this tutorial, we have access to all the various iterators and methods that SPL has to offer. Lets continue through the code. The next block of code is a simple foreach() as we have seen previously on this page. Within this loop we create an Array Object from each row. Each row is an array containing our individual result rows. As seen previouly, traversing an array structure is quite simple with SPL iterators, and this is no different. A for loop is used to iterate over the array and echo the results to the broswers. No table formatting has been added at this time, simple a list of elements from the periodic table and various information about them. Each result row is seperated by an HTML horizontal line. Here we show the first two (for brevity) results of the 109 elements.

As you can see, we have duplicate results with both associative and numerical indexes. This is because the default behavior of the iterator is to use FETCH_BOTH. This behaviour can be changed to allow us to fetch either a numerical or an associative array with the PDOStatenem::setFetchMode. In the following example will will use this to change this behavior.
We also see in the above code that we create an Array Object each time we loop through the result set. This seems a little inefficient and we will also optimise this further in the code below.

Now we see some changes to both our code and our output. We have added some HTML formatting to better present our results data in the form of tables. We also see we have change to FETCH_ASSOC and our array indexes now derive there names from the column name in the database. More importantly, is the way in which we have simplified our code by not creating the Array Object in each iteration. Instead we directly access the the array by using this line:

Overloading

This increases our complexity level yet lessens our code structure and speeds us up as we no longer need to create the Array Object each time. By directly interfacing with the ArrayIterator we get a much smoother code flow and make better use of PHP's Object Oriented capabilities. We can take this yet a step further and overload or extend the Iterators as seen previously. Our final example looks like this:

Here we have changed the format a little by changing the table structure a little and adding a title to it. But look at the implementation. A class has been created with the name TableRows. This is to add the HTML tags for our table rows. This is done by overloading the RecursiveIteratorIterator. class. SPL allows us to directly interface with the parent class and define actions within the parent class methods. In our example here we have passed the iterator to the constructor and then as it is internally travesed, the functions beginChildren() and endChildren() add the table row tags.

Filter Iterator

The snippet above will produce a list of methods in the FilterIterator like this:

• __construct
• rewind
• valid
• key
• current
• next
• getInnerIterator
• accept

The above code will produce a list as follows:

• 0 == koala
• 1 == kangaroo
• 2 == wombat
• 3 == wallaby
• 4 == emu
• 5 == kookaburra
• 6 == platypus

As we iterate over the array the accept() method is called to see wether the current key is valid, in this case, if it is numeric as checked with the PHP is_numeric() function. should be accepted. Of course we could do other tricks within the accept method as seen here as we filter out the prime numbers from an array of numbers.

From the above code we get a list of the prime numbers between 212345 and 212456 as shown here:

• 212353 is prime.
• 212369 is prime.
• 212383 is prime.
• 212411 is prime.
• 212419 is prime.
• 212423 is prime.
• 212437 is prime.
• 212447 is prime.
• 212453 is prime.

This sort of filtering makes the FilterIterator quite a useful tool for aggregate stuctures. Remember, the data could be XML or database results and with the FilterIterator you can specify whatever rules you like in the accept() method. The job of the accept() method is to decide whether an element of the inner iterator should be accessible through the Filteriterator. The inner iterator in the case above is the ArrayIterator.

Oh, and if you think you have a better prime number checking algorithm, please submit it and we will include it.

Simple XML Iterator

The above code will produce a list of class melthods like this:

To get an idea of how the SimpleXmlIterator is implemented a few scripts are provided, however, for the sake of sanity, only the first script will contain the XML tree for use in the other scripts.

The above code will produce a dump of all the elements within the XML tree and if they have a value, that will also be shown. What we have done is used the simplexml_load_stirng() function, which returns an object, to load its return value directly into the SimpoeXmlIterator. Remember that the SimpleXmlIterator is a recursive iterator, so we need an iterator to iterate over a RecursiveIterator. The correct tool for this is the RecursiveIteratorIterator which will, as the name suggests, iterate over a recursive iterator. But, we usually need a little more control than that. Here we will select the species node of each animal. Only the code is shown, not the XML.

So now we simply have a list like this:

• Phascolarctidae
• macropod
• diprotodon
• macropod
• dromaius
• Apteryx
• kingfisher
• monotremes
• arachnid

What has been done in the above script is to instantiate a new SimpleXmlIterator object. Then we have needed two foreach loops to correctly return the species values. This to me looks rather cumbersome, so lets try another way.

In the above code we have loaded the SimpleXmlIterator the simplexml_load_string() function and still have needed two loops, a for and a foreach, to iterate over the object. Here we have also used a conditional statement with SimpleXmlIterator::hasChildren() to check for the existence of child nodes. If a child node is found, the SimpleXmlIterator::getChildren() method can the node values and we can then view the results. Is this a better way? Is it faster? Lets look at a quick test with AB (Apache Bench) to see what results we can get.

The first method using two foreach statements and AB returned these results with 10,000 requests with a concurrency of 20.

The second method with 10,000 requests a concurrency of 20 produced the following results.

The second method comes in at about 5 seconds slower than the first. Showing that while the nested foreach loops may look a little clumsy, but as the iterator uses less memory, it is more efficient. The reality is that both these methods suffer and a better way is to had with xpath.

The SimpleXmlIterator::xpath() method allows direct iteration over an XML tree by specifying the xpath to the node. Similar to a file system path, the xpath is of the species node in our XML document looks like this:

The ability to specify the xpath to the particular node saves us many iterations of the XML tree which, in turn, saves us CPU cycles, thus allowing for much faster scripts. The code below will give the same listing of species as the two examples above, but this time we will use the xpath to go directly to the node we want to view. Once again, the XML tree has been omitted for the sake of brevity.

Once again we produce a list of species from XML tree like this:

• Phascolarctidae
• macropod
• diprotodon
• macropod
• dromaius
• Apteryx
• kingfisher
• monotremes
• arachnid

This is a far more efficient method of retrieving XML data. By simply changing the species path to name we could fetch a list of the animal names. All Australian animals would seem to be called Bruce. We can traverse unlimitted depths with the xpath. Below is smail XML tree with more depth.

The XML tree above has five levels from the document root. Using xpath we have traversed the tree directly to the node we seek. The saving in iterations here is obvious as we no longer need to set up a foreach heirachy to traverse the tree on the. The xpath to enlightenment just got easier.

A problem arises in XML when two documents may have similar names. If we had the xml document of animals, and another of animal owners, a conflict may arise in the name node. Each of the animals, and owners would have a name node and a method is required to distinguish between them. The SimpleXMLIterator provides several methods for the management of namespaces. These include as listed in the top of the this chapter. The script below shows a small change to the xml string that has been used and demonstrates the use of namespaces and how to utilize them within the SimpleXMLIterator.

In the script above we have declared a namespace in our root as
<document xmlns:spec="http://example.org/animal-species">
Also not the addtion to the XML of a second name node. This is prefixed by the spec: prefix to identify the namespace and not confuse it with the regular animal names. The use of the SimpleXMLIterator::registerXPathNamespace() method ensures the document namespace prefixing is sane. To get the namespaces the SimpleXMLIterator::getDocNamespaces() method is used to get the names of all namespaces declared within the document. The SimpleXMLIterator::getNamespaces() method could also have been used. The SimpleXMLIterator::getDocNamespaces() method only gets those namespaces that are actually declared within the document itself.

To add a child to the XML tree is also simple with the SimpleXmlIterator::addChild method. The XML string for this script has been simplified to better demonstrate adding a child.

The script above produces a list like this:

• koala
• kangaroo
• wombat
• wallaby
• emu
• kiwi
• kookaburra
• platypus
• funnel web
• Tiger

Note that when the new we call the saveXML() method that the XML is saved as an XML string once more. If we wish to iterate over the new string, we need to use another iterator instance. The saveXML method is an alias of asXML and was added to remove the inconsistency with domXML::saveXML. Adding an attribute is just as easy with the addAttribute method as shown here.

For demonstration purposes htmlentities() has been used to show the actual XML data and not just the values. The resulting XML string now looks like this:

Caching Iterator

The caching Iterator is a forward seeking iterator and is useful for lookng forward to check if there is a valid next item.

This note from the PHP source best describes what it can do

• note If you want to convert the elements into strings and the inner
• * Iterator is an internal Iterator then you need to provide the
• * flag CIT_CALL_TOSTRING to do the conversion when the actual element
• * flag CALL_TOSTRING to do the conversion when the actual element
• * is being fetched. Otherwise the conversion would happen with the
• * already changed iterator. If you do not need this then it you should
• * omit this flag because it costs unneccessary work and time.

Once again we will see what methods are available to the iterator.

From the above we get a list like this...

Some of the above methods will look very familiar by now. These include rewind(), valid(), current() and the usual suspects. But the CachingIterator also brings a few additions with hasNext and __toString and others. Lets begin with the hasNext() method. For the sake of example, we want our array to be formatted for use in a CSV file. This means we need a comma (,) after each member, except the last one. Traditionally we would have needed to do something like this...

Apart from being plain ugly, the use of foreach here creates memory issues when it creates a copy of the array. Because SPL iterators know only one element at a time, it is far more efficient. Lets see how SPL deals with the same task.

This makes for much cleaner code by ridding us of counters and the like, we could further make this code more re-usable by extending the CachingIterator class. This would be most helpful if this task was something that needed to be done on a regular basis.

We see from the above script that the same result is achieved but the code base is now a re-usable class extension. If we wanted access to the inner iterator, ie. ArrayIterator, we could use the getInnerIterator() method to do so.

The above results produce a list of animals minus the array member 5, the kiwi. we used the getInnerIterator() method to directly access the inner iterator, in this case the ArrayIterator, which gives us access to all the fun methods associated with that iterator. However, this still may not be optimal for re-use. We could call the inner iterator from our extended class and deal with the offending kiwi there, thus streamlining our userland codebase.

Now we see how extensible SPL really is. The same concepts can be used with all iterators when extending. The CachingIterator also has a number of flags for use with the iterator. They are..

• CALL_TOSTRING
• TOSTRING_USE_KEY
• TOSTRING_USE_CURRENT
• TOSTRING_USE_INNER

The CALL_TOSTRING flag is quite simple as it simply calls __toString() method.

As seen above, the object has been made into a string representation and can be used directly as a string. Note also we have used the CachingIterator::setFlags() method to set the flag. We use the TOSTRING_USE_KEY in the same way. This flag will call the array keys as shown below.

The TOSTRING_USE_KEY flag has been used to grab the array keys from the caching iterator object, and force them into a string representation. So the result from the above code will yield the numbers 0-7. Not too exciting, but remember, iterators can be used to traverse ANY aggregate structure, so if the above principles were applied to an XML document, or a result set from a database query, you can quickly see how this might be useful. Finally the TOSTRING_USE_CURRENT is once again used in the same manner as shown here.

The TOSTRING_USE_INNER flag is used to call the __toString() method from an inner iterator object. Lets put it to work and then see you the results.

The TOSTRING_USE_INNER flag has been set and so the __toString() method has been called from the inner interator object. The inner iterator object in this case is formed from the thte MyArrayIterator class which extends ArrayIterator. The MyArrayIterator::__toString() method has been used to return a string representation of the current key and value. This results in a list such as this.

• 0:koala
• 1:kangaroo
• 2:wombat
• 3:wallaby
• 4:emu
• 5:kiwi
• 6:kookaburra
• 7:platypus

Note: you can only use ONE flag for the __toString() method. If you try to use more an exception will be thrown.

There may be a bit to digest from the code above. But essentially it checks the offsets in offsetArray and prints the values like this.

• 0 == koala
• 2 == wombat
• NZ == kiwi
• 3 == wallaby
• 6 == platypus

So, there is a little WTF value here. We have used offsetExists to check the values of the offsetArray and offsetGet to print the value of the offset. You will have noticed that the offset of 6 is platypus. This is because there is no offset of 7 as the fifth offset is NZ with the value of kiwi. So offset 5 becomes the next offset and 6 is the final offset in this array.

The offsetUnset() method has been left to now for the reason of explaining some internal behaviour that may not be apparent other wise. When an offset is unset, only the value of the offset is unset and the offset/key remains. In the cache however, the offset and key are removed. The script below shows clearly the behavior when the cache is called with the getCache() method.

The results from the above code will produce the following output.

Note that in the first iteration, the NZ key remains and the value has been removed. When the cache itself is checked with getCache we see the true picture of the current state of the offset keys and values. The array object has been re-indexed with the NZ offset key and value removed.

Limit Iterator

As the name suggests, the LimitIterator allows the coder to limit the return values. Lets see the methods available to the LimitIterator.

The results from above show us the following methods available to the LimitIterator

• __construct
• rewind
• valid
• key
• current
• next
• seek
• getPosition
• getInnerIterator

Once again we see the usual suspects os valid() key() current() next() for iteration. What makes the LimitIterator funky is the seek() method and getPosition() method. The LimitIterator is an outer iterator and takes an iterator as a parameter for the construct. The LimitIterator allows you to specify the offset and the number of results returned. I can already hear the gears grinding as you think how this might be ideal for pagination of an aggregate structure such as database results, or an XML heirachy. This sort of functionality allows us to mimic the behaviour of the SQL LIMIT clause with the use of an offset and limit,except we can use it over any aggregate structure.

The above code will produce a list of like this:

• animal -- wallaby
• animal -- emu

Using the offset and limit variables, we have successfully extracted the XML data by positioning the internal pointer to the third item in the tree (offset)and fetching the next two items (limit). The offset an limit variables could come from POST or GET to aid in your application pagination. We saw here the use of the SimpleXMLiterator as our inner iterator. The SimpleXMLIterator can do much more. You can read more in SimpleXML Iterator chapter. The LimitIterator also allows the checking of the position of the internal pointer to check where you are in your iteration. Here we will switch to an ArrayIterator as the inner iterator to see your we can get the position of the internal pointer with the getPosition() method.

The code above will give us the results 3 and 4. The LimitIterator::getPosition() method has given the current position within the iterator. We can also use the seek() method to go directly to a position within the iterator. When called, the seek() method implements the SeekableIterator to find the required position and exposing the value to the current() method.

If you run the above code you will get an error message like this:

This is because we have incorrectly specified the seek parameter and an OutOfBoundsException is thrown. We then catch the exception and many handle the error as we wish. Lets try again with some valid values.

This time we have removed the offset and the limit and the whole inner iterator is exposed. The seek() method has been used to direct the internal pointer to the offset of 5. It is then a simple matter to echo the current() value, in this case the result is kiwi. Like all outer iterators, the LimitIterator allows us access to the inner iterator with the getInnerIterator() method.

This time we have omitted the limit parameter and used only the offset. This will allow the LimitIterator to begin at the offset and traverse to the end of the structure. We have also accessed the inner iterator (ArrayIterator) with the getInnerIterator() method and called ArrayIterator::offsetUnset() method to remove the kiwi from our lives.

SplFileObject

The above codes creates an array and then loops through this array to print the lines and numbers. With the advent of SplFileObject we can treat our file as though it were an object and use SPL iterators to traverse the file.

Now we have a nice Object Oriented approach that should be familiar if you have read the rest of this tutorial. If follows the same standard approach. This is the true power of SPL in giving us flexibility within a constrained and standardised development environment. Lets make our code a little faster with foreach.

Of course the SplFileObject does not limit us in our using of all the filesystem functions we have been acustom to in the past. Like the filesystem functions we have great flexibility in how we manipulate our file data. Here we see an example using seek():

To see a list of all the avaiable methods for SplFileObject we once again simply do this:

The above snippet will produce a list featuring these methods.

• __construct
• getFilename
• isDot
• rewind
• valid
• key
• current
• next
• __toString
• getPath
• getPathname
• getPerms
• getInode
• getSize
• getOwner
• getGroup
• getATime
• getMTime
• getCTime
• getType
• isWritable
• isReadable
• isExecutable
• isFile
• isDir
• isLink
• getFileInfo
• getPathInfo
• openFile
• setFileClass
• setInfoClass

If you have read the chapter on the Directory Iterator then, this list will be familiar to you from the SplFileInfo iterator. The SplFileObject extends SplFileInfo. It is defined as such:
class SplFileObject extends SplFileInfo implements RecursiveIterator, SeekableIterator
Because the SplFileObject extends SplFileInfo all those class methods are avaliable to it, plus the added goodness of the recursive Iterator and the Seekable Iterator. This makes for some exciting functionality not otherwise available with the SplFileInfo class alone.

Conclusions

As shown in these examples, SPL provides us with a toolkit to iterate over almost any aggregate structure, The benifits of this is that it is a Standard and so can be used by all to provide better coding practices. You will see often in you code that much of it is based on creating and traversing aggregate stuctures as those shown above. We hope this gets you started on your way to implementing this in your code base. For more information there is always the PHP manual section on SPL

Credits

Many thanks to Marcus Boerger for his help with the code in this tutorial and quick fixes to bugs in the PHP 5.1.0 core as we came across them. Marcus is a PHP core developer and the creator of SPL. He has provided excellent docs that show the inner workings of SPL at http://www.php.net/~helly/php/ext/spl/.