PHP Toolbox
http://www.phptoolbox.org
Copyright (c) 2009-2011 James Watts (SOLFENIX)
http://www.solfenix.com
This is FREE software, licensed under the GNU/GPL
http://www.gnu.org/licenses/gpl.html
REQUIREMENTS:
-------------
To use the PHP Toolbox you will need PHP 5 installed with the
SimpleXML extension. The script is cross-platform, although some
Tools may be platform specific.
IMPORTANT SECURITY WARNING:
---------------------------
The PHP Toolbox grants the user access to the server shell. This is NOT
something want an anonymous visitor having access to. There are 3 steps
you can take to make sure your server is never compromised:
- Keep the script located in a password protected directory
- Rename the "toolbox.php" file to something unpredictable, which is
not a common word in the dictionary, such as "1337-5H17.php"
- Only upload the script when required and delete directly after use
OVERVIEW:
---------
The PHP Toolbox is an extensible, cross-browser script written in PHP for
developers and system administrators. By default, the script provides a
browser based interface with a console to execute shell commands on the
server. However, you can easily extend the functionality of the script by
adding third-party Tools, no installation or configuration required.
To download more Tools, visit the official Tools repository:
http://phptoolbox.org/get-tools
To use the PHP Toolbox, simply upload the file "toolbox.php" to a location
in your webroot, for example:
/htdocs/toolbox.php
Once you have uploaded the file, enter the URL of that location on your
server, which in the case above would be:
http://example.com/toolbox.php
You can upload the script where you like, but remember that all commands
will be run relative to that location on the server's filesystem. This is
important when using the console, as the command "ls -la" will return the
contents of the directory where the PHP Toolbox is located.
To use additional Tools with the PHP Toolbox make sure you upload the
"toolbox" directory where the script is located, and add the Tools you
want available into that directory. The general idea of the PHP Toolbox
is to fill the "toolbox" directory with the Tools you use on a regular
basis, just like a real toolbox. Then all you have to do is carry the
script and directory with you and upload it where required.
If you aren't interested in using the web based interface you can also
call the script directly from a URL:
http://example.com/toolbox.php?load=%TOOL%&run=%FUNCTION%
Where %TOOL% is the Tool (directory) you wish to load and %FUNCTION% the
function of that Tool you are going to execute. You can easily discover
the URL representation of Tools by calling them from the web based
interface and viewing the output URL in the browser's address bar.
CREATE A NEW TOOL:
------------------
Creating a Tool is as easy as creating 2 files: "tool.php", which
contains your PHP class, and "config.xml", which contains the UI for
your Tool.
A basic PHP class for a Tool would look something like this:
<?php
class EXAMPLE extends TOOLBOX {
public $name = 'Example';
public $version = 1.0;
public $author = 'James Watts';
public $licence = 'GPL';
public $link = 'jameswatts.info';
public function test() {
if($this->exist('say')) {
$this->output('You said: '.$this->query('say'));
} else {
$this->error('You need to say something!');
}
}
}
?>
Here we are creating the class EXAMPLE, which extends the class TOOLBOX.
This class contains the following methods:
exist(string $name) - check if an argument was passed with the URL
query(string $name) - get a value by argument name from the URL
output(string $message) - print the result of the operation
error(string $message) - print the error that occurred
This is then saved in "toolbox/example/tool.php". As a convention, all
classes are declared in UPPERCASE, and all file and directory names must
be in lowercase.
To run the function "test", you would enter the following URL:
http://example.com/toolbox.php?load=example&run=test&say=Hello
Now that we have a Tool, all we need is an interface for it. The script
generates the UI for each Tool by parsing an XML file which defines the
controls. Lets create the UI for our new Tool:
<?xml version="1.0" encoding="utf-8"?>
<config>
<title>
An Example Tool
</title>
<description>
This is an example Tool to show off some UI.
</description>
<forms>
<form name="test" submit="Test It!">
<input name="say" type="text" label="Say" />
</form>
</forms>
</config>
This is the XML configuration file for our Tool. It contains the
definition of the form the user will see in the web interface.
Each <form> in <forms> represents a function in your class. The "name"
attribute is the function name the form will call, and the "submit"
attribute is the text that is displayed on the submit button of the
form.
Every form can have multiple <input> values, which each represent an
argument passed in the URL. For example, in the class we created, the
function "test" expects an argument named "say", so we'll create an
input for that argument with the "name" attribute as "say". An <input>
also has the following attributes:
type - can be text, password, checkbox, textarea, or select
label - the text that describes the input
optional - displays that the input is optional if set to "true"
summary - displays a summary text to explain the input's use
If you set the "type" attribute of an <input> to "select", the <input>
can have multiple drop-down <option> elements with the following
attributes:
name - the text displayed in the drop-down option
value - the value that is passed in the URL
Which input types you choose in your form is up to you, just remember
to keep it short and simple.
