DirPHP
DOCUMENTATION

1. INTRODUCTION

DirPHP is a simple tool for working with files over the web. It can perform many of the functions of FTP but does it instead over an HTTP connection through a web browser. This allows it to be extremely convienient to use since no external application is needed to do trivial tasks such as deleting and renaming files, viewing contents of folders, uploading files, etc. However, DirPHP has several features that FTP has yet to feature. DirPHP uses a color-coding scheme to organize files by type (image, folder, compressed....) in an easily readable fashion. Another feature is its built-in .php source code reader. Any .php file that is clicked on from a directory listing will make DirPHP show the syntax-highlighted source code of the file. This makes debugging and viewing .php files' source code fast and convienient from remote locations. DirPHP includes single-file upload capability and deleting and renaming tools. New to DirPHP is a basic user authentication system to prevent unauthorized access, although it is strongly not recommended that the script be used on the front ends of websites without disabling some of the potentially harmful functions of the program.

Advantages
A key advantage of DirPHP over similiar applications is its speed. DirPHP is built to run fast and be as efficient as possible. It achieves this by not using image icons next to files as some comparable scripts do. Instead, DirPHP uses the faster colored text approach using CSS style sheets. In fact, only one image is present in the entire script, the logo image, and even it is optional! All colors and fonts can be controlled by the included style sheet. Another advantage of DirPHP is that it can be used inside your existing applications with ease. DirPHP is written as a PHP class, using object-oriented code structures. Your existing application can integrate DirPHP by simply including the class and creating an instance of it. Of course, DirPHP can act as a standalone script and given proper header and footer HTML code, but this is not required so it can be easily included into your site. Finally, DirPHP is easy to add-on to or to customize to fit your exact needs. Configuration variables are present to turn almost every aspect of the program on or off, making it simple to modify for your uses.

Package Contents

• dirphp_class.php - the DirPHP php class; basically, the most important piece
• dir.php - the call-script. This file has an include() for dirphp_class.php and it creates a class instance and starts the program. Navigate to this page in your browser to see DirPHP work. (Note: if you are integrating DirPHP into your own script, you do not need this.)
• dirphp_style.css - the style sheet for DirPHP, including the color-coding schemes for different filetypes. Edit this file to customize all colors, fonts, sizes etc for your copy of DirPHP
• dirphp.gif - the DirPHP logo, the only image that DirPHP uses! (optional, but appreciated for you to include it :)
• dirphp_readme.htm - the documentation file you are reading right now
• COPYING - a copy of the GPL license which DirPHP is distributed under
• make_hash.php - a little utility for generating your hash (if you are using the built-in security)

2. INSTALLATION

Standalone
Installing DirPHP is simple. If you want to use the program as a standalone script (not included in your existing application) follow these easy steps:

1. Download the latest version of DirPHP to your computer. Extract the folder standalone to your computer.
2. Upload dir.php, dirphp_class.php, dir_style.css, and dirphp.gif to your webserver in the directory you wish to be able to view using DirPHP.
3. CHMOD any directories you want to be able to upload to to 777 (you may want to make a separate folder for DirPHP to protect your crucial files).
4. Go to dir.php in your web browser, ex- http://www.yourdomain.com/dir.php.

And that's it. You are free to rename dir.php to anything you choose but if you rename the other files, you must know how to change their file names in the script's code and doing so is not reccommended.

Integrated in your application/script
If you want to integrate DirPHP into your existing script, it will require just a little more work. Follow these steps below. More detailed configuration options are discussed further. Note: Due to how DirPHP's authentication scheme works (using cookies), if you embed it into another page, it will not work. So, to integrate it in your application, you will need to disable the built-in security. Either way, we reccommend you use a different security mechanism that is possibly already present in your application as DirPHP's security is knowingly not rock solid.

1. Download the latest version of DirPHP to your computer. Extract the integrated folder to your computer.
2. Upload the files dirphp_class.php, dir_style.css, and dirphp.gif to your webserver in the same directory as the file you are integrating DirPHP into.
3. In the .php file you are integrating DirPHP into, insert these lines to create a DirPHP class instance and run the script:
   
   // DirPHP Include Lines
   require("dirphp_class.php");
   $dirphp = new DirPHP("m/d/y");
   $dirphp->security['authentication_on'] = 0;
   $dirphp->handle_events();
4. Go to the page you embedded DirPHP into in your web browser.
5. Once your basic DirPHP code is working, read on to configure it more specifically to your needs.

3. CONFIGURATION

DirPHP is built to be customizable to fit you and your application's needs. Almost every feature of the script is able to be switched on or off. Other settings include abilities to show/hide specified files, disallow files from being overwritten, etc. A list of all available options is below:

Standard options

• upload_on
  Turns on/off upload functionality. Default is on (1)
• delete_on
  Turns on/off deleting function. Default is on (1)
• rename_on
  Turns on/off renaming function. Default is on (1)
• edit_on
  Turns on/off edit function. Default is on (1)
• php_source_view
  Turns on/off php source viewing functionality. Default is on (1)
• allow_php_uploads
  Allows/disallows php files from being uploaded. PHP files can potentially contain harmful or security-compromising code. Default is on, allowing php uploads (1)
• delete_confirm
  Turns on/off the pop-up box confirming if you wish to delete a given file. Default (and reccommended) value is on (1)
• upload_overwrite_on
  Allows/disallows file uploads to overwrite existing files if names are the same. Default (and reccommended) value is off (0)
• protected_files_show
  Dictates whether to show files in the $protected_files array (that you have specified). Default is on (1)
• protected_files_php_view
  Dictates whether to allow php source code viewing of any php files in the $protected_files array. Default is off (0)
• allow_higher_level_access
  Allows/disallows higher level directory access. This is potentially a huge security risk as a user could easily put ?dir=../../../.... and reach your root directory. Default (and highly reccommended) value is off (0)
• logo
  Filename of DirPHP logo. Default value is "dirphp.gif"

Security settings

• authentication_on
  Turns on/off security authentication. Use this to enable or disable DirPHP's security as a whole. Default is on (1)
• hash
  The MD5 hash of your desired password. Default value is the MD5 hash of the string "default". You should absolutely change this if you are using the security feature
• allowed_ips
  This array contains IP addresses that are allowed to bypass the security authentication step and be automatically allowed access to DirPHP. Default value is an empty array

Changing A Setting

To change a setting from its default value, you simply have to add a line of code before $dirphp->handle_events();. First pick which setting you wish to change. Take its name as shown above (with underscores and all lower-case) and write the line below in your call file:

Replace YOUR_SETTING_NAME with the name of your chosen setting in the list above and replace VALUE with the number value (0 or 1) of your chosen setting (make sure you leave it surrounded in double quotes). If you leave VALUE blank and leave out the comma, the setting will go to the opposite of what it is currently, basically just the opposite of the default. (Note: the logo setting doesn't use a numerical value but a string value, so if you set it you must surround it in quotes). If you are using the Standalone DirPHP setup (i.e.- using the included index.php file as your call-script) and you have made some settings changes, then your file will look something like this:

The $dirphp->set() statements must be between the new DirPHP() line and the handle_events() line.

Set Security Settings

If you are usign the Standalone DirPHP setup AND wish to use the included lightweight security feature, you must set a few more options in a slightly different way. The security setting authentication_on defaults to on, so you do not need to set that manually. The only setting you need to set manually is the hash value, which is an MD5 hash of your desired password. If you are not familiar with MD5, it is a mathematical algorithm that takes a string of text and generates a 32-character string of letters and numbers representing it. The algorithm is said to be one-way only, meaning you can create a hash from a string of text but you cannot reproduce the string using the hash. What you must do is run the included file make_hash.php in this package and put in your password into the text box and it gives you your 32-character hash. Once you have it, you need to put the folling line into your call-script before the handle_events() line:

Just replace YOUR_HASH_HERE with your 32-digit hash (and leave the double quotes).

4. LICENSE

DirPHP is distributed free of cost under the GNU General Public License. This means you may use it for free and modify it to suit your needs, so long as you distribute your modified version to anyone who asks for it free of cost. This is a shortened version of the included license, which is in the COPYING file of this package.

5. ABOUT

DirPHP was originally created as a workaround script, an exploit of a loophole in the system. I wrote it simply to be able to have similiar functions as FTP but over the web. Not only for directory listing and uploading, but for one special reason. As a PHP programmer frequently working remotely from my home PC, I wanted a convienient way to view the unparsed php source code to my scripts without having to use a third party client. DirPHP does this, and even has syntax highlighting (thank you, highlight_file() ). The most specific use of this program for me was during school (webmastering class, lol). My school district blocks FTP traffic, but doesn't filter HTTP file uploads. The whole thing has worked beautifully and I have had enough response from the users that I have expanded that little first version to what it is now, 1.0. Feel free to use this however you wish.