Forcing a Download Dialog
A fairly common question is, "How can I force a file to
download to the user?" The answer is, you really cannot.
What you can do is force a download dialog box that gives the
user a choice to open or save a linked file, or to cancel the
request. Picky? Yes, but the distinction needs to be made.
You can't force anything on the user except to force the user
to make a choice.
If you, perchance, stumbled upon this page hoping to find
a way to have a file silently download to the user without
the user's knowledge or approval, this page won't help. With
newer browsers' security measures and anti-virus/spyware programs,
you should not be able to do that. Forcing a download dialog,
on the other hand, is a fairly simple procedure, but it does
require an intermediate file that will send the appropriate
headers.
How Files are Transferred on the Internet
Before I get into that, I'll bore you with just a little
bit of theory. You should understand the way files are requested and viewed
on the web. Let's say you type the URI of this page into your browser's
address bar. The first thing that happens is that your browser looks up
the I/P address of the domain name. Once the browser has that address,
it sends a request to that address for this file. That request is
composed of headers that might look something like this:
GET /phptools/force-download.php HTTP/1.1
Host: apptools.com
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US; rv:1.8.1.6)
Gecko/20070725 Firefox/2.0.0.6
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9
,text/plain;q=0.8,image/png,*/*;q=0.5
Accept-Language: en-us,en;q=0.5
Accept-Encoding: gzip,deflate
Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7
Keep-Alive: 300
Connection: keep-alive
I won't get into all of that, but the noteworthy thing is that the request
is to GET the file /phptools/force-download.php from the host apptools.com.
The server, before sending the actual page, will send response headers that
tell the browser about the result of that request. In this example, those
headers might look similar to this:
HTTP/1.x 200 OK
Date: Thu, 09 Aug 2007 19:16:17 GMT
Server: Apache/1.3.37 (Unix) mod_throttle/3.1.2 DAV/1.0.3
mod_fastcgi/2.4.2 mod_gzip/1.3.26.1a PHP/4.4.7 mod_ssl/2.8.22 OpenSSL/0.9.7e
X-Powered-By: PHP/4.4.7
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: text/html
Content-Encoding: gzip
Content-Length: 6210
This lets the browser know what to expect next. In this case,
the HTTP/1.x 200 OK tells the browser that the
file was found okay and that no errors were encountered. The
browser should expect 6,210 bytes of plain text that is to
be rendered as HTML. It determines that from the Content-Length
and Content-Type headers.
As the browser parses the HTML content it receives, it may
encounter the need to request additional files like style sheets,
external JavaScript files, images, etc. Each time it finds
one of those, it sends an additional request comprised of a
set of headers and the server will send back a set of headers
before sending the file. Displaying a simple page typically
consists of several requests and responses.
One of the more important headers is the Content-Type header.
If the browser knows what to do with the type of content it
is to receive, it does it. For example, with text/html, the
browser renders the page in its viewport. If it's an image,
it renders that. If, on the other hand, the browser encounters
a type of content that it doesn't know how to handle, it displays
the aforementioned dialog box, asking the user what to do with
this file.
How to Send Headers
Okay, boring stuff over. Servers are configured to send appropriate
headers automatically for file types that it recognizes.
These are referred to as Internet media types or sometimes
called MIME types, from their origins in Internet mail
specifications. The MIME acronym stands for Multipurpose
Internet Mail Extensions. One method of doing this involves
reconfiguring the server to send a header that will force
the dialog. However, you may not want all files of a given
type to download.
The way around this is to use an intermediate file with the
appropriate PHP code to send the headers and then send the
file. You use, appropriately enough, the header() function
to do that. One thing to remember is that you cannot send any headers
after any non-header content has been sent to the browser.
That means that you can have nothing else in the file, including
blank lines, that goes to the browser before your call to the
header function.
How to Do It Correctly
If you look around, you may find some people suggesting to
change the MIME (Content-Type) to application/octet-stream.
Of course this will always force the download dialog, but it
will display the wrong information about the file in that dialog.
It works, but it's a bad practice. The preferred method, and
one that will display correct information about the file is
to add an additional header, specifying Content-Disposition:. By doing that, you can still send the correct
attachment
content type header and tell the browser to offer a download
of the requested file. An important point to remember is that
the server will automatically send back a set of headers for
this intermediate file. Your intermediate file must send all the
headers appropriate to the type of file you want users to download.
A simple example might look like this:
<?php
header('Content-Type: image/jpeg');
header('Content-Length: 1234);
header('Content-Disposition: attachment;filename="test.jpg"');
$fp=fopen('an_image.jpg','r');
fpassthru($fp);
fclose($fp);
?>
This code sends the correct content type for a JPEG image,
sends the file size then tells the browser to offer a download
dialog with the suggested name "test.jpg". It then
opens the file, sends the content to the browser and closes
the file. You may notice that the file name we read is different
from the file name suggested to the user for the file. That
was done only to illustrate that they need not be the same.
They can, in fact, be the same. It makes no difference. Normally,
if you link to a .jpg image, the browser will simply display
that image. Using the above, the browser will display the desired
dialog asking the user what to do with the file.
Now the above is fine if you have only one specific file
you want users to download, you know the file will always
be available, you know the size of that file and you know
none of that will change. Suppose you don't meet all of
that criteria. Let's not reinvent the wheel every time
we want the user to be able to download a file. Let's write
a script that's a bit more versatile. Let's have a PHP
script that accepts a parameter that tells it which file
to send to the user.
Let's begin by saying that there are hazards inherent with
this type of script. You have to have some error checking
in place to prevent someone from gaining access to a file
they should not get. With that thought in mind, let's start
out with this:
<?php
// this is a relative path from this file to the
// directory where the download files are stored.
$path='files';
// first, we'll build an array of files that are legal to download
chdir($path);
$files=glob('*.*');
// next we'll build an array of commonly used content types
$mime_types=array();
$mime_types['ai'] ='application/postscript';
$mime_types['asx'] ='video/x-ms-asf';
$mime_types['au'] ='audio/basic';
$mime_types['avi'] ='video/x-msvideo';
$mime_types['bmp'] ='image/bmp';
$mime_types['css'] ='text/css';
$mime_types['doc'] ='application/msword';
$mime_types['eps'] ='application/postscript';
$mime_types['exe'] ='application/octet-stream';
$mime_types['gif'] ='image/gif';
$mime_types['htm'] ='text/html';
$mime_types['html'] ='text/html';
$mime_types['ico'] ='image/x-icon';
$mime_types['jpe'] ='image/jpeg';
$mime_types['jpeg'] ='image/jpeg';
$mime_types['jpg'] ='image/jpeg';
$mime_types['js'] ='application/x-javascript';
$mime_types['mid'] ='audio/mid';
$mime_types['mov'] ='video/quicktime';
$mime_types['mp3'] ='audio/mpeg';
$mime_types['mpeg'] ='video/mpeg';
$mime_types['mpg'] ='video/mpeg';
$mime_types['pdf'] ='application/pdf';
$mime_types['pps'] ='application/vnd.ms-powerpoint';
$mime_types['ppt'] ='application/vnd.ms-powerpoint';
$mime_types['ps'] ='application/postscript';
$mime_types['pub'] ='application/x-mspublisher';
$mime_types['qt'] ='video/quicktime';
$mime_types['rtf'] ='application/rtf';
$mime_types['svg'] ='image/svg+xml';
$mime_types['swf'] ='application/x-shockwave-flash';
$mime_types['tif'] ='image/tiff';
$mime_types['tiff'] ='image/tiff';
$mime_types['txt'] ='text/plain';
$mime_types['wav'] ='audio/x-wav';
$mime_types['wmf'] ='application/x-msmetafile';
$mime_types['xls'] ='application/vnd.ms-excel';
$mime_types['zip'] ='application/zip';
// did we get a parameter telling us what file to download?
if(!$_GET['file']){
// if not, create an error message
$error='No file specified to download';
}elseif(!in_array($_GET['file'],$files)){
// if the file requested is not in our array of legal
// downloads, create an error for that
$error='Requested file is not available';
}else{
// otherwise, get the file name and its extension
$file=$_GET['file'];
$ext=strtolower(substr(strrchr($file,'.'),1));
}
// did we get the extension and is it in our array of content types?
if($ext && array_key_exists($ext,$mime_types)){
// if so, grab the content type
$mime=$mime_types[$ext];
}else{
// otherwise, create an error for that
$error=$error?$error:"Invalid MIME type";
}
// if we didn't get any errors above
if(!$error){
// if the file exists
if(file_exists("$file")){
// and the file is readable
if(is_readable("$file")){
// get the file size
$size=filesize("$file");
// open the file for reading
if($fp=@fopen("$file",'r')){
// send the headers
header("Content-type: $mime");
header("Content-Length: $size");
header("Content-Disposition: attachment; filename=\"$file\"");
// send the file content
fpassthru($fp);
// close the file
fclose($fp);
// and quit
exit;
}
}else{ // file is not readable
$error='Cannot read file';
}
}else{ // the file does not exist
$error='File not found';
}
}
// if all went well, the exit above will prevent anything below from showing
// otherwise, we'll display an error message we created above
?>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;
charset=iso-8859-1">
<title>Image Download</title>
</head>
<body>
<h1>Download Failed</h1>
<?php
if($error) print "<p>The error message is: $error</p>\n";
?>
</body>
</html>
Okay, that should do it. The script first defines a variable
to hold the path where the files are stored. Then fills
an array with the file names of those files in that directory.
Next, it creates an array of file extensions and their
corresponding content types. Next, it checks to see if
it got a parameter telling it what file to download. If
not, it generates an error. Next, it checks to see of a
received parameter matches any of the files in that directory.
If not, it generates an error. If everything is okay so
far, it gets the file extension of the requested file and
then checks to see if it has a content type to match it.
If everything is still alright, it get the file size, opens
the file. If that's successful, it sends the needed headers
of Content-Type, Content-Length and Content-Disposition,
then uses the PHP fpassthru function to send the file to
the browser. It then closes the file and exits. If anything
has gone wrong throughout the process, it sends the error
message to the browser instead. It's all pretty simple,
really.
By the way, if you need a content type that's not included
above, W3Schools has a pretty good list
of MIME types.
Now, let's take it a step
further. We're going to create a directory called downloads.
Save the above code in that directory as index.php. Create
a subdirectory under that downloads directory called files.
Anything you drop in that files directory can be downloaded
by simply linking to downloads/filename. Here is an example
to download an Adobe Acrobat file named HelloWorld.pdf.
The link, in this case looks like downloads/index.php?file=HelloWorld.pdf.
As long as the file is in that downloads/files directory
and the file type is in our array of file types, it will
work. Here is a similar link to a .jpg image: downloads/index.php?file=image024.jpg.
Now, as slick as the above is, it's still just the slightest
bit messy. It still has those nasty url parameters in the
link. If you can use a .htaccess file on the server, you can
make it even slicker. The following .htaccess file in the
downloads directory will take care of that:
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule (.*) index.php?file=$1 [PT,L,QSA]
What this .htaccess file does is tells the server that if
the requested file is not a regular file and it's not a
directory, to append the requested file name as a parameter
named "file" to the index.php file. So it will take
that request for HelloWorld.pdf and change it to index.php?file=HelloWorld.pdf
like we had above.
Now
look what we can do. In this case, we're going to link
to downloads/HelloWorld.pdf.
The .htaccess transparently changes that to downloads/index.php?file=HelloWorld.pdf..
It looks just like any other link, but still generates
the download dialog. Here is the .jpg image link downloads/image024.jpg.
Okay, I've rambled on long enough. Have fun with it!
