Validating Files

Before you work with a file or directory within your code, it's often a good idea to learn more about it, and whether or not it actually exists is a pretty good start! PHP provides many functions to help you to discover information about files on your system. This section briefly covers some of the most useful functions.

Checking for Existence with file_exists()

You can test for the existence of a file with the file_exists() function. This function requires a string representation an absolute or relative path to a file, that might or might not be present. If the file is found, the file_exists() function returns TRue; otherwise, it returns false.

if (file_exists("test.txt")) {
        echo "The file exists!";
}

This is all well and good, but what if you're unsure if something is a file or a directory, and you really need to know? Read on!

A File or a Directory?

You can confirm that the entity you're testing is a file, as opposed to a directory, using the is_file() function. The is_file() function requires the file path and returns a Boolean value.

if (is_file("test.txt")) {
        echo "test.txt is a file!";
}

Conversely, you might want to check that the entity you're testing is a directory. You can do this with the is_dir() function. is_dir() requires the path to the directory and returns a Boolean value.

if (is_dir("/tmp")) {
        echo "/tmp is a directory";
}

Once you know a file or directory exists, you may need to test its permissions. You'll learn about this in the next section.

Checking the Status of a File

When you know that a particular entity exists, and it's what you expect it to be (either a directory or a file), you'll need to know what you can do with it. Typically, you might want to read, write to, or execute a file. PHP can help you determine if you can perform these operations.

The is_readable() function tells you whether you can read a file. On Unix systems, you might be able to see a file but still be barred from reading its contents, due to user permissions. This function accepts the file path as a string and returns a Boolean value.

if (is_readable("test.txt")) {
        echo "test.txt is readable";
}

The is_writable() function tells you whether you have the proper permission to write to a file. As with is_readable(), the is_writable() function requires the file path and returns a Boolean value.

if (is_writable("test.txt")) {
        echo "test.txt is writable";
}

The is_executable() function tells you whether you can execute the given file, relying on either the file's permissions or its extension, depending on your platform. It accepts the file path and returns a Boolean value.

if (is_executable("test.txt")) {
        echo "test.txt is executable";
}

Permission-related information isn't all you might need to know about a file. The next section shows how to determine the file size.

Determining File Size with filesize()

Given the path to a file, the filesize() function attempts to determine and return its size in bytes. It returns false if it encounters problems.

echo "The size of test.txt is.. ";
echo filesize("test.txt");

Finding the specific filesize is important in situations where you want to attach a file to an email or stream a file to the useryou'll need to know the size so as to properly create the headers (in the case of the email) or know when to stop sending bytes to the user (in the case of the stream). For more general purposes, you may want to get the file size so you can display it to the user before they attempt to download some monstrous application or high-resolution photograph from your site.

Getting Date Information About a File

Sometimes you need to know when a file was last written to or accessed. PHP provides several functions that can provide this information.

You can find out the last-accessed time of a file, using the fileatime() function. This function requires the file path and returns the date that the file was last accessed. To access a file means either to read or write to it. Dates are returned from all the date information functions in timestampthat is, the number of seconds since January 1, 1970. In our examples, we use the date() function to translate this into human-readable form.

$atime = fileatime("test.txt");
echo "test.txt was last accessed on ";
echo date("D d M Y g:i A", $atime);
// Sample output: Mon 23 Aug 2004 9:54 PM

You can discover the modification date of a file with the function filemtime(), which requires the file path and returns the date in Unix epoch format. To modify a file means to change its contents in some way.

$mtime = filemtime("test.txt");
echo "test.txt was last modified on ";
echo date("D d M Y g:i A", $mtime);
// Sample output: Mon 23 Aug 2004 9:50 PM

PHP also enables you to test the change time of a document with the filectime() function. On Unix systems, the change time is set when a file's contents are modified or changes are made to its permissions or ownership. On other platforms, the filectime() returns the creation date.

$ctime = filectime("test.txt");
echo "test.txt was last changed on ";
echo date("D d M Y g:i A", $ctime);
// Sample output: Mon 23 Aug 2004 9:45 PM

Creating a Function That Performs Multiple File Tests

Listing 12.7 creates a function that brings together the file-related functions we've just looked at into one script.

Listing 12.7. A Function to Output the Results of Multiple File Tests

 1: <?php
 2: $file = "test.txt";
 3: outputFileTestInfo($file);
 4:
 5: function outputFileTestInfo($f) {
 6:    if (!file_exists($f)) {
 7:        echo "<p>$f does not exist</p>";
 8:        return;
 9:    }
10:    echo "<p>$f is ".(is_file($f)?"":"not ")."a file</p>";
11:    echo "<p>$f is ".(is_dir($f)?"":"not ")."a directory</p>";
12:    echo "<p>$f is ".(is_readable($f)?"":"not ")."readable</p>";
13:    echo "<p>$f is ".(is_writable($f)?"":"not ")."writable</p>";
14:    echo "<p>$f is ".(is_executable($f)?"":"not ")."executable</p>";
15:    echo "<p>$f is ".(filesize($f))." bytes</p>";
16:    echo "<p>$f was accessed on ".date( "D d M Y g:i A",fileatime($f))."</p>";
17:    echo "<p>$f was modified on ".date( "D d M Y g:i A",filemtime($f))."</p>";
18:    echo "<p>$f was changed on ".date( "D d M Y g:i A",filectime($f))."</p>";
19: }
20: ?>

If this code were saved to the document root of your Web server as filetests.php and run through your Web browser, the output would look something like Figure 12.2 (provided you had a file called test.txt also in the document root).

Notice that we used the ternary operator as a compact way of working with some of these tests. Let's look at one such test, found in line 10, in more detail:

echo "<p>$f is ".(is_file($f)?"":"not ")."a file</p>";

We use the is_file() function as the left-side expression of the ternary operator. If it returns TRue, an empty string is returned. Otherwise, the string "not " is returned. The return value of the ternary expression is added to the string to be printed with concatenation operators. This statement could be made clearer, but less compact, as follows:

$is_it = is_file($f)?"":"not ";
echo $f." is ".$is_it." a file";

We could, of course, be even clearer with an if statement, but imagine how large the function would become if we used the following:

if (is_file($f)) {
        echo "$f is a file<br>";
} else {
        echo "$f is not a file<br>";
}

Because the result of these three approaches is the same, the approach you take becomes a matter of preference.