Working with Directories

Now that you can test, read, and write to files, let's turn our attention to directories. PHP provides many functions for working with directories. Let's look at how to create, remove, and read from them.

Creating Directories with mkdir()

The mkdir() function enables you to create a directory. The mkdir() function requires a string that represents the path to the directory you want to create and an octal number integer that represents the mode you want to set for the directory. Remember, you specify an octal (base 8) number using a leading 0, for example, 0777 or 0400.

The mode argument has an effect only on UNIX systems. The mode should consist of three numbers between 0 and 7, representing permissions for the directory owner, group, and everyone, respectively. The mkdir() function returns true if it successfully creates a directory, or false if it doesn't. If mkdir() fails, it's usually because the containing directory has permissions that preclude processes with the script's user ID from writing.

If you're not comfortable setting UNIX directory permissions, you should find that one of the following examples fits your needs. Unless you really need your directory to be world-writable, you should probably use 0755, which allows the world to read your directory but not to write to it.

mkdir("testdir", 0777); // global read/write/execute permissions mkdir("testdir", 0755); // world/group: read/execute; owner: read/write/execute

Removing a Directory with rmdir()

The rmdir() function enables you to remove a directory from the filesystem if the process running your script has the right to do so, and if the directory is empty. The rmdir() function requires only a string representing the path to the directory you want to delete.

rmdir("testdir");

Opening a Directory for Reading with opendir()

Before you can read the contents of a directory, you must first obtain a directory resource. You can do so with the opendir() function. The opendir() function requires a string that represents the path to the directory you want to open. The opendir() function returns a directory handle unless the directory isn't present or readable; in that case, it returns false.

$dh = opendir("testdir");

In this case, $dh is the directory handle of the open directory.

Reading the Contents of a Directory with readdir()

Just as you use the fgets() function to read a line from a file, you can use readdir() to read a file or directory name from a directory. The readdir() function requires a directory handle and returns a string containing the item name. If the end of the directory is reached, readdir() returns false. Note that readdir() returns only the names of its items, rather than full paths. Listing 13.13 shows the contents of a directory.

Listing 13.13. Listing the Contents of a Directory with readdir()

 1: <?php  2: $dirname = ".";  3: $dh = opendir($dirname) or die("couldn't open directory");  4:  5: while (!(($file = readdir($dh)) === false ) ) {  6:     if (is_dir("$dirname/$file")) {  7:            echo "(D) ";  8:     }  9:     echo $file."<br/>"; 10: } 11: closedir($dh); 12: ?>

If this code were saved to the document root of your web server as readdir.php and run through your web browser, the output could look something like Figure 13.7.

Figure 13.7. Output of readdir.php.

We open our directory for reading with the opendir() function on line 3 and use a while statement to loop through each of its elements, beginning on line 5. We call readdir() as part of the while statement's test expression and assign its result to the $file variable.

Within the body of the while statement, we use the $dirname variable in conjunction with the $file variable to create a full file path, which we then test on line 6. If the path represents a directory, we print (D) to the browser on line 7. Finally, we print the filename (or directory name) on line 9.

Listing 13.13 used a cautious construction in the test of the while statement. Most PHP programmers (myself included) would use something like the following:

while ($file = readdir($dh)) {       echo $file."<br/>"; }

In this case, the value returned by readdir() is tested and, because any string other than "0" resolves to true, there should be no problem. Imagine, however, a directory that contains four files: 0, 1, 2, and 3. On my system, the output from the preceding code is as follows:

. ..

When the loop reaches the file named 0, the string returned by readdir() resolves to false, which causes the loop to end. The approach in Listing 13.13 uses === to check that the return value returned by readdir() is not exactly equivalent to false. The result 0 only resolves to false in the test, so we circumvent the problem.

By the Way

If you find the ordering of items in a directory listing to be arbitrary, it's because the order is determined by the filesystem. If you want the items ordered in a specific fashion, you must read the contents into an array, which can then be sorted to your liking and subsequently displayed.