Advanced PHP HTTP POST: File Uploads

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

In today's lesson, we are going to be learning how to upload files using the HTTP POST method.0005

The first thing we are going to talk about is something known as POST data encoding.0012

which describes how the data that you submit from an HTML form using the POST method is encoded0016

before it is sent to the web server, so that the web server knows how to interpret it.0024

We are going to go through the process of uploading some files, and then we are going to talk about what is known as the FILES superglobal.0028

And that is the way to access information about uploaded files from your PHP code.0037

Our POST data, we have been accessing using the POST superglobal.0045

We are still going to use that to access general POST name/value pairs; but for file uploads, we are going to be using this new superglobal.0050

And then, additionally, we are going to talk about, once you have uploaded a file on an HTML form,0060

how, in your PHP script, you can move that to a location that you want to--0065

because when files are uploaded, they are uploaded to the temporary directory.0069

When the POST method is used to submit an HTML form, data is encoded, by default, using URL encoding.0076

We talked a little bit about that in our review on HTTP, where we introduced the POST method.0083

When you use the POST method to submit a form, it creates (as we learned in our HTTP lesson) a header of the HTTP that describes0093

that it is using the POST method; it tells a little bit about what the content is...0105

There is a blank line, and then there is the body of that HTTP request, which contains the data that you are submitting on the form.0109

Well, that data, by default, follows this content type called application/ and this long phrase here, which says it is URL-encoded data.0117

And if we go and look at, for example, a form we are going to be working with today, called enctype.html0130

(which refers to encoding type)--it is a form that is going to allow you to submit a first name and a last name.0137

Here, we have explicitly set the encoding to this URL-encoded form; but if we left it out by default, that would be the default.0147

And so, if we go ahead and submit the form, and we use our Firebug add-on to see what the POST data looks like0154

(and in this case, we are just posting the data to the same file, enctype.html),0168

if we look at our POST data, we can see that here, the data we supplied was URL-encoded.0176

Hopefully, you can see that; it is a little bit small.0183

And it says the content type was application/x-www-form-urlencoded.0185

That is the standard encoding for data submitted by an HTML form using POST.0191

However, when we want to upload a file, you need to change that encoding; you need to use a different type of encoding.0198

And the content type in the encoding that you are going to be using is something called multipart/form-data.0205

The way that you do that is by setting the enctype attribute of your HTML form tag.0213

So, if we go back and look at enctype.html, and we scroll over here, we can see that it was set to this URL encoding, which is the default anyway.0221

And if we change it to multipart/form-data, we are going to see that, when we submit this form,0234

even though we are not doing a file upload here, we are going to take a look at how that data is encoded in the body of our POST request.0243

So, if we go ahead and run this same form again (actually, I have to refresh it so that it updates with the new encoding type),0252

and we go ahead and submit the query, if we look at our POST data, we can see that it is very different.0268

Whereas before (let me open up a second window, so we can compare them, and get rid of this so it goes to default),0277

in the old way, our POST data was formatted in this URL-encoded method down here;0305

in the new method using the multipart/form-data, what it does is sets the content type to multipart/form-data.0311

And then, it has our data that we submitted encoded in a different way.0320

Here, you can see that it is saying that we have submitted a variable called firstName; the value of it is Matthew.0326

We have a variable named lastName; we are submitting the value for that of Machaj.0334

The way that this works is: for each input element that you have on a form that you submit,0340

when you submit it using multipart/form-data as the encoding, it defines this string, known as a boundary.0346

And it creates a boundary, and in between each boundary, it has the information about each input element that was submitted.0354

So here, we have firstName and lastName.0362

It is not really important how that encoding works--the browser does it for you, and PHP knows how to interpret that and understand it.0366

But it is just to give you an idea of what is going on behind the scenes, when you use this multipart/form-data,0373

which is what we are going to be using for uploading files.0379

The way we upload files using an HTML form is using an input tag that has the type 'file.'0383

And so, we create this input tag and set the type equal to file, and then we associate a name to it, just as we would any other input element.0391

So, we are going to say that this file we are going to be uploading is going to be associated with the name imageFile.0399

And let's go and take a look at a script that shows this in action: uploadFile.html is a file we have created0405

that is going to submit the form data using multipart/form-data encoding here at the end.0413

But what we have done is added an extra input element here, a file input element called uploadedFile.0422

And so, what we are going to do is try uploading a text file.0428

And the file is called uploadFile.txt, and it just contains some basic text information.0431

And then, we are going to take a look at what the body of the POST data looks like, now that we have included an uploaded file.0438

If we fill out the form as before, this time we are going to include this uploadFile.txt, and we submit the form.0446

We go and look at our POST data (the body of the POST request); we can see that things have changed a little bit.0458

We still have our two sections for the firstName and lastName variable.0466

Here, firstName is equal to Matthew; lastName is equal to Machaj.0471

But then, we have a new section down here that is for our file that we uploaded.0473

Here, we can see the name that we gave to this uploadFile input element; it is called uploadedFile.0477

It lists the file name of the file that we uploaded, which was called uploadFile.txt.0485

And then, it provides the content type of that file that we uploaded (in this case, it was plain text).0490

And then, it provides the information or the data of that particular file.0495

And so, that is how the multipart/form-data (the body) changes a little bit when you add a file to upload.0500

Now, if we do the same thing...that was on a text file; if we do it on a binary file (for example, an image,0509

which is something we are going to be doing in our web application for uploading item images), and we submit the form,0515

and we look at the POST data, we can see: everything is the same here, except that, in our third section,0523

the file name for uploadedFile has been changed to the GIF file that we uploaded; the content type has been changed to image/gif,0532

which says the data file we have uploaded is a GIF file; and then, this right here is the data of the GIF image.0539

It is not legible, because it is not text--it is binary data.0550

But this is the information contained in that GIF file, and the web server will know how to interpret that.0554

Now, one thing to note is that if (let's go back and look at our slide) you are trying to upload a file,0562

and you don't set the encoding type to multipart/form-data, then the file doesn't actually get uploaded.0570

And all that you end up getting is a name/value pair, which is the name of the file input element that you set in your form0577

(in this case, imageFile), and then its value gets set to the name of the file that you uploaded.0588

For example, if we erase our encoding type from multipart/form-data and set it to the default and save this file,0593

when we go and refresh the file and upload our form...we try to upload an image file, and we submit it or post the form data...0607

we can see that what it has done is encoded our data as URL-encoded data.0628

It has the first name and last name encoded, as you would expect; and then, as mentioned, it just says that the uploadedFile variable is named blank.gif.0635

That is all the information, if this data were being posted to a PHP script, that you would get.0643

The file would not actually have been uploaded.0649

That is one thing that is important to notice: you have to be careful to appropriately set the encoding type for your form.0651

How do we access files that we have uploaded and information about those files in PHP?0661

Well, we mentioned, in the lesson overview, that there is another superglobal that PHP provides called $_FILES.0668

That contains information about all of the different files that have been uploaded by a particular script.0676

FILES is a multidimensional array, and the keys of that array are the names of any input file elements that you had.0682

For example, you can upload multiple files on a particular web page.0691

For example, you could have multiple input file elements.0697

Let's say we call this one uploadedFile2.0706

The keys of this FILES array are the names of those file input elements.0712

For example, the way we would access information about the uploadedFile input tag is: we would use uploadedFile as the key to the FILES array.0717

Now, what that is going to return is an associative array that contains information about that different file that was uploaded.0729

The FILES superglobal is a superglobal that provides information about all of the files that a particular form has uploaded.0736

And then, as we know, the keys to that file are the names of any file input elements we have in our particular HTML form.0746

And the associative array that it returns for a particular uploaded image has a couple of keys in it.0753

The first one is the key name, which is the original name of the uploaded file.0761

There is a type key, which is the content type of the uploaded file.0765

For example, if we uploaded a GIF image, it would be image/gif.0768

A really important one is called temp_name, which is an absolute path to the temporary location of the uploaded file,0773

because when you upload a file using an HTML form, it uploads it to a temporary directory.0779

It has an error key, which provides an error code for the file upload, which says if any problems occurred during the upload.0786

And then, it has a size key that says the number of bytes in the file that was uploaded.0794

One thing to note is that an error coded 0 means that a file was successfully updated without any problems.0798

And if you look at this link here, which is in the Quick Notes, you can take a look at some of the other errors that are possible to be set in the FILES superglobal.0805

If we go and look at our uploadFile.html, the action has been updated so that, instead of just posting the information to itself,0815

it is posting to a PHP script we have created, call processFileUpload.php.0828

Everything else in the form is the same; and if we look at our processFileUpload.php form, we can see that0835

what we are doing is accessing the FILES superglobal, which is going to contain information about all of the uploaded files.0844

In this case, we are saying, "Give us the information about the file that was uploaded with the file input element named uploadedFile."0850

If we look back at our form, we can see that our file input element had the name uploadedFile.0861

And then, this is just going to output the data that is contained in that FILES associative array.0866

If we go and try to upload a file again, now it is going to post it to this script.0873

I'm not going to bother including a first and last name--just upload a file.0878

If we upload the text file uploadFile.txt, and we go ahead and try and upload that,0882

we can see here that the FILES array, in the key uploadedFile, contains an associative array with this information.0889

And this is what we had discussed in the slide we were just on.0898

The name of the file that was uploaded was uploadFile.txt, and that is the name of the file on the client machine.0902

The type of the file is a plain text file, in this particular case.0908

This right here, which is really important, lists where that file has been temporarily saved.0912

And we can see that it has been given this random file name with a .tmp extension, and it is located in this temporary directory.0918

We can see that the error code was 0, which means that it was successfully uploaded.0927

And then also, we can see that it had 87 bytes; that was how big the file was.0931

By default, as mentioned, when you upload a file using an HTML form, it gets stored in a temporary directory.0943

And by default, it gets stored in a temporary directory of the environment that PHP is running in.0949

Now, one thing that you can do is: there is a configuration directive in php.ini called upload_tmp_dir,0956

and that allows you to set where you want any uploaded files to be stored.0963

In this case, in XAMPP, this upload_tmp_dir directive is set to this tmp directory in the xampp root directory.0969

And so, if we go back and look at our script, we can see that that is what we have here.0979

Within our Windows User folder, we have our XAMPP folder, and then we have this tmp directory.0985

And that is where it stores uploaded files; so we have that configuration set in XAMPP, and by default, it is this directory here.0993

Now, typically what you are going to want to do is: you are not going to want1002

to leave that in a temporary directory--you are going to want to move it somewhere.1004

For example, if you are uploading an image with an item for our store, we are going to store it in the Images directory for our application.1006

Well, PHP provides a function called move_uploaded_file, which allows you1014

to move an uploaded file from the temporary directory to the directory of your choice.1019

Now, the one thing to note is that whatever directory you are going moving it to, you have to have write permissions on that directory.1026

And specifically, the user that the PHP Interpreter is running as has to have write permissions on that directory.1033

Let's take a look at a script that is going to use this move_uploaded_file function.1040

Here is our script called move_uploaded_file.php, which we are going to post our form data to.1048

At the beginning here, we have the same output as we had on our last form, where we are just updating the information related to the uploaded file.1055

And then, what we do is: we are creating a string that is a path to where we want to move that uploaded file.1063

In this particular case, we want to store it in our lecture_examples directory, and we want to give it the same name that it was uploaded with.1070

So, the name of the original file on the client that was uploaded is in this position in the FILES associative array.1078

We go to FILES; we look up our uploaded file image; and then, we get the name.1093

If we look back at our script, we can see, the name is the file that we have uploaded.1099

What we do is create the path of where we are going to move it to; and in this particular case, we are just going to move it to the lecture 9 examples directory.1109

We are going to name it the same name that it was uploaded as.1115

This is just a little information that is output, that is saying, "We are moving the file from this temp location to this new location."1119

And then here, we call the move_uploaded_file function.1126

And what we do is provide the source file...this takes two parameters: the first one is the source file,1131

or the path to the temporary file; and the temporary file is stored in this tmp_name key in the FILES superglobal.1137

Again, if we look back here, we can see that tmp_name for this particular file was stored as phpB704.tmp.1148

So, when we provide this value to our move_uploaded_file, it is going to know where the temporary file is located.1155

And then, we are going to pass it the path to the new location, where we are going to store the particular file.1165

I'm just going to update our uploadFile form, so that it sends the data to this new move_uploaded_file script.1171

I'll go ahead and refresh that script.1190

And if we look (just so you know) right now, the files we are uploading are located in the data directory of our lecture 9 examples directory.1194

And what we are going to be doing is uploading one of those files to this same directory where all of these scripts are.1202

In this case, you can see that there are just two HTML files and a PHP file.1208

If we go ahead in our form and upload this blank.gif file, what we are going to be doing is uploading it and moving it to the same directory as the script.1212

When we submit the form (minimize this) we can say that the name of the file we uploaded was blank.gif.1222

It was a GIF file; this is the temporary name that it was assigned when it was uploaded to the xampp tmp directory.1234

There were no errors, and it was 799 bytes.1241

Here is our little output message that says the file was moved from this tmp file name to our lecture_examples/lecture_9 directory,1246

and it called blank.gif, which is the same name of the file as it was originally uploaded.1255

If we go back and look at our lecture 9 directory, we can see that blank.gif is now in there.1261

And if we go back and do it in the web browser, we can see that blank.gif has been uploaded into this file.1265

That is how you move a file from a temporary directory into the directory of your choice.1273

For today's homework challenge, I want you to create an HTML form that allows you to upload a file.1281

It is going to include an input element of the file type.1287

And then, I want you to create a PHP script that is going to process the file upload.1293

The script should output all of the information about the uploaded file that is contained in the FILES array.1297

And if you remember, you are going to have to access that information by providing a key to FILES.1303

And that key is going to be the name that you associate with your file input element.1309

And then, move the uploaded file from whatever temporary directory PHP assigned it to (the default XAMPP distribution is going to be xampp/tmp).1314

And then, move it into the same directory as whatever script you create.1325

So, you will be doing the same thing that we had done in our example in the lectures.1328

And then, just run the script and verify that the file was successfully moved to where it was supposed to be.1334

A couple things to make sure of: make sure that you appropriately set the encoding type attribute of your HTML form tag to multipart/form-data.1340

Otherwise, it is not going to work: it is not going to update the file, and you will not be able to access any information about the file in that FILES superglobal.1348

And then also, when moving the file, I want you to make use of the move_uploaded_file that is built into PHP.1359

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