As you work through this chapter, keep in mind that your ability to

access files on a local computer or network depends on the security

permissions that have been granted to the files and to the directories

where they are stored. The owner of a resource, such as a file or direc-

tory, can usually grant permission to access the resource. The owner

Is typically the person who created the resource. Otherwise, the net-

work administrator is in charge of granting permissions to resources.

Typical permissions include the abilities to read, write, modify, and

execute. For example, you might have permission to read a file, but

not to write to it. The procedures for manually granting permissions

to resources depend on the server’s operating system.

Changing Permissions

PHP provides the chmod() function for changing the permissions of a

file within PHP. The name “chmod” is a contraction of “change mode”;

mode is another word for permissions. The syntax for the chmod()

function is chmod(filename, mode), where filename is the name of

the file to change, and mode is an integer specifying the permissions

for the file. The value of mode defines three types of permission (read,

write, and execute) for three levels of access (the file’s owner or user,

users in the group associated with the file, and all other users).

The easiest way to ensure that the proper permissions are set is to

always use a four-digit octal (base 8) value when assigning permis-

sions—octal values encode three bits per digit, which matches the three

permission bits per level of access. When PHP parses a numeric value

that contains a leading zero, the number is assumed to be in octal for-

mat, so the leftmost digit should be 0. The remaining digits are assigned

a value, as indicated in Table 5-2. To assign more than one permission

for an access level, add the values for the permissions together.

First Digit

(Leftmost)

Always 0

0

0

0

Fourth Digit

(Rightmost)

Other (o)

4

2

1

Permissions

Read (r)

Write (w)

Execute (x)

Table 5-2

Second Digit

User (u)

4

2

1

Third Digit

Group (g)

4

2

1

Octal values for the mode parameter of the chmod() function

For example, the following code assigns read, write, and execute

permissions to the user, read and execute permissions to the group,

and no permissions for others for the file example.exe:

chmod("example.exe", 0750);

The following example assigns read permissions to all users, but only

gives the user permission to write to the index.html file:

chmod("index.html", 0644);

Write

237

The same permission bits apply to directories as well as files, but

the interpretation of the permissions is slightly different. “Read”

permission for a directory means that the user can list the files in a

directory. “Write” permission means that the user can add new files

to the directory. “Execute” permission means that the user can access

the files in the directory (assuming that the user has permissions for

the file itself ).

Checking Permissions

For reading the permissions associated with a particular file, PHP

provides the fileperms() function. This function takes a filename as

the only parameter, and returns an integer bitmap of the permissions

associated with the file. As with the chmod() function, the results will

be more meaningful when displayed in octal rather than decimal.

You can use PHP’s decoct() function to convert a decimal value to

an octal value. Also, because the fileperms() function contains more

information than just the file permissions, the permissions can be

extracted by using the arithmetic modulus operator (%) with an octal

value of 01000. (Remember that the leading 0 indicates to PHP that

the value is in octal.)

$perms = fileperms($testfile);

$perms = decoct($perms % 01000);

echo "file permissions for $testfile: 0" . $perms . "<br />\n";

As implied in

Short Quiz

1.

2.

Explain the difference between a binary file and a text file.

What are the different end-of-line markers for Windows,

Macintosh, and UNIX/Linux?

What functions are used to change and retrieve the

permissions of a file?

3.

Working with Files and Directories

4.

What are the three typical permissions for files and

directories?

What are the three levels of access for files and directories?

5.

238

Working with Directories

Before you learn more about working with files in PHP, you should

become familiar with how PHP works with directories. By knowing

how to create, read, and move between directories, you can examine

the changes that you make to files. PHP includes functions for read-

ing the contents of a directory and for creating new directories.

Reading Directories

With PHP, you can read the names of files and directories that exist

within any specified directory for which you have the appropriate

permissions. To read the contents of a directory, you use the PHP

functions listed in Table 5-3.

Function

chdir(directory)

chroot(directory)

Description

Changes to the specified directory

Changes the root directory of the

current process to the specified

directory

Closes a directory handle

Gets the current working directory

Opens a handle to the specified

directory

Reads a file or directory name from the

specified directory handle

Resets the directory pointer to the

beginning of the directory

Returns an indexed array containing

the names of files and directories in the

specified directory

closedir(handle)

getcwd()

opendir(directory)

readdir(handle)

rewinddir(handle)

scandir(directory[, sort])

Table 5-3

PHP directory functions

To iterate through the entries in a directory, you open a handle to

the directory with the opendir() function. A handle is a special type

of variable that PHP uses to represent a resource such as a file or

directory. You can then use the readdir() function to return the file

and directory names from the open directory. Each time you call the

readdir() function, it moves a directory pointer to the next entry

in the directory. A directory pointer is a special type of variable that

refers to the currently selected record in a directory listing. When you

first open the directory using the opendir() function, the directory

pointer is reset to the start of the directory listing. The directory

pointer is a way of keeping track of where you are in a directory. After

the directory pointer reaches the end of the directory, the readdir()

function returns a value of FALSE. The following code demonstrates

how to use the readdir() function to display the names of the files

in the PHP program directory. Notice that the readdir() function

is included as the conditional expression for the while statement. As

long as the readdir() function does not return a value of FALSE, the

while loop continues displaying the names of the directory entries.

Also notice at the end of the code that the directory handle is closed

with the closedir() function.

$Dir = "/var/html/uploads";

$DirOpen = opendir($Dir);

while ($CurFile = readdir($DirOpen)) {

echo $CurFile . "<br />\n";

239

When the PHP

To create a new Web page that displays the contents of the “files”

subdirectory:

1.

2.

Create a new document in your text editor.

Type the <!DOCTYPE> declaration, <html> element, header

information, and <body> element. Use the strict DTD and

“View Files” as the content of the

Add the following script section to the document body:

<?php

?>

3.

4.

Add the following code to the script section to read the files in

the “files” subdirectory. Notice that the while statement uses

the strcmp() function to exclude the “.” and “..” entries.

$Dir = "files";

$DirOpen = opendir($Dir);

while ($CurFile = readdir($DirOpen)) {

if ((strcmp($CurFile, '.') != 0) &&

Working with Files and Directories

5.

Save the document as ViewFiles.php in the Chapter direc-

tory for Chapter 5 and upload the file to the server.

Create a subdirectory named files under the Chapter direc-

tory for Chapter 5. Upload three files of your choosing to the

files subdirectory.

Open the ViewFiles.php file in your Web browser by entering

the following URL: http://<yourserver>/PHP_Projects/

Chapter.05/Chapter/ViewFiles.php. Figure 5-2 shows the out-

put for three files named kitten.jpg, polarbear.gif, and gorilla.gif.

6.

240

7.

Listing of the “files” subdirectory using the

8.

Figure 5-2

Close your Web browser window.

Starting with PHP 5.0, you can use the scandir() function, which

returns an indexed array containing the names of files and directories

in the specified directory, instead of using the opendir(), readdir(),

and closedir() functions. The following code shows how to display

the names of the files and directories in the PHP program directory.

Notice that this version does not use the opendir() or closedir()

functions. Instead, it just uses the scandir() function to return the

names of the entries in the PHP program directory to an array named

$DirEntries, which are then displayed with a foreach loop.

$Dir = "/var/html/uploads";

$DirEntries = scandir($Dir);

foreach ($DirEntries as $Entry) {

echo $Entry . "<br />\n";

When you use the readdir() function to return the entries in a

directory, the entries are not sorted, but instead are returned in the

order in which they are stored by your operating system. One benefit

of using the scandir() function instead of the readdir() function

is that the scandir() function sorts the returned entries in ascend-

ing alphabetical order. If you pass a value of 1 as a second argument

to the scandir() function, as shown in the following example, the

entries are sorted in descending alphabetical order:

$Dir = "/var/html/uploads";

$DirEntries = scandir($Dir, 1);

foreach ($DirEntries as $Entry) {

echo $Entry . "<br />\n";

241

To modify the ViewFiles.php script so it uses the scandir() function:

1.

2.

Return to the ViewFiles.php file in your text editor.

Replace the existing statements in the script section with the

following statements that use the scandir() function:

$Dir = "files";

$DirEntries = scandir($Dir);

foreach ($DirEntries as $Entry) {

if ((strcmp($Entry, '.') != 0) &&

3.

4.

Save the ViewFiles.php file and upload it to the server.

Open the ViewFiles.php file in your Web browser by enter-

ing the following URL: http://<yourserver>/PHP_Projects/

Chapter.05/Chapter/ViewFiles.php. Figure 5-3 shows the new

sorted list of files.

Figure 5-3

5.

Listing of the “files” subdirectory using the scandir() function

Close your Web browser window.

Creating Directories

You can use the mkdir() function to create a new directory. To cre-

ate a new directory within the current directory, simply pass the

name of the directory you want to create to the mkdir() function.

Working with Files and Directories

The following statement creates a new directory named “volunteers”

within the current directory:

mkdir("volunteers");

242

To create a new directory in a location other than the current direc-

tory, you can use a relative or absolute path. For example, the first

statement in the following code uses a relative path to create a new

directory named “event” at the same level as the current directory by

using the “..” notation to refer to the parent directory. The second

statement uses an absolute path to create a new directory named

“utilities” in the PHP program directory.

mkdir("../event");

mkdir("/bin/PHP/utilities");

If you attempt to create a directory that already exists, you will

receive an error like the one shown in Figure 5-4.

Figure 5-4

Warning that a directory already exists

You will also receive a warning if you attempt to create a new direc-

tory within a directory that doesn’t exist. In the next section, you will

learn how to check whether a directory exists before attempting to

access it or create a new directory within it.

Obtaining File and Directory Information

To successfully work with files and directories, you need to be able to

obtain information about them. Some of the most important infor-

mation about the file system includes whether the files and directo-

ries exist and whether you have the necessary permissions to work

with them. Table 5-4 lists the common PHP file and directory status

functions.

Function

file_exists(filename)

is_dir(filename)

is_executable(filename)

is_file(filename)

is_link(filename)

is_readable(filename)

is_writable(filename) or

is_writeable(filename)

Description

Determines whether a file or directory

exists

Determines whether a filename specifies

a directory

Determines whether a file is executable

Determines whether a filename specifies

a regular file

Determines whether a filename specifies

a symbolic link

Determines whether a file is readable

Determines whether a file is writable

243

Table 5-4

PHP file and directory status functions

The is_readable(), is_writable() (or is_writeable()), and

is_executable() functions check the permissions of a file or direc-

tory to determine whether the PHP scripting engine has read, write,

or execute permissions, respectively. The is_dir(), is_file(), and

is_link() functions are used to differentiate among the three most

common entries in a directory listing. A symbolic link, which is iden-

tified with the is_link() function, is a reference to another file else-

where on the system, not a file itself. Because each of these functions

return FALSE if a file does not exist, the file_exists() function does

not need to be used in conjunction with the other functions. By using

these functions before attempting to manipulate a file or directory,

you will ensure that the script runs correctly and does not produce

errors.

You can use the is_dir() function to check whether a specified

filename is a directory before attempting to access it. The following

example demonstrates how to use the is_dir() function before using

the scandir() function:

$Dir = "/var/html/uploads";

if (is_dir($Dir)) {

$DirEntries = scandir($Dir, 1);

Working with Files and Directories

PHP includes other types of functions that return additional informa-

tion about files and directories. Table 5-5 lists common file and direc-

tory information functions.

Function

244

fileatime(filename)

filectime(filename)

filemtime(filename)

fileowner(filename)

filesize(filename)

filetype(filename)

Description

Returns the last time the file was accessed

Returns the last time the file information was

modified

Returns the last time the data in a file was

modified

Returns the name of the file’s owner

Returns the size of the file in bytes

Returns the file type

Table 5-5

Common file and directory information functions

The file type returned by the filetype() function is a text string that

contains one of the following values: “fifo”, “char”, “dir”, “block”, “link”,

“file”, “socket”, or “unknown”. Most of these refer to special resource

The following code demonstrates how to use two of the functions

listed in Table 5-5: filesize() and filetype(). The script builds a

table that contains the filename, file size, and file type. Figure 5-5

shows the output.

$Dir = "/var/html/uploads";

if (is_dir($Dir)) {

echo "<table border='1' width='100%'>\n";

245

Figure 5-5

Output of a script with file and directory information functions

To create a more detailed directory listing:

1.

2.

Return to the ViewFiles.php file in your text editor.

Replace the existing statements in the script section with the

following statements that use the scandir() function:

$Dir = "files";

$DirEntries = scandir($Dir);

echo "<table border='1' width='100%' >\n";

echo "<tr><th colspan='4'>Directory listing for

<strong>" . htmlentities($Dir) . "</strong></th>

</tr>\n";

echo "<tr>";

echo "<th><strong><em>Name</em></strong></th>";

echo "<th><strong><em>Owner ID</em></strong></th>";

echo "<th><strong><em>Permissions</em></strong>

</th>";

echo "<th><strong><em>Size</em></strong></th>";

echo "</tr>\n";

foreach ($DirEntries as $Entry) {

if ((strcmp($Entry, '.') != 0) &&

Working with Files and Directories

$perms = decoct($perms % 01000);

echo "</td><td align='center'>

0$perms";

}

else

echo "</td><td colspan='2'

}

}

echo "</table>\n";

246

3.

4.

Save the ViewFiles.php file and upload it to the server.

Open the ViewFiles.php file in your Web browser by entering

the following URL: http://<yourserver>/PHP_Projects/

Chapter.05/Chapter/ViewFiles.php. Figure 5-6 shows the

expanded list of files.

Figure 5-6

5.

A detailed listing of the “files” subdirectory

Close your Web browser window.

Short Quiz

1.

What three functions are used to iterate through files and

directories in a specific directory?

What function returns an indexed array containing the names

of files and directories in the specified directory?

What is one benefit of using the scandir() function versus

the readdir() function?

2.

3.

4.

5.

What function is used to create a directory?

What two functions are used to determine if a directory entry

is a file or a directory?

247

Uploading and Downloading Files

Sometimes, a Web application allows visitors to upload files from

their local computer, referred to as the client, to the Web server.

More often, a Web site or application allows visitors to download files

from the Web server to their client. Depending on the specific Web

application, the files may be simple text files or they may be more

complex file types, such as images, documents, or spreadsheets. This

section describes how to upload and download files.

Uploading Files

Visitors using a Web application often want to customize pages with

custom graphics. For example, a registered member of a social net-

working Web site may want to post pictures on a profile page. Other

users may want to upload documents to be used for online collabora-

tion and review. PHP provides a method for transferring files from a

user’s client machine to the Web server.

Selecting the File

Files are uploaded in PHP through forms. The form’s method attribute

must be “POST” for a file to be uploaded. An additional attribute,

named enctype, must be added to the opening <form> tag, and must

be set to “multipart/form-data”. This instructs the Web browser to

post multiple sections, one for the regular form data and one for the

file contents.

An input field of type “file” within the form presents the user with a

file selection control. Using this control, the user can enter the full

path and name of the file to be uploaded. Most modern Web brows-

ers also provide a “Browse” button, which allows the user to navigate

to the appropriate file using a “file select” dialog box. A separate “hid-

den” input field may be included to set the maximum allowed size of

the uploaded file. This input field must be named “MAX_FILE_SIZE”

(in all capital letters) and must precede the “file” input field within the

form. The input field should be of type “hidden” to prevent it from

being displayed or changed, and the value is set to the maximum

number of bytes allowed for the uploaded file.

Using the

It is a good

MIME stands

Working with Files and Directories

Retrieving the File Information

When the form is posted, information for the uploaded file is stored

in the $_FILES[] autoglobal array, which was introduced in Chapter

4. An associative array element is created for each “file” input field

name. The associative key of the element is the name of the input field

from the form. The array element is a nested associative array con-

taining the information about the uploaded file. Table 5-6 shows the

keys of the nested associative array elements and describes the values

for those keys.

Key

'error'

'tmp_name'

'name'

'size'

'type'

248

Value

The error code associated with the file upload; an error

code of 0 indicates a successful upload

The temporary location of the file contents

The original filename

The file size (in bytes)

The file’s MIME type, as specified by the client’s Web

browser

The nested array keys of a $_FILES[] autoglobal array element

Table 5-6

The

To retrieve the information from the $_FILES[] autoglobal array,

use the syntax $_FILES[filefield][key], where filefield is replaced

with the name of the “file” input element on the Web form and key is

replaced by the appropriate key from Table 5-6. For example, assume

that the Web form’s <input> field was declared as follows:

<input type="file" name="picture_file" />

In the form handler, the $_FILES[] autoglobal array would contain

one element, $_FILES['picture_file'], which in turn contains the

following five elements:

$_FILES['picture_file']['error'] /* Contains the error code

associated with the file */

Storing the Uploaded File

As described in the previous section, the uploaded file is stored to

a temporary location on the Web server. The file then needs to be

moved to a more permanent location elsewhere in the directory

structure.

There are some important considerations when determining the des-

tination of the uploaded file. The first is whether uploaded files should

be immediately available or if they need to be verified first. If the file

needs to be verified to ensure that it is virus-free, or of the appropri-

ate type, to list just two reasons, then the file should be stored in a

“sandbox” area outside the publicly accessible Web folders. The sec-

Once you determine the destination, use the move_uploaded_file()

function to move the uploaded file from its temporary location to the

permanent destination. The syntax for the function is:

bool move_uploaded_file(filename, destination)

249

Where filename is the contents of $_FILES[filefield]['tmp_name']

and destination is the path and filename of the location where the

file will be stored. The function returns TRUE if the move succeeds,

and FALSE if the move fails.

For example, to move the temporary file uploaded using the “picture_

file” input field into the “uploads” subdirectory of the current direc-

tory using the file’s original name, you would use the following code:

if (move_uploaded_file($_FILES['picture_file']['tmp_name'],

"uploads/" . $_FILES['picture_file']['name']) ===

Working with Files and Directories

250

In the preceding example, notice the call to the chmod() function

before the “Successfully uploaded . . .” message is displayed. By default,

the uploaded file is owned by the user account that owns the Web

server process and has only owner “read” and “write” privileges

(0600). To ensure that you (and everyone else) can read the file, use

chmod(filename, 0644); after calling the move_uploaded_file()

function, replacing filename with the value that you used in the

destination parameter for the move_uploaded_file() function.

To create a form to upload a file:

1.

2.

Create a new document in your text editor.

Type the <!DOCTYPE> declaration, <html> element, header

information, and <body> element. Use the strict DTD and

“File Uploader” as the content of the

Add the following script section to the document body:

<?php

?>

3.

4.

Add the following code to the script section to read the files

in the “files” subdirectory. The associative array index for the

$_FILES autoglobal array is the name of the file input field

that will be used in the Web form ('new_file').

$Dir = "files";

if (isset($_POST['upload'])) {

if (isset($_FILES['new_file'])) {

5.

Add the following XHTML form immediately after the

closing PHP tag. Notice that the file input is named

“new_file”, which is the same value used earlier as the index

<form action="FileUploader.php" method="POST"

enctype="multipart/form-data">

<input type="hidden" name="MAX_FILE_SIZE"

value="25000" /><br />

File to upload:<br />

<input type="file" name="new_file" /><br />

(25,000 byte limit) <br />

<input type="submit" name="upload" value="Upload the

File" />

<br />

</form>

251

6.

Save the document as FileUploader.php in the Chapter

directory for Chapter 5 and upload the file to the server.

Verify that the “files” directory on the Web server has read,

write, and execute permissions enabled for user, group, and

other.

Open the FileUploader.php file in your Web browser by enter-

ing the following URL: http://<yourserver>/PHP_Projects/

Chapter.05/Chapter/FileUploader.php. Attempt to upload

a file to the server. You should receive a message stating

whether the upload succeeded or failed.

After you have successfully uploaded one or more files

to the server using the FileUploader.php form, open the

ViewFiles.php file in your Web browser by entering

the following URL: http://<yourserver>/PHP_Projects/

Chapter.05/Chapter/ViewFiles.php. You should see the

new files in the directory listing. Figure 5-7 shows the

output for a new file named seahorse.jpg along with the

kitten.jpg, polarbear.gif, and gorilla.gif files. Notice that the

Owner ID for seahorse.jpg is different from those for the

other three—seahorse.jpg was created by the user account

for the PHP scripting engine, while the others were created

by the account owner.

7.

For most

8.

9.

Working with Files and Directories

252

Figure 5-7

Listing of the “files” subdirectory after uploading seahorse.jpg

10. Close your Web browser window.

Downloading Files

Normally, it is not necessary to use PHP to download files from the

Web server. If a file is stored in a directory that is within the public

XHTML directory structure, you can provide an XHTML anchor

(<a>) tag in the Web page. The user clicks the link, and the Web

browser downloads the file automatically.

With files that do not reside within the public XHTML directory

structure, another method is required to download the file. PHP

provides the tools required to download a file from anywhere in the

directory structure.

The first step is to tell the PHP script which file to download. The

simplest way is with URL tokens and the $_GET[] autoglobal array.

This approach allows you to embed the download in a hyperlink

through an XHTML anchor (<a>) tag, similar to a standard down-

load. Because a PHP script is downloading the file, you have the

advantage of being able to include validation code within the script to

ensure that the user should be allowed to retrieve the file and that the

file is available before allowing the download.

The second step to downloading a file with PHP is to provide the

appropriate XHTML headers to tell the client Web browser that the

response contains more than just a Web page. Headers are infor-

mation sent to the Web browser from the Web server that tell the

browser about the data being sent. The types of headers to send are

listed in Table 5-7.

Header

Content-

Description

Content-Type

Description

Description of

the message

contents

MIME type and

subtype of

the message

contents

The attributes

of the attachment,

especially the

filename

The method

used to encode

the message

contents

The length of

the message

contents

Value

A text message

Example

header("Content-

Description:

File Transfer");

A MIME type/

subtype string

header("Content-Type:

application/force-

download");

253

Content-

Disposition

A series of

name/value

pairs defining

the attributes of

the file

header("Content-

Disposition:

attachment;

filename=\"list.txt\"");

Content-Transfer-

Encoding

header("Content-

Content-Length

Number

header("Content-

Length: 5000");

Table 5-7

Content headers for downloading a file