Lesson 2 - Working with text files in PHP - Online course

In the previous lesson, Introduction to work with files in PHP , we learned what types of files exist and how to work with paths to those files. In this lesson, we will also look at how to work with unstructured plain text in PHP.

Although we will focus primarily on working with unstructured text files in this lesson, the functions we will learn to use here will be used in other lessons when we work with structured files too.

Ways to read and write files in PHP

There are two ways to read and write files in PHP:

• using single-purpose functions and
• using resources.

The advantage of the first method is its simplicity and speed. PHP has functions, that can read or write the entire contents of a file when called. However, if we want to work with sections of large files or work with a CSV file directly during reading and writing to it, this abstraction turns into a disadvantage. In these cases, we use resources. However, we will get acquainted with the second method in the next lesson.

Working with files using single-purpose functions

We will now get familiar with single-purpose functions.

file_put_contents() - writing a string to a file

Before we learn to read a file, let's learn how to create such a file and how to write some text in it. file_put_contents() is used to write a string to a file. The first argument takes a path to a file that we want to write to and the second argument is the text string that we want to write. If the target file does not exist, PHP will try to create it:

$file = "my_text.txt";
$text = "Hello!<br>\nThis is the text, that'll appear in our file. :-)";

file_put_contents($file, $text);

The contents of the my_text.txt file after running the script should be as follows:

Hello!<br>
This is the text, that'll appear in our file :-)

Error handling

Errors can occur during program execution, and programs working with files are no exception. The file_put_contents() returns the number of bytes written, but if an error occurs, it returns a boolean value of false. In the example above, the code for writing to the file should look like this:

$result = file_put_contents($file, $text);

if($result === FALSE) {
  echo "An error occurred while writing to the file !";
} else {
  echo "The File was successfully written!<br>Written bytes count: ", $result;
}

The browser should show you this:

In case of an error, the following message should appear:

We can notice that we use the === operator, or the strict comparison operator, to compare the return value and the boolean value false. It ensures that the values being compared must not only be "same", but must also be of the same data type. This is important because the file_put_contents() function could "write" even 0 bytes, which does not necessarily indicate an error case. If we use the == operator (loose comparison operator), which we probably already know well, PHP, as a weakly typed language, would evaluate that 0 == false and we would have a hard-to-find bug in our program.:-)

Write error due to insufficient permissions

If we run the script on our own server and it ends with an error, the script probably does not have permission to write to the file. If the file already exists, we must grant the user account under which PHP is running write permission to the file. If the file does not exist yet, the user must be given write access to the folder in which the file will be created. If our server uses the Linux operating system, the issue of permissions is discussed in the lesson Linux Terminal (Bash) - Permissions, Installation and Processes in the course Linux Basics:-)

Adding content to a file (append mode)

If the file already exists and has some content, function file_put_contents() deletes it and creates a new file by default. If we wanted to create a guest book, this behaviour would be undesirable. However, the function offers us an append mode, in which new content is added to the end of the existing one. We can use this mode by passing the FILE_APPEND constant to the function as the third argument:

$result = file_put_contents($file, $text, FILE_APPEND);

File locking

If we had a lot of visitors on our website and everyone tried to write something to the same file, it could happen that writing to it took place more times at once and our file would be damaged. We can prevent this by passing the LOCK_EX constant as the third argument to the function. The write operation will be atomic as follows (i.e. all writes will take place one after the other, not at once):

$result = file_put_contents($file, $text, LOCK_EX);

If we want to combine append mode with locking, we combine the two constants using the bitwise OR (|) operator:

$result = file_put_contents($file, $text, FILE_APPEND | LOCK_EX);

file_get_contents() - reading a file into a string

We already created the file, so we can now read it. The file_get_contents() takes the contents of the file whose path we pass in the first argument, reads it whole, and returns its contents to us as a string. All you need to do is passing a single argument, which is the file name. The function returns either the read data as a string or false in case of an error:

$file = "my_text.txt";

$text = file_get_contents($file);

if($text === FALSE) {
  echo "An error occurred while reading the file!";
} else {
  echo "The file was successfully loaded!<br />File contents:<br />", $text;
}

The output of the script will look like this:

Since an empty string is also taken as false, the === operator is used here to check for errors.

file() - reading a file line by line into an array

The file() function works in the same way as file_get_contents(), except that it does not read the contents of the file into a string, but divides it into lines and returns an array of those lines. For example, if we had comments about our article stored in a file and each of them was on a separate line, this function would be more useful than file_get_contents(), because we would probably like to wrap individual comments in some HTML tags before outputting them, etc .:

$file = "my_text.txt";

$lines = file($file);

if($lines === FALSE) {
  echo "An error occurred while reading the file !";
} else {
  foreach($lines as $i => $line) {
    echo "Line n. ", ($i + 1), ": ", $line, "<br />";
  }
}

Output:

readfile() - outputting a file directly to the browser

Sometimes we may not want to process the content of a text file in any way and just want to output it to a visitor of our website. The advantage of the readfile() function over the previously mentioned ones is that it can work with very large files. There is no intermediate step in the form of writing text to a variable (= to RAM), which has a limited size compared to disks. For example, if we wanted to output a database with several gigabytes in size, we would not be able to do so with the previously mentioned functions, but readfile() function would make it possible:-) :

$file = "my_text.txt";

$result = readfile($file);

if($result === FALSE) {
  echo "An error occurred while outputting the file!";
} else {
  echo "<br /><br /The file was outputted!<br />Outputted bytes: ", $result;
}

Output:

As we can see, the variable $result will only contain the number of bytes read, while the content of the file itself ends up in the browser:-)

The source code with the examples from this lesson can be downloaded below.

In the next lesson, Working with CSV files in PHP , we will learn to work with files using resources and with structured files in CSV format. We will apply the knowledge in a practical example - a simple web task:-)

 

Did you have a problem with anything? Download the sample application below and compare it with your project, you will find the error easily.