Chapter 19. Directories

19.1. Introduction

A filesystem stores a lot of additional information about files aside from their actual contents. This information includes such particulars as the file's size, what directory it's in, and access permissions for the file. If you're working with files, you may also need to manipulate this metadata. PHP gives you a variety of functions to read and manipulate directories, directory entries, and file attributes. Like other file-related parts of PHP, the functions are similar to the C functions that accomplish the same tasks, with some simplifications.

Files are organized with inodes . Each file (and other parts of the filesystem, such as directories, devices, and links) has its own inode. That inode contains a pointer to where the file's data blocks are as well as all the metadata about the file. The data blocks for a directory hold the names of the files in that directory and the inode of each file.

PHP provides two ways to look in a directory to see what files it holds. The first way is to use opendir( ) to get a directory handle, readdir( ) to iterate through the files, and closedir( ) to close the directory handle:

$d = opendir('/usr/local/images') or die($php_errormsg);
while (false !== ($f = readdir($d))) {
    // process file
}
closedir($d);

The second method is to use the directory class. Instantiate the class with dir( ), read each filename with the read( ) method, and close the directory with close( ):

$d = dir('/usr/local/images') or die($php_errormsg);
while (false !== ($f = $d->read())) {
    // process file
}
$d->close();

Recipe 19.8 shows how to use opendir( ) or dir( ) to process each file in a directory. Making new directories is covered in Recipe 19.11 and removing directories in Recipe 19.12.

The filesystem holds more than just files and directories. On Unix, it can also hold symbolic links. These are special files whose contents are a pointer to another file. You can delete the link without affecting the file it points to. To create a symbolic link, use symlink( ):

symlink('/usr/local/images','/www/docroot/images') or die($php_errormsg);

This creates a symbolic link called images in /www/docroot that points to /usr/local/images.

To find information about a file, directory, or link you must examine its inode. The function stat( ) retrieves the metadata in an inode for you. Recipe 19.3 discusses stat( ). PHP also has many functions that use stat( ) internally to give you a specific piece of information about a file. These are listed in Table 19-1.

Table 19-1. File information functions

Function name	What file information does the function provide?
file_exists( )	Does the file exist?
fileatime( )	Last access time
filectime( )	Last metadata change time
filegroup( )	Group (numeric)
fileinode( )	Inode number
filemtime( )	Last change time of contents
fileowner( )	Owner (numeric)
fileperms( )	Permissions (decimal, numeric)
filesize( )	Size
filetype( )	Type (fifo, char, dir, block, link, file, unknown)
is_dir( )	Is it a directory?
is_executable( )	Is it executable?
is_file( )	Is it a regular file?
is_link( )	Is it a symbolic link?
is_readable( )	Is it readable?
is_writable( )	Is it writeable?

On Unix, the file permissions indicate what operations the file's owner, users in the file's group, and all users can perform on the file. The operations are reading, writing, and executing. For programs, executing means the ability to run the program; for directories, it's the ability to search through the directory and see the files in it.

Unix permissions can also contain a setuid bit, a setgid bit, and a sticky bit. The setuid bit means that when a program is run, it runs with the user ID of its owner. The setgid bit means that a program runs with the group ID of its group. For a directory, the setgid bit means that new files in the directory are created by default in the same group as the directory. The sticky bit is useful for directories in which people share files because it prevents nonsuperusers with write permission in a directory from deleting files in that directory unless they own the file or the directory.

When setting permissions with chmod( ) (see Recipe 19.4), they must be expressed as an octal number. This number has four digits. The first digit is any special setting for the file (such as setuid or setgid). The second digit is the user permissions — what the file's owner can do. The third digit is the group permissions — what users in the file's group can do. The fourth digit is the world permissions — what all other users can do. To compute the appropriate value for each digit, add together the permissions you want for that digit using the values in Table 19-2. For example, a permission value of 0644 means that there are no special settings (the 0), the file's owner can read and write the file (the 6, which is 4 (read) + 2 (write)), users in the file's group can read the file (the first 4), and all other users can also read the file (the second 4). A permission value of 4644 is the same, except that the file is also setuid.

Table 19-2. File permission values

Value	Permission meaning	Special setting meaning
4	Read	setuid
2	Write	setgid
1	Execute	sticky

The permissions of newly created files and directories are affected by a setting called the umask, which is a permission value that is removed, or masked out, from the initial permissions of a file (0666 or directory (0777). For example, if the umask is 0022, the default permissions for a new file created with touch( ) or fopen( ) are 0644 and the default permissions for a new directory created with mkdir( ) are 0755. You can get and set the umask with the function umask( ). It returns the current umask and, if an argument is supplied to it, changes the umask to the value of that argument. For example, here's how to make the permissions on newly created files prevent anyone but the file's owner (and the superuser) from accessing the file:

$old_umask = umask(0077);
touch('secret-file.txt');
umask($old_umask);

The first call to umask( ) masks out all permissions for group and world. After the file is created, the second call to umask( ) restores the umask to the previous setting. When PHP is run as a server module, it restores the umask to its default value at the end of each request. Like other permissions-related functions, umask( ) doesn't work on Windows.