File: readme.txt

This is very simple and convenient class for any site that has download option.

Usually, if you need download option you make a link to the file. By pressing 
on this link, the user automatically gets the dialog box to download/open file
in the link.
	Example:
	<a href="/download_folder/download_file.ext">Download Now</a>
In this case everything will work fine, but you have to put "download_file.ext"
under the web server file system and link will show part of this file system,
such as "/download_folder/".

In some cases you need to "hide" the file system location of the file, or make 
available to download from a file system that is not under the web server.
Very good examples as publishing spreadsheets, mp3s, files accessible just for 
particular group of users.  DOWNLOADFILE class will cover all of these cases and 
your link to the download file will look like:
	<a href="file.phtml">Download Now</a>. 
Yes this is link to PHP script, not to your file.

HOW TO:

1. Copy class DOWNLOADFILE to your includes directory.
2. Create PHP script that will include this class: 
	include("downloadfileclass.inc");
3. Make instance of the DOWNLOADFILE object:
	$downloadfile = new DOWNLOADFILE("/dir1/dir2/dir3/filename.ext");
Note: In the constructor of class you MUST specify at least path to the download
file. This path is mandatory argument of constructor and it MUST be on same 
computer where your web server is. It must be accessible from the server - no 
remote files. You may get this path from Database, pass it as a part of any POST,
get it from Session, GET or hardcode it, etc.
4. Use method df_download() to begin download this file:
	$downloadfile->df_download()
Note: This method return FALSE if initialization is not successful and headers with 
file on success. So, you may check return value.

OPTIONS AND FEATURES:

1. In constructor of the class you have additional parameters with default values.
	DOWNLOADFILE($df_path, $df_contenttype, $df_contentdisposition, $df_filename)

$df_path - mandatory parameter, path to download file.
$df_contenttype - optional parameter, content type of the file. 
	Default is "application/octet-stream". Example for PDF document "application/pdf".
$df_contentdisposition - optional parameter, content disposition.
	Default is "attachment", you may use "inline" mode too.
$df_filename - optional parameter, file name for user.
	Default is same file name as on your file system, you may specify any.
2. You may change any of parameters at any time, without create additional instances
of object:
	Ex. $downloadfile->df_contenttype = "application/pdf";
3. Three private methods of the class available, you may use it to get some 
debug information:
df_exists() - return TRUE if file exists by path specified, otherwise FALSE.
df_size() - return size of download file.
df_permitother() - return part of octal number for group "OTHER". For success 
download file have to have reading permission for this group. (Numbers 4,5,6,7) 
4. One public method available for this class:
df_download() - download file, return FALSE for failure and send headers and the 
file on success.

NOTES:

1. If you use session to deliver information about real file path or just
 start session in file.phtml (file that actually call method of the class)
 DON'T FORGET before you start session set session_cache_limiter(), ex:
session_cache_limiter("");
session_name("SID");
session_start();
2. DON'T USE in file.phtml (file that actually call method of the class)
 headers that set expiration date of the file to past, ex:
Header("Expires: Sat, Jan 01 2000 01:01:01 GMT"); - DON'T USE IT


Author: Viatcheslav Ivanov, E-Witness Inc., Canada;
mail: ivanov@e-witness.ca;
web: www.e-witness.ca; www.coolwater.ca; www.strongpost.net;
version: 1.00 /08.19.2002