============================
class.dnl.php's User Guide
version 0.2 - 07/05/2020
============================
class.dnl.php is a PHP class allowing to download files located
on your website or anywhere else and to log these downloads
into logfiles, by email or into a database or by combining
several of these possibilities.
This class can be used by your webserver, not your FTP server.
It does not replace the logfiles of your web server which will
continue to runs normally but allows you to log the download
of special files that you want to have a look on.
The download service contains 3,4 and maybe 5 files :
- the class.dnl.php (class which can be copied into the dnl.php file)
- the dnl.php file (to use as href into your download links)
- the files2dnl.txt (which contains the downloadable files and what logs to do)
- the dnl_log.txt (if logs have to be writen in a logfile)
- the dnlexept.txt (holding the forbidden strings in the user-agent : robots, webcrawlers
Website structure
=================
/-----------+
+--dnl
files of | index.php // header("location: /index.php"); // Nothing to see
the website | files2dnl.txt // list of downloadable files
| dnlexcept.txt // blacklist for robots
| file_1.zip
dnl.php | file_n.zip
(to use in | .. other downloadable files...
links for +--lib
downloads) | class.dnl.php // the download class
| ...other lib files...
+--logs
| dnl_log.txt // used if you log downloads into file
| ...other log files...
+--other-dirs...
Directories
===========
0) / : It's the root directory of your website
1) /dnl : It's the directory where your downloadable files are located
2) /lib : It's the directory of your libraries (such as classes)
3) /logs : It's the directry of your special logfiles
class.dnl.php
=============
It's the class itself. This file can be located into your /lib directory.
You can include it in the dnl.php file with require() or you can copy
the code of the class in it instead of require().
If you want to log into a databases, using PDO, you can use several types :
- MySQL
- IBM
- Informix
- ODBC et DB2
- PostgreSQL
- SQLite
You have to modify the members of this class with your own parameters (mail,
database --type, host, port, name, user, password--, logfile, etc... Once
you have changed your information, you no longer have to touch it.
Put it in the /lib directory.
dnl.php
=======
The dnl.php file can be stored with the other files of your web site,
i.e. in the root diretory of it.
You have to use this file in your links as below :
- Download <a href="dnl.php?f=3">this file</a>.
or
- Download <a href="dnl.php?f=eccbc87e4b5ce2fe28308fd9f2a7baf3">this file</a>.
The content of dnl.php is short :
<?php
$num = $_GET["f"];
require("lib/class.dnl.php"); // instead of require(), you can copy here the content of class.dnl.php
if($num) { $file = new dnl($num); }
?>
files2dnl.txt
=============
files2dnl.txt is a textfile which is read and exploited by the class.dnl.php
This file can be generated by mkfile2dnl.php (either in a web browser of in a
terminal). You just have to write the first and the last ID you want before use
as well as the default action (type of log).
Format of each line :
num;md5(num);action;subject;filename|url
Examples :
1;c4ca4238a0b923820dcc509a6f75849b;0;;photos.zip
12;c20ad4d76fe97759aa27a0c99bff6710;3;Zipped Gedcom File;gedcom.zip
13;c51ce410c124a10e0db5e4b97fc2af39;1;;https://portableapps.com/downloading/?a=GrampsPortable&n=Gramps%20Portable&s=s&p=&d=pa&f=GrampsPortable_3.4.9.paf.exe
where :
- field 1: num (ex: 12)
is a sequential number (1, 2, 3, ...) used as the ID of the file to download
- field 2: md5(num) (ex: c20ad4d76fe97759aa27a0c99bff6710)
It's the md5 of num. [here, md5(12)]. It's another ID of the file to download
It's possible to use either num or md5(num) as ID of the file to download.
If somebody downloads several files (file 1, file 2, etc.) using the ID num :
dnl.php?f=1, dnl.php?f=2, etc., maybe he can tries to download all your files
using the other numbers (dnl.php?f=3 ... dnl.php?f=97, etc.)
If you use md5(num) as ID, he don't knows if the ID is a random string or
a md5(number) or a md5(string filename) and it's really more difficult for an
Internet user to try to download all your files.
So, as for me, I prefer to use md5(num)
- field 3: action (ex: 3)
the field action (as a number) can be :
. 0 : no action (no special log) when a download occurs
. 1 : log it to a file
. 2 : log it with a mail
. 4 : log it to a database
it's possible to combine several actions. examples:
. 3 (file + mail)
. 7 (file + mail + database)
In all cases the file located on your web server will be logged in your http
server logs, even if no action (action=0) is specified in the files2dnl.txt
- field 4: subject (ex: Zipped Gedcom File)
This field is only used if you want log the download with a mail sent to you.
It indicates the subject of the mail, subject preceded by the member $subject ("[DNL]")
Not used when no action or log into a file or a database. So, if you log without
mail, this field can be empty or with a 0 value.
- field 5: filename|url (ex: gedcom.zip | http://www.website.com/path/to/file/file2download.ext)
a) filename : It's the filename of the file to be downloaded from your website
and from the download directory. If you write only the filename, the file
sent will be the file stored into www.yourwebsite.com/dnl (or the directory
specified in the class.dnl.php, $dnldir member)
If the file proposed to be downloaded is located in another place in your
website, you have to indicate the complete url of that file such as :
http://www.your-website.com/other/path/to/file/yourfile.zip
in this case (in that initial version) your file will be considered as an external
file to your web server ; so, it will be sent but the size will not be reported.
Maybe corrected in the next version of that class.
b) url : It's the filename with its complete URL on the Internet. So, you can
propose to download files which are stored on others hosts and log these downloads
(file, mail, database --without their size--) but not into your http server logs.
dnlexcept.txt
=============
Robots and webcrawlers search the web and collect all the links to reference them.
We can see it in the log files of web servers the user-agents recorded such as :
- Mozilla/5.0 (compatible; AhrefsBot/6.1; +http://ahrefs.com/robot/)
- Mozilla/5.0 (compatible; SemrushBot/6~bl; +http://www.semrush.com/bot.html)
- Mozilla/5.0 (compatible; DotBot/1.1; http://www.opensiteexplorer.org/dotbot, help@moz.com)
- Mozilla/5.0 (compatible; Seekport Crawler; http://seekport.com/)
The dnlexcept.txt file will be in the directory of files to download ($dnldir = ./dnl)
and will contain the characteristic character strings that can be identified in these
user-agents such as :
-----------
bot/
bot.
webcrawler
-----------
A visitor user-agent containing these character strings will end the download and the file will
neither be sent nor logged. You can update this file if new robot characteristic strings are found.
The strings in this file can be written in upper or lowercase.
Where to log
============
1) file : dnl_log.txt :
-----------------------
jj/mm/aaaa hh:mn:ss;ip-number;file-ID;size;downloaded-file;user-agent
2) Mail :
---------
Specify your mail address in the class.dnl.php, $to and $headers members
3) database : Table site_Downloads v0.1 :
-----------------------------------------
CREATE TABLE site_Downloads (
`idd` INTEGER NOT NULL AUTO_INCREMENT COMMENT 'ID of the download',
`datime` DATETIME NOT NULL DEFAULT '0000-00-00 00:00:00' COMMENT 'Date-time of the download',
`ip` VARCHAR(20) NOT NULL DEFAULT '' COMMENT 'Download from that IP',
`idf` INTEGER NOT NULL DEFAULT 0 COMMENT 'ID (num) of the downloaded file',
`bytes` INTEGER NOT NULL DEFAULT 0 COMMENT 'Size of the downloaded file',
`fname` VARCHAR(250) NOT NULL DEFAULT '' COMMENT 'File downloaded: file or URL',
`ua` VARCHAR(128) NOT NULL DEFAULT '' COMMENT 'File downloaded with that user-agent',
PRIMARY KEY(`idd`)
) ENGINE=MyISAM COMMENT='Downloads table';
NB: If you change the table name, change the $table member in the class.dnl.php
If you have some other questions, feel free to mail me at pierre@fauque.net or
tweet me at @fr_phpuser
07/05/2020. Pierre Fauque
|
Download
