Writing or Appending to a File

The processes for writing to and appending to a file are the samethe difference lies in the mode with which you call the fopen() function. When you write to a file, you use the mode argument "w" when you call fopen():

$fp = fopen("test.txt", "w");

All subsequent writing occurs from the start of the file. If the file doesn't already exist, it is created. If the file already exists, any prior content is destroyed and replaced by the data you write.

When you append to a file, you use the mode argument "a" in your fopen() call:

$fp = fopen("test.txt", "a");

Any subsequent writes to your file are added to the existing content, but if you attempt to append content to a nonexistent file, the file is first created.

Writing to a File with fwrite() or fputs()

The fwrite() function accepts a file resource and a string, and then writes the string to the file. The fputs() function works in exactly the same way.

fwrite($fp, "hello world");
fputs($fp, "hello world");

Writing to files is as straightforward as that. Listing 12.12 uses fwrite() to print to a file. We then append a further string to the same file using fputs().

Listing 12.12. Writing and Appending to a File

 1: <?php
 2: $filename = "test.txt";
 3: echo "<p>Writing to $filename ... </p>";
 4: $fp = fopen($filename, "w") or die("Couldn't open $filename");
 5: fwrite($fp, "Hello world\n");
 6: fclose($fp);
 7: echo "<p>Appending to $filename ...</p>";
 8: $fp = fopen($filename, "a") or die("Couldn't open $filename");
 9: fputs($fp, "And another thing\n");
10: fclose($fp);
11: ?>

The screen output of this script, when run from your Web browser, is

Writing to test.txt ...

Appending to test.txt ...

If you open the test.txt file or use readlines.php to read its contents, you'll find the file now contains:

Hello world

And another thing

Locking Files with flock()

The techniques you just learned for reading and amending files work fine if only a single user is accessing your script. In the real world, however, you'd expect many users to access your Web site, and the scripts within it, at more or less the same time. Imagine what would happen if two users were to execute a script that writes to one file at the same momentthe file would quickly become corrupt.

PHP provides the flock() function to forestall this eventuality. The flock() function locks a file, to warn other processes against writing to or reading from that file while the current process is working with it. The flock() function requires a valid file resource from an open file, and an integer representing the kind of lock you want to set. PHP provides predefined constants for each of the integers you're likely to need. Table 12.1 lists three kinds of locks you can apply to a file.

Table 12.1. Integer Arguments to the flock() Function

Constant	Integer	Lock Type	Description
LOCK_SH	1	Shared	Allows other processes to read the file but prevents writing (used when reading a file)
LOCK_EX	2	Exclusive	Prevents other processes from either reading from or writing to a file (used when writing to a file)
LOCK_UN	3	Release	Releases a shared or exclusive lock

You should call flock() directly after calling fopen(), then call it again to release the lock before closing the file. If the lock is not released, you will not be able to read from or write to the file. Here is an example of this seqence of events:

$fp = fopen("test.txt", "a") or die("Couldn't open file.");
flock($fp, LOCK_EX); // create exclusive lock
// write to the file
flock($fp, LOCK_UN); // release the lock
fclose($fp);