Testing Files

Before you work with a file or directory, you should learn more about it. PHP provides many functions that help you discover information about files on your system. This section briefly covers some of the most useful ones.

Checking for Existence with file_exists()

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

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

A File or a Directory?

You can confirm that the entity you are testing is a file, as opposed to a directory, with the is_file() function. is_file() requires the file path and returns a Boolean value:

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

Conversely, you might want to check that the entity you are 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" ) ) {
  print "/tmp is a directory";
}

Checking the Status of a File

When you know that a file exists, and it is what you expect it to be, you can then find out some things you can do with it. Typically, you might want to read, write to, or execute a file. PHP can help you with all these.

is_readable() 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. is_readable() accepts the file path as a string and returns a Boolean value:

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

is_writable() tells you whether you can write to a file. Once again, it requires the file path and returns a Boolean value:

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

is_executable() tells you whether you can run a 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" ) {
  print "test.txt is executable";
}

Determining File Size with filesize()

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

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

Getting Date Information About a File

Sometimes you will 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 when a file was last accessed with fileatime(). This function requires the file path and returns the date on which the file was last accessed. To access a file means either to read or write to it. Dates are returned from all these functions in Unix epoch format—that is, the number of seconds since January 1, 1970. In our examples, we use the date() function to translate this into human readable form. You'll learn more about date functions in Hour 16, "Working with Dates and Times."

$atime = fileatime( "test.txt" );
print "test.txt was last accessed on ";
print date("D d M Y g:i A", $atime);
// Sample output: Tue 19 Aug 2003 4:26 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, like so:

$mtime = filemtime( "test.txt" );
print "test.txt was last modified on ";
print date("D d M Y g:i A", $mtime);
// Sample output: Tue 19 Aug 2003 4:26 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" );
print "test.txt was last changed on ";
print date("D d M Y g:i A", $ctime);
// Sample output: Tue 19 Aug 2003 4:26 PM

Creating a Function That Performs Multiple File Tests

Listing 11.8 creates a function that brings the file test functions we have looked at together into one script.

Listing 11.8 A Function to Output the Results of Multiple File Tests

 1: <?php
 2: function outputFileTestInfo( $file ) {
 3:   if ( ! file_exists( $file ) ) {
 4:     print "$file does not exist<br/>";
 5:     return;
 6:   }
 7:   print "$file is ".(    is_file( $file )?"":"not ")."a file<br/>";
 8:   print "$file is ".(    is_dir( $file )?"":"not ")."a directory<br/>";
 9:   print "$file is ".(  is_readable( $file )?"":"not ")."readable<br/>";
10:   print "$file is ".(  is_writable( $file )?"":"not ")."writable<br/>";
11:   print "$file is ".( is_executable( $file )?"":"not")."executable<br/>";
12:   print "$file is ".( filesize($file))." bytes<br/>";
13:   print "$file was accessed on "
14:       .date( "D d M Y g:i A", fileatime( $file ) )."<br/>";
15:   print "$file was modified on "
16:       .date( "D d M Y g:i A", filemtime( $file ) )."<br/>";
17:   print "$file was changed on  "
18:       .date( "D d M Y g:i A", filectime( $file ) )."<br/>";
19: }
20: ?>
21: <!DOCTYPE html PUBLIC
22:   "-//W3C//DTD XHTML 1.0 Strict//EN"
23:   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
24: <html>
25: <head>
26: <title>Listing 11.8 Multiple File Tests</title>
27: </head>
28: <body>
29: <div>
30: <?php
31: outputFileTestInfo( "test.txt" );
32: ?>
33: </div>
34: </body>
35: </html>

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

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

We use the is_file() function as the right expression of the ternary operator. If this 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 ";
print "$f is $isit a file";

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

if ( is_file( $f ) ) {
  print "$fi is a file<br>";
} else {
  print "$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.