Opening a File: fopen

Being able to store and access data using files is a big advantage in PHP, and PHP comes with a set of file-handling functions built-in, as we're going to see in the remainder of this chapter. It all starts with the fopen function, which opens a file for reading or writing. Here's how you use this function in general:

 fopen (string filename, string mode [, int use_include_path [, resource zcontext]])

In this function call, filename is the name of the file you're opening, mode indicates how you want to open the file (for example, to read from it or to write to it), use_include_path may be set to 1 or trUE to specify that you want to search for the file in the PHP include path, and zcontext holds an optional file context (contexts modify or enhance the behavior of the data streams from and to files, and we're not going to deal with them in this book).

The mode parameter specifies the type of access you require to the stream. It may be any of the following:

`'r'`	Open for reading only.
`'r+'`	Open for reading and writing.
`'w'`	Open for writing only and truncate the file to zero length. If the file does not exist, attempt to create it.
`'w+'`	Open for reading and writing and truncate the file to zero length. If the file does not exist, attempt to create it.
`'a'`	Open for appending only. If the file does not exist, attempt to create it.
`'a+'`	Open for reading and writing, starting at the end of the file. If the file does not exist, attempt to create it.
`'x'`	Create and open for writing only. If the file already exists, the `fopen` call will fail by returning `FALSE`.
`'x+'`	Create and open for reading and writing. If the file already exists, the `fopen` call will fail by returning `FALSE`.

Note that different operating systems have different line-ending conventions. When you write a text file and want to insert a line break, you need to use the correct line-ending character(s) for your operating system. Unix-based systems use \n as the line-ending character, Windows-based systems use \r\n as the line-ending characters, and Macintosh-based systems use \r as the line-ending character. (PHP has a constant named PHP_EOL that holds the line-ending character for the system you are on.)

In Windows, you can use a text-mode translation flag ('t'), which will translate \n to \r\n when working with the file. In contrast, you can also use 'b' to force binary mode, which will not translate your data. To use these flags, specify either 'b' or 't' as the last character of the mode parameter, such as 'wt'.

Currently, the default mode is set to binary for all platforms that distinguish between binary and text mode. If you are having problems with your scripts, try using the 't' flag.

Here's an example, which opens the file /home/file.txt for reading:

 $handle = fopen("/home/file.txt", "r");

When you open a file, you get a file handle, which represents an open file. From then on, you use this handle to work with the file. Now that the file has been opened, you can read from it using the various data-reading functions we'll cover in a few pages, such as fread.

This example opens a file for writing to using text mode, the default:

 $handle = fopen("/home/file.txt", "w");

This example opens a file for binary writing:

 handle = fopen("/home/file.txt", "wb");

In Windows, you should be careful to escape any backslashes used in the path to the file (or use forward slashes):

 $handle = fopen("c:\\data\\file.txt", "r");

You're not limited to files in the local file system, either. Here's how you might open a file on a different web site, as specified by URL:

 $handle = fopen("http://www.superduperbigco.com/file.txt", "r");

You can also open files using the FTP protocol:

 $handle = fopen("ftp://user:password@superduperbigco.com/file.txt", "w");

As mentioned, when you open a file, you get a file handle to work with, and you can pass that file handle to other file functions to work with the file. We'll take a look at those other functions in the following chunks.