PHP Traverser Latest version: 0.8.2.2 >>> Instant action (online demo) <<<

[ Self ref. 1 ] [ Self ref. 2 ] [ S I T E M A P ]

Quick jump: [ GraphViz Sitemap example ]

Smarty template engine: The script's HTML output is generated with the Smarty template engine. Now it's much easier to customize the output to your needs.

Description ( Top )
PHP Traverser is a script that makes a directory browsable recursively, i.e. with this script it is possible to browse a whole directory structure, where the root of this tree is the directory where the script was placed.
Other features: download list of all the files in the current dir (for the fans of mass download), GraphViz sitemap visualisation, Search function (basic and advanced (regular expressions)), image and mp3 browser plugins, session-based shopping cart to easily collect files you want among directories.

What it is good for ( Top )
It is ideal if you want to share some stuff with your friends. You just make a directory, place the script there and then you can drop in any files -- the script will autolink everything. It's enough to send one link to your friends, which points to the script.
I wrote it because on the webserver in my university the automatic index.html generation in a requested directory was disabled (as well as CGI). First I wrote a Perl script that made an HTML page, but it was static. Whenever the content of the directory changed I had to rerun the script. So it was not very good. Then I had the idea to write it in PHP. It's enough to put the script in a directory, and voilą: everything in this dir. and in every subdir. is available dynamically. From the root point (where it is placed) it makes no link back, so you can be sure that users will stay in the directory that you wanted to show them, except if the parent of the root point also contains a copy of the script: in this case it will join to the parent, and that will become the new root-point. This feature from now on is disabled in default (you can enable it in the config file).

Online demo ( Top )

There are several more versions here; the only difference is the icon set, nothing more, the rest of the code is the same. They may not be the latest version, they just demonstrate the icon sets. If you want to test the current version, try the etalon above.

• simple, default icon set
• complex icon set (but still quite simple), taken from www.hwsw.hu
• complex icon set, KDE style, 32 x 32 pixels (for blind people :))
• complex icon set, KDE style, 26 x 26 pixels (the same as above but a bit smaller)
• complex icon set, KDE style, 16 x 16 pixels (the same as above but even smaller)

An online demo of the password protected version is available here. The code is: http://www.doug-long.com/szilard.htm (just copy-paste the text in bold)
(The source of all these versions is the same, only one variable is changed ).

Note that this password protection is done by sessions. Its feature is that it is joined to your browser. Once you enter the correct code, it'll always let you in, so while testing don't be surprised that it asks the password only once. To close the session you can kill it by calling this script: kill_session.php.

Download ( Top )
You can download the source and its components here.

Older versions are also available.

Install ( Top )
Just download the compressed file and unpack it (under Linux: tar xvzf phptraverse.tar.gz , under Windows use WinRAR). Put the assets directory somewhere in your web page, and modify the script's code a bit: change the variable $BASE and $BASE_URL. Both of them will have to point to your assets directory, but while $BASE must be an absolute path, $BASE_URL is a URL to the assets directory. This directory contains the necessary icons, JavaScript and CSS files. The configuration part is separated from the code, so all you have to do is to set up the variables properly according to your system, and you can copy traverse.php to more places -- just don't forget to change the include path of the config file.

If you want to use password protection: the installation process is almost the same, the only difference is that now we need a password file which contains the encoded password. To generate this file you should run the passgen.php script that is located in the assets/pass_gen directory (./assets/pass_gen/passgen.php). Just type in the password and encode it, then copy-paste the encoded string to the password file (traverse.pwd). You can rename the file, but then don't forget to change it in the config file too!!! Security tip: place the password file outside of the directory where traverse.php is, and in the config file use absolute path to the pasword file. Another tip: change the name of the password file too (a hacker will first try to download the default filename). If you want password protection you only have to change one variable (documented in the config file).

There are 3 possibilities now to set password protection:

1. OFF: no password protection at all
2. ON: password protection is always switched on, i.e. the dir. where the script is placed and every subdirectory is protected. Simply: everything is protected.
3. OPTIONAL: only those directories are protected where a password file exists. When to use it? When you don't want to protect all the directories just some of them. (Note: you may use different password files, but then the script will always ask for the new password when you try to access for the first time).

If you want to use directory descriptions: make a traverse.nfo file in the given directory (this is its default name which can be changed, but don't forget to modify the source code too!), and write your description into it. I have included a simple Perl script that generates a template file with the subdirectory and file names of the directory where you run it. You can find it in the ./assets/description_gen/ directory, its default name is description_gen.pl. Usage: ./description_gen.pl > traverse.nfo. After this you only have to add your descriptions. It is possible that you included a file in traverse.nfo, but traverse.php doesn't show it. Why? It may have several reasons: 1) traverse.php has no rights to read this dir/file. 2) maybe in the config file you disabled this dir/file. Check the $dontShowArray! Be sure that traverse.nfo is readable (Linux: chmod 644 traverse.nfo). Important! $dontShowArray is global, it is set for each directory, while traverse.ex is local, i.e. it is applied only for the dir. where it is placed.

Mimetypes: at last they are here. All you have to do is to change the $mimetypesConfigArray variable in the config file (instructions included there). The icons are in the assets directory. If you want to use your own icons, read the instructions in the assets/mimetypes_20021111.php file. In the online demo section you can check the available icon sets.

Logging: completely new feature. With this you can monitor which file how many times has been clicked on. For more info see the config file, look for the $log_click array. !!! If you want to use this feature, allow it in the config file !!! The script will write to a log file whose default name is traverse_clk.log. On our university webserver I use 755 rights to directories and 644 for files. In this environment the script has no rights to create a new file, but giving write permissions for the directories is to be avoided too, as others have shell access to this server. So my idea is: let's create empty log files in every directory and make them readable/writeable (chmod 646). Thus the script can manipulate the log files. So I have written a simple bash script (in the assets/empty_logfile_gen dir.), called empty_logfile_gen.sh. Copy it to the dir. where the script is located, and run it there. It'll touch the log file (create it if not yet exists) and set its rights. Then delete the bash script from there. Whenever you add some new subdirectories, you should rerun this script to create the empty log files. It won't do any harm to already existing log files. Under Windows I think you can also run the bash script using the Cygwin environment, but first try the traverser script, maybe it can create log files (at home it worked for me).

Maybe it's not the nicest solution, but if you have a better idea, tell me :)

Modules ( Top )

History: let me tell you the story of this module. A few months ago I had the idea to add some kind of visualisation stuff to the project which would permit to see all the subdirectories. At that time I didn't know about the GraphViz project, so I wanted to draw everything "by hand". After a short thinking phase I gave it up saying it's too difficult :-). Later I tried IsaViz (an RDF visualisation tool), which also uses GraphViz, but I didn't realize I could also use it. Then last week (October 2003) I found a project, which is almost what I wanted (http://urlgreyhot.com/graphviz/). The main problem for me with this project was that you have to send a formatted text file and you get a gif. But I needed something which generates images on the fly on my webserver with an imagemap. (That project was not GPL at that time, but changing some e-mails with its author he changed his mind). But this script was good to make me discover the incredible GraphViz tool. Oh my, why didn't I find it a few years ago? :-). This tool contains a graph-drawing software, called dot, to which you send the description of a graph in plain text format (in its own language), and it sends back the graph in the format you want. I found one more useful thing, the Image_GraphViz class in PHP's PEAR repository. I modified this class a bit to my needs.

Installation: to make the sitemap work you need to install the GraphViz software. From this we'll only use the programs dot and neato. Set the path to them in Traverser's config file. We'll also need to write temporary files, its location must be set too (in default under Unix you can use the /tmp directory). After this you should try dot from console first! Make a file (in.dot) with the next content:

digraph G {
   node [fontsize=9];
   A [URL="http://host/a.html"];
   B [URL="http://host/b.html"];
   C [URL="http://host/c.html"];
   A -> B;
   A -> C;
}

Search:
Now you can perform a search on the site where the script is placed. Both basic (exact string-match and substring-match) and advanced (Perl-like regular expressions) search are supported. For more info click on the "Help" link in the search module's window, there you can find a longer description (see the online demo).

Basket:
While browsing among directories now you can drop files into a shopping basket :-), and then get a download list at the end. Easy, ain't it? If enabled in the config file, you'll have a coloumn 'Basket', where there is a link 'Add', that'll add the file to the basket. On the top right hand corner you'll find a link to the basket manager (it also shows the number of items in the cart).

Plugins ( Top )
To different mimetypes you can assign different plugins. You can start a plugin by clicking on an icon on the left side. If something is assigned to this extension then the plugin will start in a new window. If you want to write your own plugin, you have to know that a plugin gets 3 information as GET parameters:
1) the URL of the directory of the file on which you clicked
2) the directory of the file you clicked on
3) the name of the file you clicked on
I think they are enough to work with them. I wrote a template for plugins that can be modified easily, it can be found in the assets/plugins directory. Available plugins at the moment:

 

Name of the plugin	Assigned extension(s)	Origin	Remark
MP3_ID 1.0	mp3	Originally written by Sandy McArthur, now part of the PEAR	MP3 tag reader/writer class.
PHPSlideShow v0.6.2	.gif, .jpg, .jpeg, .png	Greg Lawler, http://www.zinkwazi.com/pages.php?page_name=scripts	The script was originally written by Greg, I have done some modifications to make it "pluggable".

How can you add your own plugin? First you have to register it in the config file (look for $pluginsArray). Write your plugin and put it in the assets/plugins/ directory. These things have to match in the traverse.php and in your plugin script: a) where the script is placed (I recommend the default directory) b) the assigned extensions.
You don't have to write a plugin from scratch, first analyze the template.class.php file and add your modifications.
Last step: don't forget to send me your excellent plugins! :) I'll put them here.

Version history ( Top )

Version	Date	Remark
v0.8.2.2	July 2005	Oh God, I haven't touched my dear script for more than a year! At last I integrated Christian Folini's https protocol patch. Sorry for the delay.
v0.8.2.1	June 2004	Pagetime (time in milliseconds needed to generate the page) is added to the end of pages in HTML comment.
v0.8.2	March 2004	In features it's the same as the previous 0.8.0 version. The only difference is that the HTML output is generated completely with the Smarty template engine, so the customization of the script has become much easier!
v0.8.0	Nov. 2003	This is a milestone release with several new features. First: plugins are not independent PHP files any more but classes in traverse.php, thus within a plugin you can call functions located in Traverser. This way a plugin can also see just those files that are visible to Traverser (before there was a bug that a plugin could read hidden files too, now it's over). New plugin added: mp3 browser. It gives lots of useful information about a song (like in Winamp). New feature: shopping basket. Now you can drop in any file anywhere in the filesystem. When you finished you can easily get a download list of the selected files. This shopping cart is also integrated in the plugins, so if you like a song or an image, just click on 'Add'.
v0.7.9.1	Oct. 2003	a bug fixed in the slideshow plugin
v0.7.9	Oct. 2003	Search module is added, the GraphViz sitemap button works under IE too
v0.7.8	Oct. 2003	Dynamic GraphViz Sitemap module is added.
v0.7.5.1	Oct. 2003	Minor fix: joining to the parent script is now optional (default: no), so now you can rename traverse.php to index.php safely. I got some feedback that the script behaves strangely when it is called index.php, now I found out why :)
v0.7.5	Sept. 2003	The data structure of the script until now was a big mass. Now I rewrote the inner structure completely, I think it became much easier to modify.
v0.7.1	19 Sept. 2003	the script now allows logging how many times a file has been clicked on
v0.7.0.1	11 Sept. 2003	a little bug with special characters like in Portuguese is corrected
v0.7.0	26 June 2003	bug in optional password protection corrected (thanks Paul), code simplified, beautified :). Config part got separated in another file.
v0.6.2.1	19 February 2003	new KDE icon set (16x16), fast-jump thingie
v0.6.2	22 January 2003	corrected KDE icons (thanks to Joel)
v0.6.1	15 January 2003	several minor fixes
v0.6.0	25 Decembre 2002	plugin support
v0.5.0	11 Novembre 2002	different icons for different mimetypes
v0.4.1	10 Novembre 2002	optional password protection for some (selected) subdirectories
v0.4.0	09 Novembre 2002	in each directory you can select which files/dirs you want to hide
v0.3.9.1	04 Novembre 2002	the parent dir. got a new image (thanks to Brandon)
v0.3.9	29 Octobre 2002	now you can click on the gray line anywhere, it will follow the link (thanks to Kim)
v0.3.8	26 Octobre 2002	ALL the elements in the given directory can be described
v0.3.7	23 Octobre 2002	source code completely restructured. CSS and JavaScript codes are separated again. The code of PHP and of the generated HTML is much more readable.
v0.3.6	13 Octobre 2002	directories are shown first, then files (like in Norton Commander clones)
v0.3.5	23 September 2002	the download button can be switched off by changing a variable
v0.3.4	22 September 2002	description can be added to the directories
v0.3.3	21 September 2002	bug fix of the lattest feature (dir. names with spaces)
v0.3.2	20 September 2002	bug fix, now the script can handle directories whose name contains spaces
v0.3.1	19 September 2002	minor bug fixes
v0.3.0	15 September 2002	download-list can be generated, the CSS definition is placed in the body of the script, not separated any more
v0.2.9	28 July 2002	password protection is added
v0.2.2	27 July 2002	better customization, DHTML support can be switched off (for Opera), looks nice again in Netscape 4.x
v0.2.1	18 July 2002	a serious bug corrected thanks to Ly0n (users could browse in parent directories)
v0.2.0	17 July 2002	bug fixed with pointer to parent directory when it also contained traverse.php; CSS support added
v0.1.0	May 2002	first implementation

Known bugs ( Top )
Don't use the search module if your password protection is optional. At the moment the script will also show the files in these directories too. I want to correct it in a future version. Solution at the moment: if you have optional password protection, switch off the search option.

Tips ( Top )
Here are some tips that may not be completely evident:

• Performance tuning: if you have lots of files in a directory, then it can be a good idea to switch dhtml and on_click effects off in the config file, they produce lots of html output taking the bandwidth. You can also play with the 'coloumns' array in the config file what to show/hide to reduce the size of the html result.
• I'm trying to document the source code as well, so if something is not clear here, read the comments of the source too!
• When you move the mouse over a line, a gray rectangle highlights the row. You can click anywhere in this rectangle to follow the link!
• If you want to see an image, click on the icon on the left! Thus an image viewer plugin will start.
• If you want to download everything in a given directory, time to explore the "Download" button! Then save the generated list (for ex. list.txt) and simply pass it to a download manager (wget -i list.txt). Don't worry if in the browser the generated list seems a mess (I mean that filenames are together, not each in a new line). It is because it's a text file, not HTML. But when you save it, it'll be correct.

Ideas / To do ( Top )
Some future ideas that should/could be implemented as plugins:

Assigned extension(s)	Idea from	Description
.zip, .rar, etc.	Max Headroom	content reader :) Yeah, that would be nice! Any idea how to do that? A very simple solution: get a list using the appropriate packer (run it in a process) and show the output. If there's already a PHP modul for this, let me know.

Other ideas:

Idea from	Description
	the order of file list should be changable (ascending/descending by type -- file or dir., and by size)
Celso	create a list with the recent updates
Celso	create a list of the most downloaded files

Otherwise I'm getting to run out of ideas, so let me know what you would like to see in the script...

Related works ( Top )
I agree that open source softwares should link to each other more, offering the public a greater range of choice. Here I'll collect other projects that are related to this in some sense.

• Pathalizer is a tool to visualize the paths most users take when browsing a website. This information can then be used to decide how to improve the navigation of the site, and which parts are most worth improving and keeping up to date. In short, pathalizer generates a directed, weighed graph from an apache log (but it's easy to modify the first part of the process to use pathalizer for lists of other events). View a screenshot.
• The goal of the Autoindex project is to create a "Windows Explorer" that can be used to browse through folders on websites. In its function this project is very similar to PHP Traverser. Autoindex also supports file upload.

Credits ( Top )
I am very grateful for every remark. Without your ideas/support I would have stopped around version 0.3.0.
The following people have contributed code snippets, bug fixes, ideas: Ly0n, Jeff, Aaron, Robert, tom, Kim (sun818@TekGems), Max Headroom, Brandon, Joel, Paul Richmond, Celso Rodrigues, Antonio Nereu, Leknor, Glenn, Martin Carlsson, Christian Folini, Pete Ebeid

Sites/pages where this script is used ( Top )
If you use my script in a public location then I would be happy to put a link here to your page! This way others could see the script in action too! :) So far:

How to contact me ( Top )
You can send your ideas/questions to the project's forum. It is new (started in March, 2004), I hope you'll like it. You can also contact me directly if you want at szathml@delfin.unideb.hu. I am not great at webdesign, so you can send me advises how to improve the layout of this page and the traverse.php as well. Or if you find some grammatical errors, let me know too :) Enjoy using this useful script!

Created by Laszlo Szathmary, alias Jabba Laci, 2002--2005

[ Self ref. 1 ] [ Self ref. 2 ] [ S I T E M A P ]