6.1 Before and After: Using Iterators

This section shows you how to use and write basic iterators. It begins by comparing directory iteration with and without an iterator and then shows you how to write a DirectoryIterator in PHP.

All the directory iteration examples process the set of files shown in Figure 6-1.

Figure 6-1. Files located in /www/www.example.com/

6.1.1 PHP 4: Reading Files in a Directory

In PHP 4, you read files by using opendir( ) , readdir( ) , and closedir( ) :

 $dir = opendir('/www/www.example.com/'); while (false !=  = ($file = readdir($dir))) {     print "$file\n"; } closedir($dir);  .   ..   email.html   images   includes   index.html   search.html  

The opendir( ) function returns a directory handle. Then, you usually pass the handle to readdir( ) inside a while loop. When iteration is complete, you clean up with closedir( ) .

As noted in the introduction, this looks simple, but you can run into problems if you're not careful. The check inside the while cannot be $f = readdir($d) , because then a file named would terminate the loop.

The results from the preceding code include files of all types, including directories. To filter out directories, call is_file( ) on the results:

 $d = '/www/www.example.com/'; $dir = opendir($d); while (false !=  = ($file = readdir($dir))) {     if (is_file($d . DIRECTORY_SEPARATOR . $file)) {         print "$file\n";     } } closedir($dir);  email.html   index.html   search.html  

Again, this check requires more subtlety than it should. If you don't use the PHP constant DIRECTORY_SEPARATOR and instead hardcode a slash, your script will break if it's run on a Windows machine.

6.1.2 PHP 5: Reading Files in a Directory

A better solution is to use the directory iterator class, DirectoryIterator . This class is part of SPL, so you don't need to include it before you use it.

DirectoryIterator takes a pathname as its constructor and then lets you loop through the files in the path :

 $dir = new DirectoryIterator('/www/www.example.com/'); foreach ($dir as $file) {     print "$file\n"; }  .   ..   email.html   images   includes   index.html   search.html  

This code produces the same output as the more complex while loop that uses the directory functions.

Also, eliminating directories doesn't require the use of a special PHP constant:

 $dir = new DirectoryIterator('/www/www.example.com/'); foreach ($dir as $file) {     if (! $file->isDir( )) {         print "$file\n";     } }  email.html   index.html   search.html  

Using the isDir( ) method neatly sidesteps the platform-specific issue since this detail is handled only once, inside the iterator itself.

6.1.3 DirectoryIterator Methods

The isDir( ) method is not the only method of the DirectoryIterator class. Other methods return the file's full path, the current path, and determine whether the file is a "dot." In Unix and Mac OS X, every directory automatically contains two special files named dot (.) and dot dot (..), which are links to the current directory and parent directory, respectively. If you're not careful, they can wreak havoc upon directory processing.

Table 6-1 lists some of the major DirectoryIterator methods.

Table 6-1. Important DirectoryIterator methods

Name	Return type	Description
getPath( )	String	Returns the opened path (e.g., /www/www.example.com )
getFilename( )	String	Returns the current filename (e.g., index.html )
getPathname( )	String	Returns the current path and file (e.g., /www/www.example.com/index.html )
isDir( )	Boolean	Determines whether the current file is a directory
isDot( )	Boolean	Determines whether the current file is a dot file (i.e., "." or "..")