8.1 Using the Streams API

This section covers reading and writing files using the streams functions. For now, the examples only use the file wrapper, which is for local files. Other wrappers, along with their different configuration options, are covered in the next section. However, due to the miracle of streams, you won't need to learn any new functions to use those new wrappers.

The syntax for specifying a stream is scheme :// target . The scheme can be the name of any installed wrapper, such as file or http . The target varies depending upon the wrapper, but is usually a path to the file, with an optional hostname if applicable . For instance, to reference the local file /www/www.example.com/index.html , use file:///www/www.example.com/index.html .

The best way to read the entire contents of a stream into a variable is the file_get_contents( ) function. For example:

 // get the index page $index = file_get_contents('file:///www/www.example.com/index.html'); // short hand syntax for above $index = file_get_contents('/www/www.example.com/index.html'); 

These examples locate the file /www/www.example.com/index.html on the hard drive, read its contents, and place them in the $index variable. Since the file wrapper is the default wrapper for file_get_contents( ) , you can omit it for brevity.

You can make file_get_contents( ) also search your include_path . To enable this feature, pass true as the second argument:

 $classes = file_get_contents('classes.php', true); 

Now instead of looking only in the current directory, file_get_contents( ) also works through the include hierarchy, so its behavior is identical to include .

The file_get_contents( ) function respects read permissions and PHP's internal access restrictions, such as open_basedir . Trying to read in a restricted file causes PHP to produce a warning:

 $forbidden = file_get_contents("/etc/shadow");  PHP Warning:  file_get_contents(/etc/shadow): failed to open stream:   Permission denied  

In these cases, file_get_contents( ) returns false .

While file_get_contents( ) is the most efficient way to retrieve an entire file, a large file will use up lots of memory. If you don't need to access the entire file at once, use fopen( ) instead:

 $stream = 'file:///www/www.example.com/index.html'; $handle = fopen($stream, 'rb'); $contents = ''; while (!feof($handle)) {     $data = fread($handle, 8192);     print $data; // or another function to handle the data } fclose($handle); 

The fopen( ) function returns a file handle, or file pointer, to the file. Passing this handle to file functions such as feof( ) , fread( ) , and fclose( ) makes them act upon your file.

This code, however, is far more complex because you need to worry about opening the file for read access and then looping through its contents one chunk at a time. You also need to check repeatedly if you've read the entire file. Therefore, unless you're manipulating very large files on a regular basis, it's best to always use file_get_contents( ) .

When you need to do the reverse (save a variable as a file), use file_put_contents( ) :

 file_put_contents('file:///www/www.example.com/index.html', $index); file_put_contents('/www/www.example.com/index.html', $index); 

These two functions place the contents of $index into /www/www.example.com/index.html .

The default behavior is to overwrite an existing file; however, you can make file_get_contents( ) append to a file by passing the FILE_APPEND constant as a third parameter:

 file_put_contents('/var/log/http/error_log', $error, FILE_APPEND); 

This adds the contents of $error to the end of /var/log/http/error_log .

An alternative method of sending data is fwrite( ) :

 $stream = '/www/www.example.com/index.html'; $handle = fopen($stream, 'wb'); fwrite($handle, $index); fclose($handle); 

This opens the stream for writing and sends the contents of $index to the file /www/www.example.com/index.html .