Documentation

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.

Creaing 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 $requires = null;
    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:

This is then saved in "toolbox/example/tool.php". As a convention, all classes are declared in UPPERCASE, and all file and directory names mustbe 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". The <input> also has the following attributes:

If you set the "type" attribute of an <input> to "select", the <input> can have multiple drop-down <option> elements with the following attributes:

Which input types you choose in your form is up to you, just remember to keep it short and simple.

An XSD (XML Schema Definition) file is available to help you check your XML for the Tool's UI. It can be found here.

Important Security Notice

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: