This page lists the variables and commands that can be used in an installer, and some how-to explanations. See the SDK: An Overview page for a closer look at the installer format.

Installer/Upgrader Variables

• Custom Inputs
• Database: Host
• Database: Name
• Database: Username
• Database: Password
• Database: Table Prefix
• Install Location: Path
• Install Location: URL
• Locale
• Path: ImageMagick
• Path: NetPBM
• Path: Perl
• Time

Installer/Upgrader Commands

• CHMOD
• CHOWN
• Copy
• Delete
• Edit File
• External Task
• Extra Inputs
• Extract Archive
• Fetch (execute an external script)
• Copy
• Make Directory
• Make File
• Move
• MySQL Escape Value
• MySQL Import
• MySQL Query
• Remove
• Search/Replace
• Step Label

How-To

• How do I set up Custom Inputs?
• How do I set up an External Task?

The value of a custom input. Custom inputs appear on the "settings" step of the install process, and are added using the $this->setInputFields command.

$this->input['field_fieldid']

// examples
$this->sr("config.php", "#username#", $this->input['field_uname']);
$this->sr("config.php", "#password#", md5($this->input['field_passwd']));
$this->sr("config.php", "#your@email.com#", addslashes($this->input['field_email']));

The hostname of the MySQL server.

$this->db_host

// example
$this->sr("config.php", "#localhost#", $this->db_host);

The user of the MySQL database used by this install. This requires that the "database" installer requirement is enabled.

$this->db_user

// example
$this->sr("config.php", "#database_user#", $this->db_user);

The username of the MySQL database used by this install. This requires that the "database" installer requirement is enabled.

$this->db_name

// example
$this->sr("config.php", "#database_username#", $this->db_name);

The password of the MySQL database used by this install. This requires that the "database" installer requirement is enabled.

$this->db_pass

// example
$this->sr("config.php", "#database_password#", $this->db_pass);

The prefix of the MySQL database table(s) used by this install. This requires that the "database" installer requirement is enabled.

$this->db_pass

// example
$this->sr("config.php", "#table_prefix#", $this->db_prefix);

The location of the install as a server path.

$this->path

// example
$this->sr("config.php", "#install_path#", $this->path);

The location of the install as a URL (webpage location).

$this->url

// example
$this->sr("config.php", "#install_url#", $this->url);

Any Installatron locale text can be accessed using:

itron::$locale("locale_key");

// example
itron::$locale("_inprogress_externaltask_complete")

The path to ImageMagick graphics binaries on the server, if set in administration.

$this->path_imagemagick

The path to NetPBM graphics binaries on the server, if set in administration.

$this->path_netpbm

The path to Perl on the server, if set in administration.

$this->path_perl

The current server time, as a UNIX time stamp.

$this->systime

Set Unix permissions for files or directories.

$this->chmod("file_or_directory", chmod_value [, diff_chmod_value_for_dirs = chmod_value [, recursive = false ]] );

// examples
$this->chmod("config.php", 0666);
$this->chmod("temp/uploads", 0777);
$this->chmod("data", 0777, NULL, TRUE);
$this->chmod(array("config.php","data/level.inc"), 0644);

Set Unix owner and group for files or directories.

$this->chown("file_or_directory", user, group, recursive );

// examples
$this->chown("config.php", "bob");
$this->chown("config.php", "bob", "apache");
$this->chown("temp/uploads", "bob", null, TRUE);
$this->chown(array("uploads","temp"), "apache", null, TRUE);

Copy files or directories.

$this->cp("source", "destination");

// examples
$this->cp("config-dist.php", "config.php");
$this->cp("inc/config.php", "admin/data.php");

Add custom inputs to a "settings" step. This is usually added to step 1 to collect things like a password and email address which are then used to configure the install.

NOTE: The setInputFields command goes in the _init part of a step, not the _process part.

$this->setInputFields(array(
    array(
        "ID" => "inputid",
        "LABEL" => "_installer_installerid_input_inputid_label",
        "TEXT" => "_installer_installerid_input_inputid_text",
        "TYPE" => "input_type",
        "VALUE" => "default_value",
		"OPTIONS" => array( "one", "two", "three" ),
        "STORE" => true,
        "READONLY" => true,
    ),
));

The ID (required)is used to identify the input, and can be referred to later in the installer using $this->input['field_inputid'].
The LABEL (required) and TEXT (optional) point to locale entries, and installerid should be the id of your installer.
The TYPE (required) can be one of: text, check, password, select.
The VALUE (optional) can be a default value for the field.
The OPTIONS (optional) is the equivalent of VALUE for select fields. The array holds the values.
STORE (optional), when set TRUE, tells Installatron to store the value and show it with the installs Notes.
READONLY (optional), when set TRUE, creates an input value that cannot be edited.

More on custom inputs can be found below.

Load an external script and have the user complete that "external task" before continuing with the install or upgrade. This is similar to fetch except that the external script is interactive. It is preferable to not use external tasks, but some install/upgrade processes are so complex that it can be difficult to reproduce the steps insider the installer, so that is when an external task step is used.

NOTE: The setExternalConfig command goes in the _init part of a step, not the _process part.

$this->setExternalConfig("path_and_file");

// examples
$this->setExternalConfig("install/install.php");
$this->setExternalConfig("setup.php?step=2&key=$key");

Extract an archive. The archive must be registered in the version's init.xml file.

$this->extract("archive_id", "destination");

// examples
$this->extract("main", ".");
$this->extract("xtra1", "upgradetempdir");
$this->extract("chineselang", "plugins/locale");

Execute an external script over HTTP, usually to run an install or upgrade script. This is like loading the page in a web browser, however there is no visual output, and no interaction.

$result = $this->fetch("path_and_scriptname");

// examples
$this->fetch("install/install.php");
$this->fetch("upgrade.php?step=2&language=en");// a GET request
$this->fetch("upgrade.php",array( "step" => "2", "language" => "en" ));// a POST request

Create a directory.

$this->mkdir("path_and_dirname");

// examples
$this->mkdir("temp");
$this->mkdir("temp/upload");

Create a file.

$this->write("path_and_filename", "contents");

// examples
$this->write("config.php", "This is a config file.");
$this->write("inc/config.php", $myContents);

Move files or directories.

$this->mv("source", "destination");

// examples
$this->mv("config-dist.php", "config.php");
$this->mv("inc/config.php", "admin/data.php");

// move contents to the "install directory" examples
$this->mv("script-1.5.2/*");
$this->mv("script-1.5.2/upload/*");

Escape a value before using it with database commands, to remove the possibility of SQL injections.

$this->db_escape("text");

// example
$escaped_websitename = $this->db_escape($this->field['field_sitename']);

Import/execute a .sql script. This requires that the "database" installer requirement is enabled.

$this->db_import("path_and_file");

// examples
$this->db_import("mysql.sql");
$this->db_import("install/db/populate.sql");
$this->db_import("upgrade/45_to_46.sql");

Execute a MySQL query. This requires that the "database" installer requirement is enabled.

$this->db_query("mysql_query");

// examples
$this->db_query("UPDATE users SET username='admin' WHERE userid='0'");
$this->db_query("INSERT INTO {$this->db_prefix}_config (name, age) VALUES('Bob', '20' ) ");

Remove (delete) files or directories.

$this->rm("path_and_target");

// examples
$this->rm("install");
$this->rm("*.php");
$this->rm("temp/*");
$this->rm(array("one.php","temp/two","admin/advanced/*.inc"));

Edit a file using PHP PREG search and replace.

$this->sr("path_and_file", "#regex_search#", "replace_value");
$this->sr("path_and_file", array( "#regex_search#" => "replace_value" ));

// examples
$this->sr("config.php", "#false#", "true");
$this->sr("config.php", "#\$installed\s+=\s+'0'#", "$installed = '1'");
$this->sr("config.php", "#(\$installed\s+=\s+')0'#", "{$1}0'");
$this->sr("data.php", "#(// SET THESE VALUES)#", "$newContent\n\n$1");

// database values examples
$this->sr("config.php", array(
	'#(\$hostname\s+=\s+)\'.*?\'#'      => "$1".var_export($this->db_host,true),
	'#(\$database_name\s+=\s+)\'.*?\'#' => "$1".var_export($this->db_name,true),
	'#(\$database_username\s+=\s+)\'.*?\'#' => "$1".var_export($this->db_user,true),
	'#(\$database_password\s+=\s+)\'.*?\'#' => "$1".var_export($this->db_pass,true),
	'#(\$table_prefix\s+=\s+)\'.*?\'#' => "$1".var_export($this->db_prefix,true)
));

// custom input fields examples
$this->sr("install/mysql.sql", "#administrator#", "");
$this->sr("install/mysql.sql", "#548dfjfsd998dfs9kd#", md5($this->input['field_password']));
$this->sr("install/mysql.sql", "#your@email.com#", addslashes($this->input['field_email']));

The step label is the text that appears under the progress bar during an install or upgrade, to describe what it happening on that step. Each step _init should begin with a step label command.

$this->setStepLabel("step_description");

// examples
$this->setStepLabel("CURRENTLY DOING STUFF");
$this->setStepLabel("_installer_installerid_progress_doingstuff");

// examples using global locale presets (** should use these if possible**):
$this->setStepLabel("_step_progress_settings");
$this->setStepLabel("_step_progress_extracting");
$this->setStepLabel("_step_progress_processing");
$this->setStepLabel("_step_progress_externaltask");

Custom Inputs are an optional feature added to step 1 to collect additional information -- such as a password or an email address -- which are then used to configure the install.

Here is an example:

public function step1_init()
{
    $this->setStepLabel("_step_progress_settings");
    $this->setInputFields(array(
        array(
            "ID" => "uname",
            "LABEL" => "_info_adminusername",
            "TEXT" => "_settings_adminusername",
            "TYPE" => "text",
            "VALUE" => "admin",
            "STORE" => true,
            "READONLY" => true,
        ),
        array(
            "ID" => "passwd",
            "LABEL" => "_info_adminpassword",
            "TEXT" => "_settings_adminpassword",
            "TYPE" => "password",
            "STORE" => true,
        ),
    ));
}

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

From that example you can see that step1_init adds two custom fields: username and password. username is a text field with a value of "admin" and is read-only. password is a password field. Both will be remembered by Installatron.

Then step1_process is used to error-check the password value. If an error is found, it will return the user to step1_init with an error message (in this case, a locale key) and the password field highlighted in red.

External Tasks are an optional feature that can be used to load an external install or upgrade script into a window in Installatron, and ask the user to complete the tasks of that external script before continuing with the install/upgrade in Installatron. An external task is given an entire install or upgrade step, plus you will usually add an extra SR to the _process before the external task.

Here is an example:

.
.
.
public function step3_process()
{
    .
    .
    .
    $this->sr("install.php", "#Congratulations, you.*?to continue.#", itron::$locale['_inprogress_externaltask_complete']);
}

public function step4_init()
{
    $this->setStepLabel("_step_progress_externaltask");
    $this->setExternalConfig("install.php");
}

public function step4_process()
{
    // _process is not ususally used on an external task step
}

From that example you can see that a "step4" has been added for the external task, and the $this->setExternalConfig(); command has been added to the _init, not the _porocess. An SR was also added to the step3_process, to insert the "You have completed the external task..." message into an appropriate place in the external task script.