The following are two examples of install.php code. It's recommended that you have already read the SDK: An Overview page, and at least glanced over SDK: Variables, Commands, and How-Tos so that you can understand these examples.

There are two examples because there are two common approaches to creating an Installatron installer. The first method is to do the complete install within Installatron, and the second method is to use Installatron to "get the files ready" and then call on the software's own installer to complete the process. The former approach is always preferable, however it is not always easy to cleanly replicate all the install steps in an installer.

The former method is affectionally known as the Custom Inputs method, because custom fields are typically used with this method but not with the other, and the latter method is known as the External Task method, because an external install script is used. Both methods are valid, so it's really just a question of what works best for the script you're installing.
Click on these headers to look at each example:

In this example we are going to install an imaginary script called Super Duper, version 3.1.0. The installer id will be "superduper".

We have already downloaded the archive and read the install documentation, so we know what needs to be done. The task at hand is to recreate those install steps in install.php. Let's get to it:

//==========================================================================
// STEP I: SETTINGS
//==========================================================================

// Step 1 is _always_ the settings page, where the user is asked to select a location for
// the install and perhaps configure some database stuff. Most of these settings are
// automatic, however we can use step1_init to add our own settings, which we will do here.

// The _init half of a step "defines the page".

public function step1_init()
{
    // The '_init' part of a step always has one of these $this->setStepLabel() commands.
    // This sets the text that appears under the progress bar for this step. For step 1
    // we always use the locale key "_step_progress_settings", which in english is the
    // word "SETTINGS".
    $this->setStepLabel("_step_progress_settings");

    // Here are the "Custom Inputs" from which this install method gets its name.
    // The settings engine can do just about anything, but these are three commonly used
    // custom inputs.
    $this->setInputFields(array(
        array(
            // Our first input is named 'uname' and is a type 'text' with a default
            // value of 'admin'. This input is actually 'readonly', meaning that is here
            // only so that the user knows the username 'admin' will be used for this
            // install. STORE means that Installatron will remember this value, so
            // the user can find it again using the [notes] button in Installatron.
            "ID" => "login",
            "LABEL" => "_info_adminusername",
            "TEXT" => "_settings_adminusername",
            "TYPE" => "text",
            "VALUE" => "admin",
            "STORE" => true,
            "READONLY" => true,
        ),
        array(
            // A password field, also stored, named 'passwd'.
            // The LABEL is the text that appears on the settings screen and the TEXT is
            // the text that will appear on Notes and Summary pages. Usually the TEXT
            // version is shorter. As with 'admin', the password uses some official
            // installatron text for LABEL and TEXT. Using offical locale keys means
            // that they will automatically work in different languages.
            "ID" => "passwd",
            "LABEL" => "_info_adminpassword",
            "TEXT" => "_settings_adminpassword",
            "TYPE" => "password",
            "STORE" => true,
        ),
        array(
            // A text field named 'email'. This one is not stored (it is presumed that
            // the admin will remember their email address).
            // {email} is a special tag -- Installatron will replace it with the user's
            // email address.
            // LABEL and TEXT are handled differently here, just to show another approach.
            // These both use locale keys that are specific to this installer. Their
            // values will be in the locale_en.php file.
            "ID" => "email",
            "LABEL" => "_installer_superduper_input_email_label",
            "TEXT" => "_installer_superduper_input_email_text",
            "TYPE" => "text",
            "VALUE" => "{email}",
        )
    ));
}

// The _process half of a step "does stuff after the page is submitted".

public function step1_process()
{
    // Step 1 _process can be used to error check values collected in step 1 _init.
    // Here we are just checking that email and passwd are more than 2 characters each,
    // though we could do any sort of error checking that we wanted.
    if ( !isset($this->input["field_email"]) || !isset($this->input["field_email"][1]) )
    {
        // If an error is discovered, this line can be used to return the user back to
        // step1_init, with an error message. In this case, the error message is an
        // official locale key, but it could be any text or a locale key of this installer.
        $this->addError("_errors_tooshort", "field_email");
    }

    // passwd: check that length is at least 2 characters:
    if ( !isset($this->input["field_passwd"]) || !isset($this->input["field_passwd"][1]) )
    {
        $this->addError("_errors_tooshort", "field_passwd");
    }

}

//==========================================================================
// STEP II: ARCHIVE EXTRACTION
//==========================================================================

// Step 2 is usually used to extract the 'main' archive. Each step is run as a
// separate process, so by splitting up long tasks we limit the risk of
// going over the maximum process time allowed by the server. If the archive
// is small, this could be merged with step 3.

public function step2_init()
{
    // Another setStepLabel and another locale key. This one says "EXTRACTING".
    $this->setStepLabel("_step_progress_extracting");

    // Installatron will automatically create the rest of this page, so nothing
    // more is required here.
}

public function step2_process()
{
    // Here we find our first real process command. This one will extract
    // an archive with the registered id of 'main'. This will be extracted into
    // the install directory (that is, the directory selected by the user on
    // step 1.
    $this->extract("main");
}

//==========================================================================
// STEP III: CONFIGURING INSTALL
//==========================================================================

// Step 3 in this example is both the last step, and the main processing step.
// The contents of the archive have been extracted into the install directory,
// and it is now the task of step 3 to do whatever needs to be done to complete
// the install.

public function step3_init()
{
    // This one, if you haven't guessed, adds "PROCESSING" under the progress bar.
    $this->setStepLabel("_step_progress_processing");
}

public function step3_process()
{
    // The archive, extracted in step 2, contains a top-level directory named
    // 'superduper-3.1.0/' and the rest of its files are in there. So we want to move
    // the contents of that directory back into the install directory:
    $this->mv('superduper-3.1.0/*','.');

    // Now we need to CHMOD a file:
    $this->chmod('config.php',0666);
    // ..and a couple of directories:
    $this->chmod(array('uploads','images'),0777);

    // Next we're using to use SR (REGEX Search/Replace) to edit the config.php file.
    $this->sr("config.php",array(
        // This first set are adding all the database-related values.
        "#DB_HOST = '.*?'#" => "DB_HOST = ".var_export($this->db_host,true),
        "#DB_NAME = '.*?'#" => "DB_NAME = ".var_export($this->db_name,true),
        "#DB_USER = '.*?'#" => "DB_USER = ".var_export($this->db_user,true),
        "#DB_PASS = '.*?'#" => "DB_PASS = ".var_export($this->db_pass,true),
        "#DB_PREF = '.*?'#" => "DB_PREF = ".var_export($this->db_prefix,true),
        // And now the install path and install URL:
        "#SCRIPT_PATH = '.*?'#" => "SCRIPT_PATH = ".var_export($this->path,true),
        "#SCRIPT_URL = '.*?'#"  => "SCRIPT_URL = ".var_export($this->url,true)
    ));

    // Super Duper, our example script, uses a MySQL database, so we now need to set up the
    // database with tables and values. Scripts generally use one of two methods to do this,
    // and while you would usually only use one method in an installer, I'll show them
    // both for this example:

    // DATABASE POPULATION METHOD A: .sql files

    // If .sql files are provided, you can often use them to popular the database with the
    // required tables and data:

    // A note about prefixes: they come in several flavors. Some scripts like the _ to be part
    // of the prefix, like "myprefix_" and some prefer the prefix without ("myprefix").
    // And not all scripts support the editing of prefixes.
    // In our example, Super Duper does support custom prefixes, and it has the _ as part of
    // the prefix. With that in mind (and the Version Info requirements correctly set) we'll
    // use SR to add the Installatron-generated prefix to this file:
    $this->sr("install/db/mysql.sql", "#sd_#", $this->db_prefix);

    // Next we import the .sql file, to create and/or populate the database:
    $this->db_import('install/db/mysql.sql');

    // And finally, modify the database using the Custom Input values collected in step 1.
    $this->db_query("UPDATE {$this->db_prefix}usertable SET username='{$this->input['field_uname']}', user_password='".md5($this->input['field_passwd'])."' WHERE user_id='1'");
    // (We didn't end up using the email field, so we can remove it from step 1.)

    // DATABASE POPULATION METHOD B: external install script

    // Some scripts provide an install script that can be executed without user interaction.
    // These are great. Instead of fiddling around with .sql files we can do everything that is
    // required simply by calling their install script. In this example, the step=2 bypasses
    // page that wanted the user to click a button. Since there are no visuals when using fetch,
    // we have to bypass it.
    $this->fetch('install/index.php?step=2');

    // And finally, to complete the install:
    $this->chmod('config.php',0644);
    $this->rm('install');
}

Note: The External Task feature has been DEPRECATED as of Installatron 6.1. We recommend using one of the above methods instead.

For the second example we'll stick with the same imaginary script called Super Duper, version 3.1.0. The installer id is "superduper".

And as before, we have already downloaded the archive and read the install documentation, so the task is to recreate those install steps in install.php. Let's get to it:

//==========================================================================
// STEP I: SETTINGS
//==========================================================================

// Step 1 is, as always, the settings page. Custom Inputs are not usually used when
// installing by the "External Task" method, so step 1 is sparse:
// method .

public function step1_init()
{
    // Hopefully you know from example 1 what this does.
    $this->setStepLabel("_step_progress_settings");
}

public function step1_process()
{
    // nothing to see here
}

//==========================================================================
// STEP II: ARCHIVE EXTRACTION
//==========================================================================

// Step 2, as in example 1, is an extraction of the 'main' archive.

public function step2_init()
{
    $this->setStepLabel("_step_progress_extracting");
}

public function step2_process()
{
    $this->extract("main");
}

//==========================================================================
// STEP III: CONFIGURING INSTALL
//==========================================================================

// Step 3 is going to be the first of two processing steps. This first one is
// used to get everything ready for the External Task.

public function step3_init()
{
    $this->setStepLabel("_step_progress_processing");
}

public function step3_process()
{
    // As in example 1, the contents of this top-level archive directory is moved
    // back into the install directory.
    $this->mv('superduper-3.1.0/*','.');

    // We CHMOD a file and some directories. The 'TRUE', added in this example, will
    // CHMOD the directories recursively.
    $this->chmod('config.php',0666);
    $this->chmod(array('uploads','images'), 0777, TRUE);

    // Next we're using to use SR (REGEX Search/Replace) to add the database values
    // to the external install script. We don't have to do this -- we can leave it up
    // to the user to copy and paste the values from Installatron when asked -- but
    // it's generally ideal to pre-set these values so the user doesn't need to worry
    // about them.
    // If you look carefully at the REGEXs, they are adding a value='' item to various
    // inputs in the script, and makes them readonly so that the user can't
    // accidentally change them from the values that Installatron needs.
    $this->sr("install/install.php",  "#(name='DB_HOST')#",  "$1 value='{$this->db_host}' readonly");
    $this->sr("install/install.php",  "#(name='DB_NAME')#",  "$1 value='{$this->db_name}' readonly");
    $this->sr("install/install.php",  "#(name='DB_USER')#",  "$1 value='{$this->db_user}' readonly");
    $this->sr("install/install.php",  "#(name='DB_PASS')#",  "$1 value='{$this->db_pass}' readonly");
    $this->sr("install/install.php",  "#(name='DB_PREF')#",  "$1 value='{$this->db_prefix}' readonly");
    // Same with the path and URL:
    $this->sr("install/install.php",  "#(name='SCRIPT_PATH')#",  "$1 value='{$this->path}' readonly");
    $this->sr("install/install.php",  "#(name='SCRIPT_URL')#",   "$1 value='{$this->url}' readonly");

    // The final task of step 3 is to get the External Task ready.
    // We're going use to SR to add an "The External Task is Complete" message to
    // the install script. Without adding this message the user will not known when
    // to continue with the Installatron install process.
    // You need to be careful to match the quotes when doing this step.
    $this->sr("install/install.php",  "#Super Duper is now.*?to continue.#"  ,"".(itron::$locale['_inprogress_externaltask_complete'])."");
}

//==========================================================================
// OPTIONAL STEP: EXTERNAL COFIGURATION
//==========================================================================

// Step 4 is our External Task. An external task loads the external install script into
// a window in Installatron and asks the user to complete this task before continuing.
// This isn't an ideal way to auto-install a script, however it is usually a lot easier
// to set up and maintain, and there are some scripts that can't be installed any other
// way.

public function step4_init()
{
    // This one will say "EXTERNAL TASK".
    $this->setStepLabel("_step_progress_externaltask");

    // This is the command that adds an external task to a page. As you can see, this
    // one is loading in the install script that we editted in step 3.
    $this->setExternalConfig("install/install.php");
}

public function step4_process()
{
    // This _process could be used to check that the user completed the external task.
}

//==========================================================================
// OPTIONAL STEP: FINALIZE
//==========================================================================

// Step 5 is the final processing step. The tasks performed here couldn't be done in
// step 3 because the external task required things a certain way. Now that the
// task is complete we can finalize the install.

public function step5_init()
{
    $this->setStepLabel("_step_progress_processing");
}

public function step5_process()
{
    // Set config.php back to something secure.
    $this->chmod('config.php', 0644);
    // And remove the install/ directory.
    $this->rm('install');

    // Congratulations, you not only installed Super Duper using an external task,
    // you also made it all the way through two whole examples.
}