PHP Stream-based file IO


Example

Opening a stream

fopen opens a file stream handle, which can be used with various functions for reading, writing, seeking and other functions on top of it. This value is of resource type, and cannot be passed to other threads persisting its functionality.

$f = fopen("errors.log", "a"); // Will try to open errors.log for writing

The second parameter is the mode of the file stream:

ModeDescription
rOpen in read only mode, starting at the beginning of the file
r+Open for reading and writing, starting at the beginning of the file
wopen for writing only, starting at the beginning of the file. If the file exists it will empty the file. If it doesn't exist it will attempt to create it.
w+open for reading and writing, starting at the beginning of the file. If the file exists it will empty the file. If it doesn't exist it will attempt to create it.
aopen a file for writing only, starting at the end of the file. If the file does not exist, it will try to create it
a+open a file for reading and writing, starting at the end of the file. If the file does not exist, it will try to create it
xcreate and open a file for writing only. If the file exists the fopen call will fail
x+create and open a file for reading and writing. If the file exists the fopen call will fail
copen the file for writing only. If the file does not exist it will try to create it. It will start writing at the beginning of the file, but will not empty the file ahead of writing
c+open the file for reading and writing. If the file does not exist it will try to create it. It will start writing at the beginning of the file, but will not empty the file ahead of writing

Adding a t behind the mode (e.g. a+b, wt, etc.) in Windows will translate "\n" line endings to "\r\n" when working with the file. Add b behind the mode if this is not intended, especially if it is a binary file.

The PHP application should close streams using fclose when they are no longer used to prevent the Too many open files error. This is particularly important in CLI programs, since the streams are only closed when the runtime shuts down -- this means that in web servers, it may not be necessary (but still should, as a practice to prevent resource leak) to close the streams if you do not expect the process to run for a long time, and will not open many streams.

Reading

Using fread will read the given number of bytes from the file pointer, or until an EOF is met.

Reading lines

Using fgets will read the file until an EOL is reached, or the given length is read.

Both fread and fgets will move the file pointer while reading.

Reading everything remaining

Using stream_get_contents will all remaining bytes in the stream into a string and return it.

Adjusting file pointer position

Initially after opening the stream, the file pointer is at the beginning of the file (or the end, if the mode a is used). Using the fseek function will move the file pointer to a new position, relative to one of three values:

  • SEEK_SET: This is the default value; the file position offset will be relative to the beginning of the file.
  • SEEK_CUR: The file position offset will be relative to the current position.
  • SEEK_END: The file position offset will be relative to the end of the file. Passing a negative offset is the most common use for this value; it will move the file position to the specified number of bytes before the end of file.

rewind is a convenience shortcut of fseek($fh, 0, SEEK_SET).

Using ftell will show the absolute position of the file pointer.

For example, the following script reads skips the first 10 bytes, reads the next 10 bytes, skips 10 bytes, reads the next 10 bytes, and then the last 10 bytes in file.txt:

$fh = fopen("file.txt", "rb");
fseek($fh, 10); // start at offset 10
echo fread($fh, 10); // reads 10 bytes
fseek($fh, 10, SEEK_CUR); // skip 10 bytes
echo fread($fh, 10); // read 10 bytes
fseek($fh, -10, SEEK_END); // skip to 10 bytes before EOF
echo fread($fh, 10); // read 10 bytes
fclose($fh);

Writing

Using fwrite writes the provided string to the file starting at the current file pointer.

fwrite($fh, "Some text here\n");