Advanced PHP Introduction to File I/O

Hello again, and welcome back to Educator.com's Advanced PHP with MySQL course.0000

In today's lesson, we are going to be introducing the concept of file I/O, or file input and output.0005

Specifically, we are going to be going over what file I/O is; and as part of that discussion,0013

we are going to be talking about what file permissions are, which is something you may be familiar with,0017

especially if you have used a Linux or UNIX platform.0023

We are also going to be going over the different methods used to read from files.0026

The first method we are going to talk about is called fopen, which is a built-in function of PHP.0032

And as part of that, we are going to provide a discussion of specifying file paths to that function,0037

and also the different access modes that you can specify to the function,0042

that describe whether you want to open a file to read or write, for example.0047

We are going to go over the concept of file pointers, which is very similar to an array cursor,0051

which allows you to read or write from a certain point in a document, based on where this particular pointer is.0057

And then, we are going to go over a couple of other methods that relate to working with files.0064

fgets is a way of reading a single line from a file; feof is a function that tests if your file pointer is at the end of a file.0070

And we will explain more about that, and then we are going to go over the fclose method,0082

which is the analog to fopen, which is a way to close a particular file.0085

And we are also going to talk about the trim function, which is useful when working with files.0090

A file I/O, or file input and output, refers to reading from and writing to files in a file system.0098

PHP fortunately provides a number of built-in functions for doing so.0107

And in order to perform file I/O, there are typically three steps involved.0112

The first step is: you open a connection, or you open a particular file.0118

Then, what you do is perform any read or write operations that you need to on that particular file.0122

And when you are done with those operations, you close the file.0128

And so, we are going to, as we go through this lesson, walk through each of these different steps.0132

One thing to note about opening a file is that, when you open a file, we will be learning that you need to specify0139

whether you intend to just read or write from that particular file.0146

Now, we are going to talk about file permissions.0153

And like I said, those of you that use UNIX or Linux systems are more familiar with this than Windows users.0154

But in order to read or write from or to a particular file, you need to have the appropriate permissions on that file.0162

For example, to read from a file, you need to have what is known as read permissions on the file.0169

To write to a file, you need to have write permissions on the file.0174

And what these are, are permissions that are set by the particular operating system, on the system that you are using.0178

So, for our local development environment, it is going to be Windows's permission system.0184

If you are developing, if you are using a web host, they typically use a Linux server.0188

It is going to be dealing with Linux's permission systems for read and write permissions.0195

One of the things to note is that not having the proper file permissions for a particular file is one of the most common errors0202

in trying to do file I/O with PHP--if you are trying to read from a file (and you don't have read permission),0209

or write from the file (if you don't have permission to write on the file).0215

Now typically, with an operating system, the way permissions work is: they are associated with a particular user account.0220

For example, in Windows, when you log onto your computer, that is your user account.0227

And you have certain read and write permissions for different directories and different files.0231

Typically, you always have (for example) read and write permissions for all of the directories and files within your user directory.0236

When using PHP, one thing to note that you may encounter as a problem is that PHP, when the PHP Interpreter runs on your server,0244

it typically runs as a PHP user account, or as a web user account.0257

So, you have to make sure that the account associated with the PHP Interpreter0261

(and this is something that you may be able to change, or maybe it's something that you will have to talk to your system admin about)--0265

that that user account has to have a proper permission set to read or write for a particular file.0270

If PHP is trying to open a file for reading, whatever user that PHP Interpreter process is running at0277

needs to have permission to read or write from that particular file.0284

The first step in working with a file in PHP is to open the file for reading or writing.0290

And you do that using what is known as the fopen function.0295

Again, it is a built-in function of PHP, and it takes two required parameters.0299

The first one is the name and the path to the file that you are going to be opening.0304

The second is what is known as the read and write mode with which to open the file.0309

So, as mentioned, when you open a file, you have to let PHP and the operating system know whether you intend to0314

just read from the file, write from the file, or do both.0318

If fopen on a particular file is successful, it returns what is known as a file handle.0323

And what a file handle is: it represents an open connection to that particular file.0329

In PHP, a file handle is one of the special PHP data types (the other one being null) that is known as a resource data type.0335

Basically, it is a data type that refers to an external resource (in this case, a handle to an open file).0346

Another example of a resource data type might be a connection to a MySQL database.0354

If fopen fails, it returns false, and then it generates an E_WARNING-level error.0360

So, that is something that we are going to talk a little bit about working with--how to handle that error when you use the fopen function.0367

And this is a key function, because a valid file handle is needed by all of the other PHP file I/O functions that we are going to be dealing with.0374

because when you call up a function (for example) to read a line from a file, you have to pass it a valid file handle.0383

And that valid file handle means that it's a handle to an opened PHP file.0389

So, this is really a key function.0397

If we go and look at php.net and the documentation for the fopen function, we can see,0400

it has these two required parameters: file name and mode (mode being the read/write mode that you use to open a particular file).0406

And if you look down here, you can see: with mode, there are a number of different options that you use to open a file.0418

You can open it to read, open it to write...we are going to go over that a little more in a second.0423

File paths: as we saw, the first parameter to the fopen function is a file name parameter.0433

And you have to provide a path to the file that you want to open.0438

That can be a relative path or an absolute path, depending on the situation.0442

A couple things to notice about how to specify the paths: in Windows, you may know that paths are typically separated by the backslash character.0450

And on a UNIX system, they are actually separated by a forward slash character.0459

So, when you are specifying the path to a file in the fopen function, on a Windows system,0463

it lets you use either forward slashes or back slashes to specify the path.0471

And in order to specify a backslash within a PHP string literal, you have to escape it; so you will notice that,0479

for each backslash, you actually have two backslash characters.0485

On a UNIX system, which is maybe what your web host is going to be using, file paths are denoted with the forward slash character.0490

One thing to note is that, for the maximum code portability, you should always use forward slashes, even when working on a Windows environment.0499

For example, if this was specified...let's say this was just a path right here...this path is a relative path because it uses forward slashes.0507

If we move the application that uses this particular path from a Windows machine to a UNIX machine, the relative path would still work,0517

because the forward slash character can be used for both Windows and UNIX.0527

Now, that said, if we had instead used the backslash character to specify the path (and here I am eliminating the escape character),0532

now if we move our application to a Linux system, it is not going to be able to find that file in a relative path, because of the / character.0548

File access modes are the second parameter to the fopen function, and are a 1- to 2-character string0560

that tells PHP whether you want to open a file for reading, writing, or both.0568

And there are a couple other different options that you can do, as well.0572

One thing to note is that, in order to open a file for reading or writing, you have to have the proper permissions for that, as we had talked about.0577

You can request PHP, for example, to open a file to read; but if you don't have read permission on that file, you are not going to be able to do that.0585

And if we go back and look at the documentation for fopen, you can see: in the function documentation--the function reference--0592

there are a number of different modes that you can specify.0600

You can specify the character r (which is what we are going to be using in today's lesson)--a lowercase r that says0602

you are just opening the file to read, and you want the file pointer (which we are going to get to) to be placed at the beginning of the file.0607

We can use the w that says we are going to open the file for write.0615

There are modes for appending to the end of the file, and creating a new file, and so forth.0618

We are going to talk more about those when we get to the lesson on writing to files.0624

Let's go take a look at some sample code that we have.0632

There is a file called fopen.php; and we are going to use the fopen function in a couple of different ways to show how it is used.0635

We are going to be opening a file that is in the data directory of the directory that fopen.php is contained in.0646

So, fopen.php is in one directory; then, within that directory, there is another subdirectory called data.0659

For example, if we look at our lecture 3 examples, we can see that we have an fopen file;0665

and then, within that, there is a subdirectory called data that contains a file called stocks.txt.0671

This is the file that we are going to be trying to open.0677

And stock.txt, if we actually look at it, is a little terse; and we are going to explain more about that when we get to a future example,0681

but it basically is our way of representing the current stock for different items in a particular store.0690

For right now, we are just going to work with opening the file.0698

The first way we are going to do that is by using a relative path.0700

So, we specify a string called relPath that specifies a relative path to stock.txt.0703

And as you can see, it is in the data subdirectory where this fopen.php file is located.0712

And then, here we call the fopen function; we pass it the path name, or the path to the file, which is a relative path in this case;0720

and we pass it the access mode r, which says we want to open this file for reading.0726

Then, as we mentioned, if fopen does not work, what it will do is return false, saying that there was an error opening the file.0732

We test; it says that if file handle is false, we are going to output an error message that says, "There was an error opening the file."0741

And if it successfully opens it, we are going to output a message that says, "The file was successfully opened for reading."0748

Down here, we have another example that does the same thing, except we are going to use an absolute path and the fopen function.0754

So, instead of providing a relative path, we are going to provide an absolute path.0763

In this case, we define our absolute path using the SERVER ['DOCUMENT_ROOT'] superglobal array value.0766

And then, we are adding this specific path to our stock.txt file.0777

And as you can see, the same function call is made, except we use this absPath variable, which has an absolute path.0783

And again, we are going to test if there was an error opening the file; and if so, we are going to output an error message.0791

And if not, we are going to say that the file was successfully opened for reading.0796

If we go and load this script in our browser (go to fopen.php), we can see a couple of things.0801

We can see fopen using a relative path; and what it does is says, "The file" and it shows the relative path to that file "was successfully opened for reading."0809

So, we were able to open that file correctly.0817

And then, down here, when we use the absolute path, our output is--0819

and this is the absolute path to stock.txt--it says that file was successfully opened for reading.0823

We can see here an example of using both an absolute and a relative path with fopen.0829

There is a third example in this file, in which we try to generate an error using fopen, to show how it handles an error.0835

For example, we are going to try to open a file called stock.csv, which is an extension used for comma-separated value files.0843

You might have heard of it; it doesn't matter if you have or haven't.0855

But what you will notice is that, in our data subdirectory, in which fopen.php is located, there is no stock.csv file.0859

So, when we go to open this file, we should get an error from PHP.0871

And so, we should say, "There is an error opening this path."0875

And if we go and look at the end of the script (let's refresh it, just to make sure), we can see: at the bottom here,0877

it says, "warning: fopen on stock.csv failed to open"--the file doesn't exist.0885

And then, we have our output message that says, "There was an error opening stock.csv."0894

And one thing that is typically used here: because we have generated our own error output message here,0899

we don't really typically want this PHP warning to be output; it is kind of ugly, and it doesn't provide a good user experience.0907

So, we are going to make use of the error suppression operator, which is the @ symbol.0916

We are going to prepend that to the fopen function that is going to generate this error, so that, when we reload our page,0924

the PHP warning is not going to be output; and we are just going to have it output our own error message.0932

And any time we are going to be using fopen in this course (and as you will pretty much see any time you see fopen used),0937

it will be prepended with that error suppression operator, so that, if there is an error opening that file,0942

it doesn't output the ugly error message to your user's output.0948

So now, something I want to talk about is a file pointer.0956

It is kind of like an array cursor, which we learned about in the introductory course.0960

What it is: it is a cursor that is used to keep track of the current character being accessed in the file.0964

For example, if we have a file down here that has these three lines (which is a number of different characters,0972

separated by hidden new line characters here), when we are reading to or writing from a file,0978

we read to or write from a file based on the location of the file pointer.0986

For example, when we open a file using fopen with the r access mode, it opens the file for reading,0990

and it places the file cursor here, at the beginning of the file.0996

So, when we go to read (for example) the first four characters from this file, it is going to read from the current file pointer.1000

It is going to read up to here--the first four characters.1009

Now, for example (and there are different functions for moving this cursor around) that the file pointer was actually down here, before this i character.1012

Now, when we read four characters, it is going to read these four characters here: i, s, space, and l.1021

So, the file pointer is what is used to read from a file.1028

And also, if we are going to write to a file, when you write to a file, it is going to write to wherever that current location of the file pointer is.1031

One thing to note is that, sometimes, you will hear file handles referred to as file pointers; and that is commonly used.1040

In this course, we are going to distinguish between a file handle and a file pointer to make it easier to understand,1047

so that there is less confusion, because often, they are both referred to as file pointers.1054

So, for this course, we are going to use file handle to refer to the handle, or the connection, to an open file,1060

and then a file pointer to refer to the cursor that you use to access data within a file via reads or writes.1067

The first function we are going to introduce for reading from a file is called fgets.1077

And what it does is: it reads the contents of the current line of a file.1082

So, wherever the file pointer is--whatever line it is on--it reads out the contents of that file.1086

And if that pointer is in the middle of the line, it just reads from wherever that pointer is until the end of the line.1091

The other thing that it does is: after it reads the contents of the line, it advances the file pointer to the beginning of the next line.1098

Let's take a look at the fgets function in action.1106

We have a file called fgets.php, and we have a similar code to what we had in the last example, fopen.php.1109

We define a relative path to this stock.txt file; we open the file for reading.1117

We are using the r access mode, which is going to place the file pointer at the beginning of the file, so it will be at the very beginning of the first line.1124

You can see, we have the error suppression operator here, which is going to suppress any errors1131

(for example, "PHP can't find this stock.txt file").1136

If there is an error opening the file, we output an error message; if not, we move forward.1139

And then, what we do is call the fgets method.1144

And the fgets method takes at least one required parameter, that is the handle to the file that you want to read the current line from.1147

When we call fgets and pass it fileHandle, because fileHandle hasn't been used by any other (for example) read or write functions,1156

and we open the file with this r access mode, when you call fgets for the first time on a file handle, it is going to read the first line of the file.1165

So, what we do is call fgets on fileHandle and store the contents of that first line in this variable line.1174

And then, we output "contents of the first line are" whatever is stored in that variable.1179

If we go and view this script in our browser, when we go to fgets, we can see the output.1185

It says "contents of the first line is 100011."1192

And if we go back and look at stock.txt, we can see that that is the contents of the first line in the file.1197

That is how you use fgets to read a line from a file.1204

Now, typically you don't just want to read the first line of a file; you want to read multiple lines in a file, or even all of the lines in the file.1210

And one thing that is commonly used with fgets is another function called feof.1216

And what that allows you to do is test to see if the file pointer is at the end of the file.1224

For example, if you want to read all of the different lines in a file, and then stop reading from that file when you reach the end of the file,1227

you use this feof to function to let you know to stop reading lines, because you are at the end of the file.1235

And just so you know, eof stands for "end of file"; and it is commonly used to refer to when you have reached the end of a particular file.1241

If we go and look at a new piece of code called feof.php, what we are going to do is loop over all of the lines in that stock.txt file and output them.1252

Here, we have defined the relative path to the file; we have opened it using fopen.1269

And then, what we have done is created a loop that says, "As long as feof on this file handle on this file that we have opened is not true,"1276

meaning that it is not the end of the file yet, "it is going to continue to go through this loop."1287

And what it does is: when it enters into this loop, the first time, it is going to evaluate this test condition.1292

feof is going to return false, because it is not the end of the file; so not false is true.1298

We are going to enter the while loop, and the first thing we are going to do is get the current line in the file.1303

This, the first time we go through this, is going to get the contents of the first line in the file.1309

Then, what we are doing is simply outputting the line number of the file with the contents of that line.1313

And in order to do that, we have defined a lineNum variable, which is sort of like a loop counter that we are going to use to keep track of the line number.1319

Then, after it has output that line, it is going to increment the line number.1327

It is going to go back to the test condition of the while loop, and it is going to say, "Are we at the end of the file yet?"1331

In this case, because our file (as you have seen) has three lines in it, it is going to say, "No, we are not at the end of the file."1336

So, we are going to run the loop again, and we are going to go ahead and read the line and output it.1341

In this case, it is going to happen several times, and it is going to output each line of the file.1346

So, if we go and look at the results of this...we go to feof.php...we can see that it outputs line1=1000:5.1352

It outputs line 2 and line 3; and also, you can see, it tried to output a line 4.1362

You can see that it actually entered this loop a fourth time, but when it tried to output line, there was nothing there.1369

Well, the reason that happened is because in stock.txt, there are four lines, because at the end of this third line,1376

there is actually a new line character, which makes it line 4.1384

So, when feof is testing this file to see if it's at the end of the file, after it reads this third line, it is going to come down here1387

to this next line, and it is going to see that it is not the end of the file, because there is still a new line there.1398

And it is going to read the contents of that new line.1402

In this case, the new line has nothing on it, which is why it outputs nothing.1405

That is one thing you will have to be careful of, either by not including a new line at the end of your data files,1410

or testing for that condition (which is something we are going to show in an example in a minute).1415

As mentioned at the beginning of the lesson, there is a 3-step process for file I/O in PHP, or pretty much in most programming languages.1426

You open the file; you perform any read or writes that you need to on it; and then you close the file.1434

In this slide, we are going to talk about fclose, which is the analog to fopen; it is used to close the connection to an open file.1439

The way you do that is: you pass it a handle to an open file as its parameter, and what happens is that fclose goes ahead and closes that file.1446

Now, some people don't always close a file after they are done using it, but it is a recommended practice that you always1455

close any files that you have opened in your code, and also do so as soon as you are done using a file.1462

And part of the reason for that is something known file locking.1468

Typically, on a computer, only one process or program can access a file at the same time.1473

So, if you have a file open--if you have opened it, and you are doing a bunch of processing on it, and stop processing;1479

and you go off and do a bunch of other stuff, but haven't closed it; then any other program on the computer1485

trying to access that file is not going to be able to.1489

So, that is one of the main reasons for always closing a file when you are done with it, and doing it as soon as possible--1492

so that it is free for any other process to use.1498

Let's take a look at another code example called fclose.php.1502

And what this does is completes this 3-step loop.1507

We open our file using fopen, the same file as before.1513

We loop over each file, outputting it (we read each line of that file, and then output that line's contents).1516

And then, here you can see, we use the fclose method.1522

We have just finished using the file for all the reads that we need to, so we want to close it right away.1525

fclose returns true or false, depending on whether it was able to successfully close the file or not.1531

Based on that return value, if it was successfully closed, we are going to say "the file relPath was successfully closed."1537

If not, we are going to say there was an error closing it.1544

If we go and look at fclose.php, and we view it, we can see it outputs different lines of the file.1548

You will see here, it still outputs line 4, because we have that new line in the file.1555

And it is going to output the message at the end: "The file ./data/stock.txt was successfully closed."1559

And so, that is an example of using the fclose method.1567

Now, we are going to take a look at a little more real-world example in a file called currentStock.php.1571

What it is going to do is read this stock.txt file, and it is going to output for the user the current stock of each item number in the store.1576

For example, in this file, the way stock.txt is set up is: the first part of each line is an item number of an item in this fictitious store, for example.1588

And then, a colon is entered; and then after the colon is the current stock of the item.1600

And we put each item and its current stock on a new line in our stock.txt file.1609

For example, this file states that there are five items with item ID 1001 currently in stock.1615

It is out of stock of item 1002, because the quantity here is 0; and it has 24, currently, of item 1003.1625

What we do in this currentStock.php script is: we open for reading this stock.txt file.1636

And what we do is: we are going to loop over each line of the file, using this feof text function.1646

At each line that we are going to go to, we are going to read that line, using the fgets method.1653

What that is going to do is return (for example, when we read the first line) 100011.1659

Then, what we want to do is separate that information out into something useful.1666

We want to separate it out into an item ID and the current stock.1668

So, we are going to use the explode function and specify that we are going to be using the colon as the delimiter.1672

And we are going to say, "Take this string that we read from the file and separate it into parts, based on where the colon is."1680

And it is going to generate an array, and the first part of that array, or the value with the 0 index of that array, is going to be the item ID.1689

The value with the next index, the 1 index, is going to be the current stock.1696

Here, we do a little test that says, "If the length of lineArr is not equal to 2, then continue processing the next line."1703

And this our way of correcting for when we reach this fourth line here.1711

Instead of outputting the stock for this line, that is for an item that doesn't exist, when it reads this line,1717

and it runs explode on it, there is no colon; it is not going to return an array that is of size 2.1728

So, we are going to just say, "Skip over processing it."1733

And that way, that empty line doesn't get output.1735

Now, if the array does equal 2 in size, then we are going to extract the item ID and current stock amount from the array.1741

And here, we are just creating some short variables: we are going to say, "Item ID is equal to the value of the array at the 0 index,1749

and the current stock is equal to the value of the array at the 1 index."1755

And then, we are just going to output a line that says "Item ID has so-and-so items in stock, based on what was in the file."1760

We are going to do that for each of the items in the file.1769

And then, what we are going to do is close the file using the fclose method.1772

And if there is an error, we are going to generate an error message that says "There was an error generating the code."1776

If we go and look at this file, currentStock.php, we can see that it read over the file, and it said:1786

"Item 1001--there are 5 in stock; item 1002--0 in stock; item 1003--there are 24 in stock."1794

And so, this is the output of this file.1804

And one thing you will notice is that it has put "in stock" on a separate line in this page.1805

And if we look back here, and we look at our string to output, we don't have a new line or a break in there.1812

And so, what is happening is: an extra new line is getting into there, being added to that.1822

And because we are enclosing this output in the pre tag, it outputs the text as is.1828

So, if there is a new line character, it outputs it as a new line, or makes it look like a break.1836

If we look at the source code here, we can see that, after 5, there is a new line (let me blow this up) in the code.1840

And you can see, "in stock" is on a separate line.1851

Similarly, when we process item 2 after 0, we can see that a new line is output.1855

The reason for that is: if we look at stock.txt, each of these lines has two parts.1860

It has the item ID, and then a colon; and then it has the current stock.1867

But also, there is a new line character here (which allows us to put the second item on the next line).1875

So, when explode runs on this line, it is going to return, as the second element, 5 and a new line character1882

(which is why that new line character is going to show up).1891

And so, now, we are going to talk about a way to get rid of that new line character.1894

PHP provides a built-in function called trim; and it is often used; and what it does is strips any white space from the beginning or end of a string.1901

And it is often used to strip new line characters from lines read from a file.1910

So, what we are going to do: if we go back to currentStock.php, here, when we get the current stock from this lineArr1915

that we have created using the explode method, we are going to run the trim function on that array value.1929

And what that is going to do is strip that new line character off of that current stock,1936

because when it reads this line (for example, the first line), it reads 5 and then a new line.1944

Well, now, when it gets that string here by lineArr index 1, and we run trim on it, it is going to get rid of that new line.1950

So, all that is going to be left in that string is 5.1959

So, if we save this, and we go and look at the file again, we are going to see that now that new line doesn't appear.1961

And the string appears as we had written it, with "in stock" being on the same line.1970

So, it says "item number 1001 has 5 in stock."1973

And if we look at our source code, we can see that none of those (let's blow it up) new lines after the current stock appear anymore.1977

And so, typically, any time we are going to be reading stuff from a file, we are going to be running the trim command on it, as well.1988

So, we are going to do that for itemID.1995

In this case, it is not going to matter; but in some cases it does, so just as a good practice, when we read from a file,1997

and we use (for example) this explode method, we are going to trim any data that we get.2004

If we just run it again, everything is going to look the same; but that is just good practice.2010

For the homework challenge for today's course, I want you to do something similar to what we did in today's lecture.2018

I want you to create a data file called users.txt, where each line is a comma-delimited string2023

(in our example in this lecture, we used a colon-delimited string)--2029

a comma-delimited string that represents the first name, last name, and email address of the user.2033

And so, for example, one user in this data file might be represented like this:2040

Tom, Stevens (this is his first name and his last name), tstevens@gmail.com (it's his email address).2045

You won't see it here, but there will actually be a new line character.2053

You will go to a new line and add another first name, last name, and email address for a particular user.2055

So, go ahead and populate this file, users.txt, with several fictitious users, just for use in this example.2062

And then, what I want you to do is: from PHP script, open this users.txt file; read each line; and then, after reading each line,2070

output the name of each user and the email address of each user.2079

You are going to have to make use of that explode command that we use in this thing.2085

And also, I want you to make sure that you use all of the functions that we used in the course today.2089

Use the fopen function to open the file; fgets to read a particular line; feof to test when you have reached looping over the lines in a file;2094

fclose (which is important) so that you close a particular file; and then use the trim function, so that you don't have that error2105

that we saw when we read a line from our file in today's lecture, where it adds an extra new line to a string that it reads from a file.2112

And test that example out on this text file that you create, and then see the name and email address output for each different user.2121

That ends today's lesson; thank you for watching Educator.com--I look forward to seeing you next time.2132