File Handling

Congratulations! You now know all about file handling in PHP. Here’s a recap of what you’ve learned:

- Use `fopen` with the correct mode to access a file for reading, writing, or appending.
- Close any files you’re not actively using with `fclose`.
- Read files with `fread` or `file_get_contents`.
- Write files with `fwrite` or `file_put_contents`.
- Retrieve information about files with operations like `filesize` and `file_exists`.
- Find and diagnose errors by checking function return values, inspecting the console for error messages, and using file information functions.

To learn even more about file handling in PHP, try exploring the [official PHP documentation for file system functions](https://www.php.net/manual/en/ref.filesystem.php). In the meantime, let’s wrap things up with one more exercise.

Review

Nice work! We can now read and write files in PHP. However, you might’ve noticed that most operations, including both reading and writing, can take quite a few steps. For example, here’s what it takes to read a file called `my-file.txt`:

```php
$name = "my-file.txt";
$file = fopen($name, "r");
$size = filesize($name);
$content = fread($file, $size);
fclose($file);
```

Wouldn’t it be nice if there was an easier way? Luckily, there is! PHP offers shorthand alternatives to `fread` and `fwrite` that take care of implementation details like opening the file and obtaining its size.

First, let’s take a look at an alternative to `fread` called `file_get_contents`. To try it out, let‘s refactor our example to use the function:

```php
$content = file_get_contents("my-file.txt");
```

This reads `my-file.txt` into `$content`, just as we did before — but with a fraction of the code. We only need one argument (the file name) and PHP takes care of the rest.

Likewise, PHP includes an alternative to `fwrite` called `file_put_contents`. This allows us to write to a file with just one function call:

```php
file_put_contents("hello.txt", "Hello, world!");
```

This opens `hello.txt` in write mode, writes “Hello, world!” to the file, and closes the file in one function call. Since the file is opened in write mode, any existing content will be erased from the file. However, if we’d like to append to the file instead, we can specify this by passing `FILE_APPEND` as the third argument:

```php
file_put_contents("cool-pets.txt", "Bailey", FILE_APPEND);
```

To let us customize its behavior, the `file_put_contents` function takes an optional third argument that can be set to one of a few values, including `FILE_APPEND`. These values, called flags, are constants included in the PHP language.

Now, let’s use `file_get_contents` and `file_put_contents` to refactor a PHP script that uses `fread` and `fwrite`!

Shorthand Functions

Now that we know how to open and close files, let’s take a look at how to read them. To demonstrate how this works, let’s say we have a file called `real-cool-file.txt` with the following text:

```
Wowsers!
```

First, we’ll need to open the file in read mode:

```php
$cool_file = fopen("real-cool-file.txt", "r");
```

Then, we can use the `fread` function to read the file:

```php
$cool_text = fread($cool_file, 4);
```

The `fread` function reads the given number of bytes from a file, returning the result as a string. Let’s take a closer look at how it works:

- The first argument, `$cool_file`, is the file pointer for the file we’d like to read.
- The second argument, `4`, is the number of bytes we’d like to read from the file. A byte is a unit of data stored on a computer. In this case, it is equivalent to one character of text.

Our code reads 4 bytes of text from `real-cool-file.txt` into `$cool_text`. If we were to then `echo $cool_text`, here’s what we would see in the console:

```
Wows
```

Since we read only the first 4 bytes, we’re seeing only the first 4 characters of the file. But, what about the rest? For `real-cool-file.txt`, we can count that the file contains 8 characters, meaning that we can read the entire file by reading 8 bytes:

```php
$cool_text = fread($cool_file, 8);
echo $cool_text; // Wowsers!
```

However, in practice, we won’t always know the exact number of bytes to read. We might work with files of varying sizes or with files that are too large to count manually. Fortunately, PHP gives us the `filesize` function to find out the size of any file. Here’s how:

```php
$cool_size = filesize("real-cool-file.txt");
```

The `filesize` function takes a file name as an argument, returning the size of the file in bytes. In this example, we used `filesize` to find the size of `real-cool-file.txt` and store the result in `$cool_size`. We can then use this variable with `fread` to read the entire file, even if we didn’t know the number of bytes to read in advance:

```php
$cool_text = fread($cool_file, $cool_size);
echo $cool_text; // Wowsers!
```

When we’re finished reading the file, we’ll close it with the `fclose` function:

```php
fclose($cool_file);
```

Now, it’s your turn! Let’s practice reading a file in PHP.

Reading a File

Depending on what we want to do with a file, the file handling process can vary. However, the first and last steps will always be the same; we will open the file first, and close it when we’re finished.

Let’s first take a look at how to open a file. If for instance we wanted to open a file called `"my-file.txt"`, here’s how we could open it:

```php
fopen("my-file.txt", "r");
```

In PHP, we can use the `fopen` (short for “file open”) function to open a file. Let's break down the syntax in the above example:

- The first argument is `"my-file.txt"`; the name of the file we’d like to open. This assumes `my-file.txt` is located in the same directory as the PHP script opening it, but if the file is located elsewhere, we can provide the path to the file (e.g., `../some-location/my-file.txt`).

- The second argument is the mode, `"r"`. The mode describes the type of access we want for the file we’re opening. In this case, the `r` stands for read mode. This means we can read the file from our code, but if we wanted to write to the file, we’d need to use a different mode.

There are 11 total modes that can be used with `fopen`. We’ll cover a few of them in this lesson.

It is important to note that the `fopen` function returns a reference to the opened file, called a file pointer. This allows us to interact with the file from other parts of our code. However, in order to use the file pointer, we’ll need to assign it to a variable. 

Let’s update our code from earlier to include this crucial component:
```php
$file = fopen("my-file.txt", "r");
```

In the above code, we’re assigning the result of `fopen` (a reference to our opened file, `my-file.txt`) to a variable called `$file`. We’ll use this variable to access the file from our code and to close the file when we’re done.

Lastly, as we have already alluded to, whenever we’re finished with an open file, we’ll need to close it. By assigning the file pointer to a variable, we can easily close the file using the `fclose` function. Here’s how we can use it:

```php
fclose($file);
```

Here, we used the `fclose` function to close the file referenced by the `$file` variable, `my-file.txt`. This is important because it safely disconnects the file from our application, preventing errors such as unsaved changes and data corruption. Just imagine what would happen if we never closed any of our files! Our computer's memory (every time we open a file, we use a tiny bit of it) would eventually overload and our computer's performance would grind to a halt. While it is not likely to happen with modern computer systems, as a best practice, always use `fclose` to close any files that aren’t in active use. 

Let's now practice using `fopen` and `fclose` to get a grasp of the basics of file handling.

Opening and Closing Files


In the previous exercise, we learned that we can write to a file by opening it in write mode (`w`). When a file is opened in write mode, any existing content is deleted. Sometimes, we’ll prefer this behavior. However, other times, we’ll want to add to an existing file without erasing what’s already there. This process is known as appending. We can append in PHP by opening the file in append mode:

```php
$file = fopen("hello.txt", "a");
```

This opens `hello.txt` with the `fopen` function, using `"a"` as the second argument to open the file in append mode. Unlike write mode, this tells PHP to preserve any existing content as it opens the file. However, if the file does not exist yet, PHP will still create the file.

Let's see it in action using our above file `hello.txt` with the following content:

```
Hello, world!
```

Once we’ve opened the file, we’ll still use the `fwrite` function to write to the file. Let’s try it out:

```php
fwrite($file, " Let’s learn PHP file handling!");
```

Since we opened the file in append mode, this writes to the end of the file without modifying what’s already there. If we looked at `hello.txt` now, we would see this:

```
Hello, world! Let’s learn PHP file handling!
```

To practice using append mode, let’s try appending to a file ourselves!

Appending to a File

Besides reading and writing, PHP includes several functions that can provide valuable information about a file, such as whether a file exists. For the most part, these functions take a single argument; the name of the file we’d like to learn about.

We’ve actually used a file information operation already. To read the correct number of bytes from a file, we used the `filesize` function to obtain the file size in bytes:

```php
$size = filesize("real-cool-file.txt");
```

Another common file information function is `file_exists`:

```php
file_exists("reed-me.txt"); // false
file_exists("read-me.txt"); // true
```

The `file_exists` function takes a file name as an argument and returns a boolean value. This value is `true` if the given file name exists in the current directory, or `false` otherwise.

Some other common file information functions include: [`filetype`](https://www.php.net/manual/en/function.filetype.php), [`fileperms`](https://www.php.net/manual/en/function.fileperms.php), and [`is_dir`](https://www.php.net/manual/en/function.is-dir.php). The full list of available functions is available in the [official PHP documentation](https://www.php.net/manual/en/book.filesystem.php). 

To get a feel for how file information operations work, let’s practice using `file_exists`!

File Information Operations

Next, let’s take a look at how to write to a file! The process of writing to a file is similar to reading, except we use the `fopen` function to open a file in write mode:

```php
$file = fopen("hello.txt", "w");
```

This opens `hello.txt` in write mode (`w`), assigning the file pointer to a new variable called `$file`. When opening a file in write mode, `fopen` will work in one of two ways:

1. If the file being opened *does not* exist in the current directory, the file will be created.
2. If the file being opened *does* exist already, any existing content in the file will be deleted. If this isn’t what we want, we can also append to a file without erasing what’s already there — we’ll learn how in the next exercise.

For this example, let’s assume that `hello.txt` did not already exist. By opening the file in write mode, we created an empty file called `hello.txt`. We can then write to the file using the `fwrite` function:

```php
fwrite($file, "Hello, world!");
```

`fwrite` works by taking two arguments. The first argument is `$file`, the file pointer we opened for `hello.txt`. The second argument is the text we’d like to write: “Hello, world!”. This will write “Hello, world!” to `hello.txt`. 

As long as the file pointer is open, we can call `fwrite` as many times as we’d like. To add text on a new line, indicate the line break with a `\n`:

```php
fwrite($file, "\n" . "This will be on a new line.");
```

Now, the directory where we created our PHP script contains a file, `hello.txt`, with the text we wrote:

```
Hello, world!
This will be on a new line.
```

As always, we’ll need to close the file when we’re finished:

```php
fclose($file);
```

Now, let’s practice writing to a file!

Writing to a File

Files are everywhere! Just about every piece of data on our computer is stored using files. For example, we could have a document saved into a `.pdf` file, a photo as a `.jpeg`, or a song as a `.mp4`. Sometimes we can even have multiple files compressed into a single file such as a `.zip`. These files are then organized into a structure of directories known as a file system.

As developers, it is common that we may want to work with files. Maybe we want our applications to open different PDF files or find and play a selected MP4 file. Many applications use files to store software configurations and activity logs. Learning to use programming to handle files is important to be able to write effective software! Don't worry — PHP, as well as many other programming languages, have easy-to-use features to work with files.

To start to understand how PHP interacts with files, imagine we wanted to read a book (a sort-of real-world file). Before we can read a book, we first need to open it. When we're finished reading, we will probably want to close the book. In PHP, to work with files, we can follow a similar process: open a file, perform some operation (such as reading or writing), and then close the file.

In this lesson, we will start to explore the basic operations of working with files in PHP. Specifically, we will learn to: 
* Open and close a file
* Read the contents of a file 
* Write to a file
* Append to a file 
* Use PHP shorthand functions for file operations
* Retrieve important information about a file
* Deal with common file handling errors and bugs

Let's get started!

Introduction

Whenever we’re working with the file system, there’s a lot that can go wrong. If a file operation is unsuccessful, PHP attempts to continue running our program as seamlessly as possible, meaning that any errors can be difficult to pin down. However, we can find out what’s wrong by looking for two indicators:

1. The file operation returns `false`.
2. An error or warning message is printed to the console.

To see this in action, let’s take a look at what happens if we misspell a file name:

```php
$read_me = file_get_contents("reed-me.txt");
echo $read_me;
```

This should print the contents of `read-me.txt`, but because we got the file name wrong, this won’t work. In fact, we might not even know that an error occurred — sometimes, all we’ll see is a blank screen. This is because `file_get_contents` returned `false`, a value that `echo` and `print` statements display as an empty string.

Ideally, our applications would let us know about the error using some sort of error message. To make this happen, we can check the value returned from `file_get_contents` and handle failure cases explicitly:

```php
$read_me = file_get_contents("reed-me.txt");
if ($read_me == false) {
    echo "Cannot read file";
} else {
    echo $read_me;
}
```

Like other file operations in PHP, `file_get_contents` indicates errors by returning `false`. By explicitly handling this scenario, we can make bugs much easier to diagnose.
 
PHP can also inform us of the problem by printing a message to the console:

```
PHP Warning:  file_get_contents(reed-me.txt): Failed to open stream: No such file or directory in index.php on line 2
```

To hone our debugging skills, let’s try this out ourselves!