How to use the Classes

After having installed and configured the classes, you certainly want to use them. Taking the provided example file histview.php, this page explains how to do that: We will setup a simple page which displays your ChangeLog and provides links to download released versions.

Setting it up

Sure, we already configured the classes for "general use" - but there are still some things we better leave for the particular pages as this one - e.g. parameters passed at the URL:

Line	trunk/histview.php
17	#==================================================================[ Setup ]===
18	#-------------------------------[ Read request vars and do some protection ]---
19	$prog = $_REQUEST["prog"];
20	# $prog should only contain letters, digits and "_"
21	if (empty($prog) || @preg_match("/[^\w]/u",$prog)) $prog = "HistView";
22	# $file should be alphanumeric - no special chars or / or \
23	$file = $_REQUEST["file"];
24	if (empty($file) || @preg_match("/[^\w-_.]/u",$file)) unset ($file);
25	# $dir should only be one of ours - here: "tar","deb","rpm"
26	$dir  = $_REQUEST["dir"];
27	if (!empty($dir) && !in_array($dir,array("tar","deb","rpm"))) unset ($file,$dir);

The lines 19, 23, and 26 pick some arguments from the URL and assign them to local variables, so it is easier to access them. The lines following these assignments shall provide some protection against hackers code injection and the like: So we define that the "prog" name only may contain letters and digits (line 21). If there is any other letter in the string, or the string is empty, we assign it a default.

Analogue to that we protect the file name, which should be alpha-numerical (letters, digits, the minus, the underscore and the dot - but e.g. no slash ("/") or backslash ("\") to prevent the delivery of system-wide files). If this is violated, the file name will be unset, and no file is delivered (line 24). As for the directories (line 26+27), we know there should be only those we have defined - humm, or we go to define in the next section.

To prevent PHP Notices to be thrown if (one of) those arguments are not passed, you could add some code around the particular block - so for the "prog" it would look like:

<?php
if (isset($_REQUEST["prog"])) {
  $prog = $_REQUEST["prog"];
  if (empty($prog) || @preg_match("/[^\w]/u",$prog)) $prog = "HistView";
} else {
  $prog = "HistView";
}

Line	trunk/histview.php
29	#------------------------------------------------------[ Setup directories ]---
30	$dirs = array( "tar" => "/var/ftp/downloads",
31	"deb" => "/var/repo/debian",
32	"rpm" => "/var/repo/redhat/RPMS.dist" );
33	$charset = "iso-8859-15";

Finally you may need to setup the directories (lines 30-32 - but you can of course also reference the directories configured with the classes), and the character set which we will use at a later time.

Processing a file request

No we go for the real thing: Before we display our ChangeLog, we need to see whether we should deliver a file instead:

Line	trunk/histview.php
35	#========================================================[ Process Request ]===
36	#----------------------------------------------[ Was a download requested? ]---
37	if (!empty($_REQUEST["file"])) {
38	include("class.download.inc");
39	if (!empty($file) && !empty($dir)) {
40	$dl = new download();
41	if ($dl->sendfile($file,$dirs[$dir])) exit;
42	}
43	$e404 = "\n<DIV CLASS='ebox'>Sorry - but the requested file was not found here.</DIV>";
44	} else {
45	$e404 = "";
46	}

Note that in line 37 we check for the $_REQUEST variable though we already assigned it to a local variable? This is not an accident, but intended: We need to check whether something was requested - not if something has to be delivered. The latter is checked at line 39: If both $file and $dir are empty while the corresponding $_REQUEST variable was set, they have been cleaned up. So we handle it the same as if the file was not found: If it were found, it would have been sent at line 41 (and the script would have stopped). Since we are still here, the error message will be setup instead. If you think line 38 could better be moved into the if condition (i.e. it should be at line 40), you are right - feel free to do so, this is just an example

If you want to reference the directories configured with the classes instead, change line 41 to

if ($dl->sendfile($file,$hv->${dir}base)) exit;

Display the ChangeLog

If either the file request failed, or there has not been any - we are still here, and the script is still running. So now we go to display the ChangeLog:

Line	trunk/histview.php
48	#-----------------------------------------------[ Display the history file ]---
49	include("histview.inc");
50	$file = $dirs["tar"]."/".strtolower($prog).".hist"; // ChangeLog to parse
51	# Simple method, no download links to provide:
52	#$hv = new histview($file);
53	# Providing download links:
54	$hv = new histview($file,strtolower($prog));
55	# Setting up the directories
56	$hv->set_basedir("tar", $dirs["tar"]);

First we of course need to include the class (line 49), and create an instance of the class (line 54) - which will automatically execute the configuration we made before - so we only have to provide it with the missing directory for our .tar.gz files (line 56), and we are done so far.

Line	trunk/histview.php
58	# Process the page
59	$hv->process();
60	$history = $hv->out();
61	$title = "History for $prog";
62	echo "<!DOCTYPE HTML PUBLIC '-//W3C//DTD HTML 4.01 Transitional//EN'>\n";
63	echo "<HTML><HEAD>\n"
64	. " <META HTTP-EQUIV='Content-Type' CONTENT='text/html; charset=$charset'/>\n"
65	. ' <LINK REL="stylesheet" TYPE="text/css" HREF="histview.css">'."\n"
66	. " <TITLE>$title</TITLE>\n"
67	. "</HEAD><BODY>\n<H2>$title</H2>\n";
68	echo $e404;
69	echo $history."\n</BODY></HTML>\n";

In line 59 we tell the class to process our ChangeLog and also check for all related files, and then we obtain the well-formatted ChangeLog and assign it to the local variable $history in line 60. Lines 61-67 output the HTML header and start of the page. In line 68 we place our error message (which may be empty), and finally at line 69 all the content will be sent to the browser, and the page will be closed - task completed!