a nice photo of my face :D

PHP Traverser

Latest version: 0.8.2.2

>>> Instant action (online demo) <<<
 


Quick jump: [ GraphViz Sitemap example ]

What's new?     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.

  1. Short description
  2. What it is good for
  3. Online demo
  4. Download
  5. Install
  6. Modules
  7. Plugins
  8. Ideas/To do
  9. Related works
  10. Version history
  11. Known bugs
  12. Tips
  13. To do
  14. Credits
  15. Sites/pages where this script is used
  16. Contact
Rate My Program
@ HotScripts.com
Excellent!
Very Good
Good
Fair
Poor


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 )

The etalon is here.

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.

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 )

Dynamic GraphViz Sitemap:
With this module you can easily visualize the structure of your whole site! The module will explore recursively your site from the point where you placed the traverse.php script, it will generate dynamically a tree of your directory structure, and it adds an imagemap to this too, so each node in the graph is clickable. This permits an extra-fast jumping among directories (paticulary useful if you have a big website with lots of directories). example graph

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;
}

Then try to make a gif file of this:  dot -Tgif in.dot > in.gif
Try also if the imagemap works:  dot -Tcmap in.dot > in.cmap
If everything was fine, you can try the sitemap in your browser.

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:

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.

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:

No.
URL
Maintainer
Remark
1.
http://www.maxheadroom.nu/files
Daniel Johansson, a.k.a. Max Headroom
Max sent me very useful ideas, bug reports. v0.6.1. was mainly inspired by his ideas
2.
http://tekgems.com/dl/
sun w. kim <sun818@TekGems>
 
3.
http://www.mofra.org.br/cgi-mofra/biblio/arq/Documentos/
Celso Rodrigues
Celso gave me lots of good ideas (for ex. the logging)
4.
http://weblog.ods.org/ftp.php
Liu Yu-sheng
 

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
 
Last modified: 2007.07.31, 11:01, Jul., Tue