Miscellaneous

Quickstart Guide

The quickest way to create an Installatron installer, or at least the template for one, is to log into the Installatron Installer Editor (everyone who has an installatron.com account, which you will have if you ever purchased Installatron licenses, can log into the Editor) and use the right-sidebar to create a new installer.

The form asks you for some information about the script and then you press the [Create] button to build it.

All of the values can be easily changed later except for Script Name. If you want to experiment then use a Script Name of "test" and give it some dummy values.

The rest of this document describes what you'll find in an Installatron installer or what you'll need to create if you're making one manually.

Installer Structure

An Installatron application package is comprised of several files and directories, placed inside Installatron's "installers" directory:

/var/installatron/installers/installerid/
init.xml // information about the installer and the application
locale_en.php // the default (english) locale file
button.png // a 88x31 button image for the app
logo.png // up to 400x150 logo image for the app
icon.png // 175x175 icon image for the app
icon64.png // 64x64 icon image for the app (resized icon.png)
[ss1.png] // 1024x640 screenshot of the app
[ss2.png] // 1024x640 screenshot of the appversion1/ // a version sub-directory
[LICENSE] // license agreement for this version (optional)
init.xml // information for this version (including PHP7 install code)
[version2/ // another version sub-directory (optional)
[LICENSE]
init.xml] // information for this version (including PHP7 install and upgrade code)

/var/installatron/installers/installerid/
init.xml // information about the installer and the application
locale_en.php // the default (english) locale file
button.png // a 88x31 button image for the app
logo.png // up to 400x150 logo image for the app
icon.png // 175x175 icon image for the app
icon64.png // 64x64 icon image for the app (resized icon.png)
[ss1.png] // 1024x640 screenshot of the app
[ss2.png] // 1024x640 screenshot of the appversion1/ // a version sub-directory
[LICENSE] // license agreement for this version (optional)
init.xml // information for this version
install.php // PHP5 install code for this version
[version2/ // another version sub-directory (optional)
[LICENSE]
init.xml // information for this version
install.php // PHP5 install code for this version
[upgrade.php]] // PHP5 upgrade code for upgrading to this version (optional)

A Note About PHP7 Verses PHP5

The introduction of PHP7 by the The PHP Development Team in 2015 necessitated changes in the way that Installatron installers worked. Specifically, whereas for PHP5 the install and upgrade code for each version of each installer was supplied in separate files for each task (see the package layout diagram above), for PHP7 it was necessary to move the install/upgrade code into the init.xml file.

To maintain backwards compatibility, Installatron now supports both formats; external install.php/upgrade.php files for when Installatron's core is running on PHP5 and internal init.xml elements for when the Installatron core is running on any version of PHP7.

The code used by both formats is very similar and is easy to translate between one format and the other.

Note that the Installatron installer Editor tool lets you edit installers in v2.0 format while it automatically builds the additional v1.0 / PHP5-only files each time you save.

If you're creating an installer by hand then unless you know that the installer will be used on PHP5 servers we recommend ignoring the v1.0 installer format and PHP5 compatibility altogether.

Creating an application package

The easiest way to create an Installatron application package is to use the Installer Maker/Editor tool. This tool creates a basic template and has a GUI for editing most of the commonly used features.

The Version init.xml

todo...

The version-level init.xml file contains information specific to this version of the application. Here is the format:

<?xml version='2.0'?><installer><information><!-- the main information about this version of the app --></information><changelog[ url="{URL_TO_RELEASE_NOTES}"]><![CDATA[
<!-- highlights, bug fixes, and security information about this version of the app -->
]]>
</changelog><links><!-- some links associated with this version of the app --></links><requirements><!-- a list of server and account requirements for this version of the app --></requirements><archives><!-- a list of archives used to install and upgrade this version of the app --></archives><skeleton><!-- a list of this version of the app's top-level files and directories, and its main config file --><!-- a list of this version of the app's database tables (without table prefix) --></skeleton><fields><!-- definitions for getting and setting fields like the administrative user's password and email address, and the app's version --></fields><languages><!-- a list of languages supported by this version of the app --></languages><install><!-- the code to install this version of the app (when Installatron is running on PHP7+) --></install><upgrade><!-- the code to upgrade to this version of the app (when Installatron is running on PHP7+) --></upgrade></installer>

<?xml version='1.0'?><installer><information><!-- the main information about this version of the app --></information><changelog[ url="{URL_TO_RELEASE_NOTES}"]><![CDATA[
<!-- highlights, bug fixes, and security information about this version of the app -->
]]>
</changelog><links><!-- some links associated with this version of the app --></links><requirements><!-- a list of server and account requirements for this version of the app --></requirements><archives><!-- a list of archives used to install and upgrade this version of the app --></archives><skeleton><!-- a list of this version of the app's top-level files and directories, and its main config file --><!-- a list of this version of the app's database tables (without table prefix) --></skeleton><fields><!-- definitions for getting and setting fields like the administrative user's password and email address, and the app's version --></fields><languages><!-- a list of languages supported by this version of the app --></languages></installer>

<?xml version='2.0'?><installer><information><infoid="version"value="1.2.3"/><infoid="license"value="_apps_opensource"/><infoid="default-dir"value="default_directory_name"/><infoid="date"value="YYYY-MM-DD"/></information><changelogurl="https://myapplication.org/news/2019/myapplication-5-1-1-release/"><![CDATA[
This maintenance release fixes 33 bugs, including improvements to the block editor, accessibility, and internationalization.
Highlights
* Site Health Check: Building on the Site Health features introduced in 5.1, this release adds two new pages to help debug common configuration issues. It also adds space where developers can include debugging information for site maintainers.
* PHP Error Protection: This administrator-focused update will let you safely fix or manage fatal errors without requiring developer time. It features better handling of the so-called “white screen of death,” and a way to enter recovery mode, which pauses error-causing plugins or themes.
]]></changelog><links><linkid="admin"value="wp-admin/index.php"/><linkid="edit-1"value="wp-config.php"/><linkid="edit-2"value="other_editable_files.php"/></links><requirementstype='2.0'><requirementid="itron"value="5.0.0"/><requirementid="diskspace"value="18"/><requirementid="php"value="5.2.4-"/><requirementid="mysql"value="5-"/><requirementid="mysql-table-prefix"value="ma_"/><requirementid="php-date-timezone"value="1"/><requirementid="php-bcmath"value="1"/></requirements><requirements><requirementid="itron-version"value="5.0.0"/><requirementid="diskspace"value="18"/><requirementid="database"value="1"/><requirementid="db-prefix-support"value="1"/><requirementid="db-prefix-underscore"value="1"/><requirementid="php-version-minimum"value="5.2.4"/><requirementid="php-version-minimum"value=""/><requirementid="perl-version-minimum"value=""/><requirementid="perl-version-maximum"value=""/><requirementid="mysql-version-minimum"value="5"/><requirementid="mysql-version-maximum"value=""/><requirementid="php-pdo-mysql-minimum"value="1.0"/><requirementid="php-register-globals"value="0"/><requirementid="php-safe-mode"value="0"/></requirements><archives><archiveid="main"url="url_to_main_archive"type="archive_type"md5="md5_value" /><archiveid="xtra1"url="url_to_extra_archive_1"type="archive_type"md5="md5_value" /><archiveid="xtra2"url="url_to_extra_archive_2"type="archive_type"md5="md5_value" /></archives><skeleton><fileid="wp-admin"/><fileid="wp-content"/><fileid="wp-includes"/><fileid="wp-config.php"isconfig="true"/><fileid="wp-activate.php"/><fileid="wp-app.php"/><fileid="wp-blog-header.php"/><fileid="wp-comments-post.php"/><fileid="wp-cron.php"/><fileid="wp-links-opml.php"/><fileid="wp-load.php"/><fileid="wp-login.php"/><fileid="wp-mail.php"/><fileid="wp-pass.php"/><fileid="wp-register.php"/><fileid="wp-settings.php"/><fileid="wp-signup.php"/><fileid="wp-trackback.php"/><fileid="xmlrpc.php"/><tableid="commentmeta"/><tableid="comments"/><tableid="links"/><tableid="options"/><tableid="postmeta"/><tableid="posts"/><tableid="term_relationships"/><tableid="term_taxonomy"/><tableid="terms"/><tableid="usermeta"/><tableid="users"/></skeleton><fields><fieldid="version"><get><?php return $this->read("wp-includes/version.php", "/wp_version = (['\"])(.+?);/", 2);?></get></field><fieldid="language"><get><?php return $this->db_query("SELECT setting_value FROM {$this->db_prefix}settings WHERE setting_key='locale'", null, "setting_value");?></get><set><?php $this->db_query("UPDATE {$this->db_prefix}settings SET setting_value=? WHERE setting_key='locale'", array($this->input["field_language_value"]));?></set></field><fieldid="login"><get><?php return $this->db_query("SELECT user_login FROM {$this->db_prefix}users WHERE ID=?", array("1"), "user_login");?></get><set><?php $this->db_query("UPDATE {$this->db_prefix}users SET user_login=? WHERE ID=?", array($this->input["field_login"], "1"));?></set></field><fieldid="passwd"><set><?php $this->db_query("UPDATE {$this->db_prefix}users SET user_password=? WHERE ID=?", array(md5($this->input["field_passwd"]), "1"));?></set></field></fields><languages><languageid="en"value="en-US"/><languageid="en_uk"value="en-GB"/><languageid="fr"value="fr-FR"/><languageid="nl"value="nl-NL"/><languageid="pt"value="pt-PT"/><languageid="pt_br"value="pt-BR"/></languages><install><!-- todo... --></install><upgrade><!-- todo... --></upgrade></installer>

<?xml version='2.0'?><installer><information><infoid="version"value="1.2.3"/><infoid="license"value="_apps_opensource"/><infoid="default-dir"value="default_directory_name"/><infoid="date"value="YYYY-MM-DD"/></information><changelogurl="https://myapplication.org/news/2019/myapplication-5-1-1-release/"><![CDATA[
This maintenance release fixes 33 bugs, including improvements to the block editor, accessibility, and internationalization.
Highlights
* Site Health Check: Building on the Site Health features introduced in 5.1, this release adds two new pages to help debug common configuration issues. It also adds space where developers can include debugging information for site maintainers.
* PHP Error Protection: This administrator-focused update will let you safely fix or manage fatal errors without requiring developer time. It features better handling of the so-called “white screen of death,” and a way to enter recovery mode, which pauses error-causing plugins or themes.
]]></changelog><links><linkid="admin"value="wp-admin/index.php"/><linkid="edit-1"value="wp-config.php"/><linkid="edit-2"value="other_editable_files.php"/></links><requirementstype='2.0'><requirementid="itron"value="5.0.0"/><requirementid="diskspace"value="18"/><requirementid="php"value="5.2.4-"/><requirementid="mysql"value="5-"/><requirementid="mysql-table-prefix"value="ma_"/><requirementid="php-date-timezone"value="1"/><requirementid="php-bcmath"value="1"/></requirements><requirements><requirementid="itron-version"value="5.0.0"/><requirementid="diskspace"value="18"/><requirementid="database"value="1"/><requirementid="db-prefix-support"value="1"/><requirementid="db-prefix-underscore"value="1"/><requirementid="php-version-minimum"value="5.2.4"/><requirementid="php-version-minimum"value=""/><requirementid="perl-version-minimum"value=""/><requirementid="perl-version-maximum"value=""/><requirementid="mysql-version-minimum"value="5"/><requirementid="mysql-version-maximum"value=""/><requirementid="php-pdo-mysql-minimum"value="1.0"/><requirementid="php-register-globals"value="0"/><requirementid="php-safe-mode"value="0"/></requirements><archives><archiveid="main"url="url_to_main_archive"type="archive_type"md5="md5_value" /><archiveid="xtra1"url="url_to_extra_archive_1"type="archive_type"md5="md5_value" /><archiveid="xtra2"url="url_to_extra_archive_2"type="archive_type"md5="md5_value" /></archives><skeleton><fileid="wp-admin"/><fileid="wp-content"/><fileid="wp-includes"/><fileid="wp-config.php"isconfig="true"/><fileid="wp-activate.php"/><fileid="wp-app.php"/><fileid="wp-blog-header.php"/><fileid="wp-comments-post.php"/><fileid="wp-cron.php"/><fileid="wp-links-opml.php"/><fileid="wp-load.php"/><fileid="wp-login.php"/><fileid="wp-mail.php"/><fileid="wp-pass.php"/><fileid="wp-register.php"/><fileid="wp-settings.php"/><fileid="wp-signup.php"/><fileid="wp-trackback.php"/><fileid="xmlrpc.php"/><tableid="commentmeta"/><tableid="comments"/><tableid="links"/><tableid="options"/><tableid="postmeta"/><tableid="posts"/><tableid="term_relationships"/><tableid="term_taxonomy"/><tableid="terms"/><tableid="usermeta"/><tableid="users"/></skeleton><fields><fieldid="version"><get><?php return $this->read("wp-includes/version.php", "/wp_version = (['\"])(.+?);/", 2);?></get></field><fieldid="language"><get><?php return $this->db_query("SELECT setting_value FROM {$this->db_prefix}settings WHERE setting_key='locale'", null, "setting_value");?></get><set><?php $this->db_query("UPDATE {$this->db_prefix}settings SET setting_value=? WHERE setting_key='locale'", array($this->input["field_language_value"]));?></set></field><fieldid="login"><get><?php return $this->db_query("SELECT user_login FROM {$this->db_prefix}users WHERE ID=?", array("1"), "user_login");?></get><set><?php $this->db_query("UPDATE {$this->db_prefix}users SET user_login=? WHERE ID=?", array($this->input["field_login"], "1"));?></set></field><fieldid="passwd"><set><?php $this->db_query("UPDATE {$this->db_prefix}users SET user_password=? WHERE ID=?", array(md5($this->input["field_passwd"]), "1"));?></set></field></fields><languages><languageid="en"value="en-US"/><languageid="en_uk"value="en-GB"/><languageid="fr"value="fr-FR"/><languageid="nl"value="nl-NL"/><languageid="pt"value="pt-PT"/><languageid="pt_br"value="pt-BR"/></languages></installer>

What follows is a closer look at each element of the version init.xml:

<changelog>

Changes from the previous version of this application (as supported by Installatron) to this version of the application.

These notes are provided to the user prior to updating an application.

[<changelog[ url="{URL_TO_RELEASE_NOTES}"]><![CDATA[
<!-- highlights, bug fixes, and security information about this version of the app -->
]]>
</changelog>]

<changelogurl="http://www.myapp.com/releases/5.1.1/releasenotes"><![CDATA[
This maintenance release fixes 33 bugs, including improvements to the block editor, accessibility, and internationalization.
Highlights
* Site Health Check: Building on the Site Health features introduced in 5.1, this release adds two new pages to help debug common configuration issues. It also adds space where developers can include debugging information for site maintainers.
* PHP Error Protection: This administrator-focused update will let you safely fix or manage fatal errors without requiring developer time. It features better handling of the so-called “white screen of death,” and a way to enter recovery mode, which pauses error-causing plugins or themes.
]]></changelog>

An asterisk ('*') at the beginning of the line will automatically be converted into a bullet-point ('•').

Installatron conventions: while this changelog entry can be anything you like, Installatron roughly follows the following conventions;

It might begin with a brief summary.

If this is a security release then the 1st section is "Security".

Other sections, typically in this order, can be "WARNINGS", "Highlights", "Bug Fixes", "Languages". But we're not super strict about them; the goal is more to be readable than to follow a strict format.

We will often remove bug IDs and bug-reporting or bug-fixing credits for the same readibility concerns.

If this version has skipped over several releases of the application, all of the intervening release notes will be included here too, separated by their corresponding version numbers.

<links>

Some administration links associated with this version of the application.

All links are optional, and all are in the form of paths relative to the app's main install directory.

[<links><linkid="admin"value="{ADMIN_BACKEND_PATH}"/></links>]

<links><linkid="admin"value="wp-admin"/></links>

admin adds an [admin] button to the Installed Apps page and is a link to an "administration" page. config is the same except it is for a [config] button. edit-1, edit-2, etc are files that can be edited inside Installatron (for templates or config files that can't be edited through the application itself). todo...

<archives>

A list of archives associated with this version of the application.

Installatron will download these when they are first used and cache them in /var/installatron/archives/.

The first archive is always, by convention, the application's main archive, which is used to install and also often to upgrade the application too. You can list as many other archives as needed. Uses might include; optional demo content for install, a separate upgrade archive for upgrading, and locale archives.

<skeleton>

A list of top-level directories, top-level files, and database tables that Installatron should, by default, associate with this version of the application.

Database tables should be listed without a table prefix.

The skeleton entries are not technically required but you absolutely should try to make these lists as accurate as possible because they affect these tasks: Import, Clone, Backup, Uninstall. So if you want any of those tasks to work you should pay attention to these lists.

Some flags are available to identify key files (and these need not be top level):

isconfig - identifies the file containing the main MySQL and other configuration values (this flag is important when performing Import, Clone, and or a Backup-Restore).

Remember; the files and directories listed here are only the top-level (ie. those in the install directory) items, and you only need to include items in sub-directories if they are flagged.

The order of these lists is not important although by convention the <file> list is usually before the <table> list.

Pro tip: a common question here regards plugins that might add extra files or tables; should you try to anticipate every possible file, directory, and table that might ever be part of this application and include it here? You could and that would be a solution, sure. But that's not how we handle the official installers.

Regarding files/directories; Installatron automatically watches for top-level- files and directories that are created during install/update tasks -- files that are not includes in the installer's skeleton list -- and adds them to the list of files that Installatron will track for the application.

If the user adds files to the main directory outside of install or update tasks then Installatron has no knowledge of those files/dirs and will not track them. This means they will not be included in any Backup, Clone, or Uninstall.

The app's owner can, however, edit the app (in Installatron), go to the 'Files & Tables' tab, and check the files that they want Installatron to start tracking.

Regarding tables; if a table-prefix is used by the application then Installatron will always automatically know which tables belong to the application, regardless when the tables were added. Installatron will just work with all tables beginning with that prefix.

If no table-prefix is used then Installatron falls back to using a combination of the skeleton table list plus it will automatically watch for extra tables added during install/update tasks and track them as well. If no prefix is used then for tables added outside of an Installatron activity, like if the user added a plugin to the app which added its own tables, Installatron will not know about those new tables and they will therefore not be included in any Backup, Clone, or Uninstall.

But as with files; the app's owner can edit the app in Installatron, go to the 'Files & Tables' tab, and check the extra tables that they want Installatron to start tracking.

The Installer

Applications are, ultimately, installed by installer code, the details of which are documented here.

While the installer code itself has not changed, the location of the installer code changed between versions 1.0 and 2.0 of the Installatron installer format; the version 1.0 format, used when the Installatron core is running on PHP 5, is found in a file named installerid/version/install.php while the version 2.0 format, used when the Installatron core is running on PHP 7+, is included directly in the version's installerid/version/init.xml file (inside <install>...</install> tags).

If you're using Installatron Installer Editor to edit your installer then it will automatically create the PHP5-compatible files, but if you're creating the installer by hand then unless you specifically know it will be used on PHP5 servers we recommend ignoring the v1.0/PHP5 installer files. They won't be needed.

<install>(v2.0 / PHP7+)installerid/version/install.php(v1.0 / PHP5)

When Installatron's core is running on PHP 7+ it will look for the install code, for this version of the application, in the version's init.xml file (inside a pair of <install>...</install> tags). If Installatron is running on PHP 5 then it will ignore this code (and look for the v1.0 install.php file instead).

This v2.0 formatting of the install code is very simple;

The code must be wrapped in <?php ... ?> PHP tags.

While it's not 100% necessary, if the first step in the install is to extract the app's archive(s) then then the next line should be this special comment:

When Installatron's core is running on PHP 5 it will look for the install code, for this version of the application, in the version's install.php file. If Installatron is running on PHP 7+ then it will ignore this code (and look for the v2.0-style install code inside init.xml instead).

The v1.0 install process is comprised of steps, and each step is comprised of an _init component (which configures the page for the step), and a _process component (which performs actions).

Step 1 is a legacy step and should be omitted.

Step 2 is usually used to extract the "main" archive (see the description of the version/init.xml file above for more about archives).

Step 3 is usually used as the main processing step. Here it sets permissions, moves and edits files, populates a database if the application uses one, and so on.

More steps can be added if you wish, but all of Installatron's official installers use steps 2 and 3 when installing on PHP 5.

{STRIPPEDVERSION} is the "version" with all non-alphanumeric characters replaced by underscores. For example, the strippedversion for '2.0 (p1)' would be: 2_0__p1_

When Installatron's core is running on PHP 7+ it will look for the install code, for this version of the application, in the version's init.xml file (inside a pair of <install>...</install> tags). If Installatron is running on PHP 5 then it will ignore this code (and look for the v1.0 install.php file instead).

This v2.0 formatting of the install code is very simple;

The code must be wrapped in <?php ... ?> PHP tags.

While it's not 100% necessary, if the first step in the install is to extract the app's archive(s) then then the next line should be this special comment:

When Installatron's core is running on PHP 5 it will look for the install code, for this version of the application, in the version's install.php file. If Installatron is running on PHP 7+ then it will ignore this code (and look for the v2.0-style install code inside init.xml instead).

The v1.0 install process is comprised of steps, and each step is comprised of an _init component (which configures the page for the step), and a _process component (which performs actions).

Step 1 is a legacy step and should be omitted.

Step 2 is usually used to extract the "main" archive (see the description of the version/init.xml file above for more about archives).

Step 3 is usually used as the main processing step. Here it sets permissions, moves and edits files, populates a database if the application uses one, and so on.

More steps can be added if you wish, but all of Installatron's official installers use steps 2 and 3 when installing on PHP 5.

The Upgrader

Applications are, ultimately, upgraded by upgrader code, the details of which are documented here.

While the upgrader code itself has not changed, the location of the upgrader code changed between versions 1.0 and 2.0 of the Installatron upgrader format; the version 1.0 format, used when the Installatron core is running on PHP 5, is found in a file named upgraderid/version/upgrade.php while the version 2.0 format, used when the Installatron core is running on PHP 7+, is included directly in the version's installerid/version/init.xml file (inside <upgrade>...</upgrade> tags).

<upgrade>(v2.0 / PHP7+)installerid/version/upgrade.php(v1.0 / PHP5)

When Installatron's core is running on PHP 7+ it will look for the upgrade code, for this version of the application, in the version's init.xml file (inside a pair of <upgrade>...</upgrade> tags). If Installatron is running on PHP 5 then it will ignore this code (and look for the v1.0 upgrade.php file instead).

This v2.0 formatting of the upgrade code is very simple;

The code must be wrapped in <?php ... ?> PHP tags.

The @INTERNAL legacy-step-point comment (as seen in the installer above) is not typically added to upgraders.

When Installatron's core is running on PHP 5 it will look for the upgrade code, for this version of the application, in the version's upgrade.php file. If Installatron is running on PHP 7+ then it will ignore this code (and look for the v2.0-style upgrade code inside init.xml instead).

The v1.0 upgrade process is comprised of steps, and each step is comprised of an _init component (which configures the page for the step), and a _process component (which performs actions).

Step 1 is typically used to extract the archives (note that, unlike the installer where step 1 is omitted, we do start with step 1 here in the upgrader).

Step 2 is usually used as the main processing step. Here the archives are extract, permissions set, files moved and files edited, databases populated (if the application uses one), and so on. Note that this is different to the approach used by v1.0 installers where archive extraction is in a separate step.

More steps can be added if you wish, but most of Installatron's official v1.0 use a single step to upgrade applications (with only a few using 2 steps).

{STRIPPEDVERSION} is the "version" with all non-alphanumeric characters replaced by underscores. For example, the strippedversion for '2.0 (p1)' would be: 2_0__p1_

When Installatron's core is running on PHP 7+ it will look for the upgrade code, for this version of the application, in the version's init.xml file (inside a pair of <upgrade>...</upgrade> tags). If Installatron is running on PHP 5 then it will ignore this code (and look for the v1.0 upgrade.php file instead).

This v2.0 formatting of the upgrade code is very simple;

The code must be wrapped in <?php ... ?> PHP tags.

The @INTERNAL legacy-step-point comment (as seen in the installer above) is not typically added to upgraders.

When Installatron's core is running on PHP 5 it will look for the upgrade code, for this version of the application, in the version's upgrade.php file. If Installatron is running on PHP 7+ then it will ignore this code (and look for the v2.0-style upgrade code inside init.xml instead).

The v1.0 upgrade process is comprised of steps, and each step is comprised of an _init component (which configures the page for the step), and a _process component (which performs actions).

Step 1 is typically used to extract the archives (note that, unlike the installer where step 1 is omitted, we do start with step 1 here in the upgrader).

Step 2 is usually used as the main processing step. Here the archives are extract, permissions set, files moved and files edited, databases populated (if the application uses one), and so on. Note that this is different to the approach used by v1.0 installers where archive extraction is in a separate step.

More steps can be added if you wish, but most of Installatron's official v1.0 use a single step to upgrade applications (with only a few using 2 steps).

A Fields Guide

Fields are one of the top-level definitions in the installerid/version/init.xml file and they are used to define how Installatron interacts with the application.

For example; if Installatron needs to know what version of an application is currently being used then it calls the code in <fields><field id="version"><get>. This code, for whatever application Installatron is interested in, is expected to be able to find the app's version.

Here is what fields look like in the version's init.xml file (the first field here, for version, is taken from our WordPress installer):

<fields><fieldid="version"><get><?php return $this->read("wp-includes/version.php", "/wp_version = (['\"])(.+?)\1;/", 2);?></get></field><!-- this is the template of an internal field --><field {ID}><get><?php return /* return the value for this field */ ?></get><set><?php /* code to set this field using the Installatron $this->input["field_{ID}"] value */ ?></set>
[<verify><?php /* code code to verify that the user has entered a valid value */ ?></verify>]
</field><!-- this is the template of a custom field --><field {ID} {TYPE} {DEFAULT_VALUE}><label>{LOCALE_TAG_1}</label>
[<options><optionvalue="yes">{LOCALE_TAG_2}</option><optionvalue="no">{LOCALE_TAG_3}</option></options>]
<get><?php return /* return the value for this field */ ?></get><set><?php /* code to set this field using the Installatron $this->input["field_{ID}"] value */ ?></set>
[<verify><?php /* code code to verify that the user has entered a valid value */ ?></verify>]
</field>
...
</fields>

(One of the great values of WordPress is that in the 15 years or more that Installatron has installed WordPress the method of finding the app's version has never changed. So that particular piece of code has never needed to change in our WordPress installer.)

Also note that there is no <set> for the version field because Installatron never sets an app's version, only ever reads it.

Any PHP code can be used between the <?php ... ?> tags, though we encourage you to use Installatron's internal variables and commands in order to maintain maximum compatibility and portability.

verify

Before looking at the different types of fields we'll quickly look at the optional<verify> element which is common to all fields that include a <set> element. This is used to validate any value entered by the user. Here's the format and an example:

<verify><?php /* code code to verify that the user has entered a valid value */ ?></verify>

Internal Fields

The version field, seen above, is an example of an internal field type which means that Installatron automatically recognises it and knows how and when to use it. You only need to add its definition to the <fields>...</fields> block in installerid/version/init.xml and Installatron will handle the rest.

All internal fields need only the {ID} parameter; you don't need to provide the {TYPE} and {DEFAULT_VALUE} parameters.

The following is a full list of internal fields that you can add to your installer. Simply add them to the <fields>...</fields> definition, edit the PHP code for each set and get to match your application, and Installatron takes care of the rest.

email

get & set

This gets and sets the application's administrative user's email address. The <get> should return the app's administrative user's current email address and the <set> should use Installatron's $this->input["field_email"] value to set a new email address (usually set somewhere in the app's database).

language

get & set

This gets and sets the application's language. This is the most difficult field to support, and we recommend leaving it until everything else is running smoothly.

First, you need to decide whether this is to get and set the application's language and/or the administrative user's language. Installatron itself is, admittedly, inconsistent on this question; we take it on a case-by-case basis, but wherever possible we aim to make this setting change both the application's primary language and the administrtive user's selected language.

Note that this setting does not tend to affect the localisation that visitors will see the website in as most applications will use the visitor's own browser settings to determine the best localisation for them.

With that said, if you include this internal-field then <get> should probably return the app's administrative user's current language setting and the <set> should change both the application's language and the administrative user's language to use Installatron's $this->input["field_language"] value.

Pro tip: what if the application only comes with the English locale files, as many apps do, and the other translations need to be downloaded separately? Changing the database values won't cut it, will it? No, it won't! You will need to expand this code to either:

add an $this->extract(); to extract an extra archive that has been attached to this version of this installer, or;

add some code that will download and install the locale files (if they aren't already present).

login

get & set

This gets and sets the application's administrative user's username. The <get> should return the user's current username and the <set> should use Installatron's $this->input["field_login"] value to set a new username (usually set somewhere in the app's database).

passwd

The <set> should use Installatron's $this->input["field_passwd"] value to set a new password (usually set somewhere in the app's database).

Passwords are almost always encoded in some way so your task here is to replicate the encoding method used by the application. In the example code here, for example, the password is simply encoded with md5() however it's possible that you will need to replicate some of the application's encoding code here in order to match the format perfectly.

The result of encoding it incorrectly is that you won't be able to log in as the administrator after installing the app.

sitedescription

get & set

This gets and sets the application's website description (the detailed text that is usually displayed on the website's front page). The <get> should return the current description and the <set> should use Installatron's $this->input["field_sitedescription"] value to set the website's new description (usually set somewhere in the app's database).

sitetitle

get & set

This gets and sets the application's website title (the text that is usually displayed on the website's front page and in the web browser's title bar). The <get> should return the current title and the <set> should use Installatron's $this->input["field_sitetitle"] value to set the website's new title (usually set somewhere in the app's database).

Custom Fields

Installatron also allows you to define your own fields. They are also added to the <fields>...</fields> definition, like their internal counterparts, and they typically look something like this:

<field {ID} {TYPE} {DEFAULT_VALUE}><label>{LOCALE_TAG_1}</label>
[<options><optionvalue="yes">{LOCALE_TAG_2}</option><optionvalue="no">{LOCALE_TAG_3}</option></options>]
<get><?php return /* return the value for this field */ ?></get><set><?php /* code to set this field using the Installatron $this->input["field_{ID}"] value */ ?></set>
[<verify><?php /* code code to verify that the user has entered a valid value */ ?></verify>]
</field>

The <label>...</label> element is new here and it is simply the Bold Text that appears directly above this input when you are installing or editing the app (eg. like Administrator Email is the build-in label for the internal email field). We would always add a localisation tag and use that here, but you can also use straight text.

The <options>...</options> element is also new, but you only need that for certain {TYPE}s of fields so let's now have a close look at each custom field type:

radio

When installing the app this let's you collect a text string from the user which you can use for any purpose.

Requires a default value (matching one of its options) and also requires <options>. Shouldn't need to verify the values here but you can add a <verify> element if you wish.

<fieldid="{ID}"type="radio"value="{DEFAULT_VALUE}"><options><optionvalue="{VALUE1}">{LOCALE_TAG_2}</option><optionvalue="{VALUE2}">{LOCALE_TAG_3}</option>
...
</options><get><?php return /* return the current value here */ ?></get><set><?php /* use $this->input["field_{ID}"] here to do whatever you want this field to do */ ?></set></field>

text

When installing the app this let's you collect a text string from the user which you can use for any purpose.

Does not require a default value and does not use <options>.

<fieldid="{ID}"type="text"value=""><get><?php return /* return the current value here */ ?></get><set><?php /* use $this->input["field_{ID}"] here to do whatever you want this field to do */ ?></set>
[<verify><?php /* code code to verify that the user has entered a valid value */ ?></verify>]
</field>

The Other Package Files

installerid/

The installer id is lowercase alphanumeric key that must be unique to the installer. Usually these are named after the application being installed, so for example the id for our own phpBB installer is phpbb, the WordPress installer is wordpress and so on.

installerid/init.xml

The first of the two init.xml files that, together, really hold the important information and functionality of Installatron installers.

This init.xml, the installer init.xml as we refer to it, holds all the information that is specific to the installer or the application as a whole. The version-specific information goes in the version init.xml.

app_category is one of these: or any plain text to create a new category of application.

inputid keys are only used if custom fields are used in the installer. inputid is the id of the input (see fields section below).

formal_description is a description of the application in an formal format. Look at the descriptions in Installatron to see the format used.

authors_description is a longer description of the application, usually quoted from the website of the application.

NOTE: you can also add your own locale keys, using the _installer_installerid_ prefix on any lines that you add.

<?php
itron::$locale = array_merge(itron::$locale,array(
"_installer_wordpress_title" => "WordPress",
"_installer_wordpress_type" => "_types_blog",
"_installer_wordpress_category" => "_categories_contentmanagementsystems",
"_installer_wordpress_description" => "WordPress is an open source blog application. WordPress forked from b2/cafelog in 2003, and WordPress Mu multiple website functionality has been integrated since 2010. Today WordPress is the most used blog application powering millions of blogs and being used by tens of millions of people every day.",
"_installer_wordpress_authordescription" => "WordPress is a personal publishing platform and blogging application with a focus on aesthetics, web standards, and usability.<br><br>Features:<ul><li>Additional pages allow you to manage non-blog content easily, so for example you could have a static "About Me" page.<li>A full theme system enables designing everything from the simplest blog to the most complicated webzine a piece of cake.<li>Changes made to templates and entries are reflected immediately on your site, with no need for regenerating static pages, and all generated HTML is fully compliant with W3C standards.<li>Trackback and Pingback standards fully supported.<li>Visitors can post comments on your blog entries, and commenting can be disabled on a per-post basis.<li>Spam protection eliminates comment spam from your blog.<li>User registration enables visitors to register and maintain profiles and leave authenticated comments on your blog, if enabled.<li>Password Protected Posts enables you to give passwords to individual posts to hide them from the public.<li>A full XML-RPC interface enables you to extend WordPress and use clients designed for other platforms like Zempt.<li>User groups enables up to 10 levels of users, with different levels having different (and configurable) privileges with regard to publishing, editing, options, and other users.<li>Bookmarklets make it easy to publish to your blog or add links to your blogroll with a minimum of effort.<li>Ping-O-Matic is supported, which means maximum exposure for your blog to search engines.</ul>",
"_installer_wordpress_multisite_yes" => "Yes, enable multi-site support for sub-directories of the selected install location.",
"_installer_wordpress_multisite_no" => "No, do not enable. Multi-site can be enabled later within WordPress. (Recommended)",
"_installer_wordpress_limitloginattempts_yes" => "Yes, limit failed login attempts for increased security. (Recommended)",
"_installer_wordpress_limitloginattempts_no" => "No, do not limit failed login attempts.",
));
?>

installerid/ss1.jpginstallerid/ss2.jpginstallerid/ssN.jpg

installerid/version/

There is one version/ directory for each version of the application that is supported by the package. If the package installs a single version, or does not support upgrading, then there will be a single version directory. The version should have no spaces, and should only use characters that can be used in a directory name.

installerid/version/LICENSE

installerid/version/init.xml

The second of the two init.xml files that, together, really hold the important information and functionality of Installatron installers.

This init.xml, the version init.xml as we refer to it, holds all the information that is specific this version of the installer or the application. The version-non-specific information goes in the installer init.xml.

(Option 1) Use Installatron's addon-installer system.

An addon-installer is comprised of two files: the first is a tar.gz archive containing the application package (this is created by the editor). The second file is a controller file which looks like this:

installerid is the unique id of the installer.build_number is the current build number of the installer. Increment this number whenever the installer is edited.url_to_installer is a URL to the application package archive. The archive must be a gzip-compressed tar archive, and must be created using our Application Installer Editor tool.

Example

Let's create an example application package with the id joomla.

When we're ready to test it we go to the Publisher tab and click the Publish button.

That will create an archive named joomla.tar.gz, which we download to our PC and then upload to a public web location somewhere. Let's upload it to http://my_domain/my_installers/joomla.tar.gz for this example.

Then we create this catalog file (or edit the one provided by Publisher) named joomla.xml:

That will add the joomla application package to Installatron. Installatron will check the joomla.xml file each time an update/repair is run to see if the build number has changed. If it has changed, it will download the installer again.

More information is provided on the Publisher page in the editor.

(Option 2) Use WGET to download the application package directly from the editor to your server.

The wget shell command can be used to transfer application packages directly to the /var/installatron/installers directory. Details are provided on the Publisher tab in the editor.

This option is only available for PHP5 because PHP4 uses a different application package format, which must be created using the Publisher tool in the editor.

This approach is also good for quick development, but should only be used during development. Once an application package is finished, you should use method 1 above.

(Option 3) Manually add the application package to your server.

It's also possible to manually upload/make the files and directories directly in the /var/installatron/installers directory.

This option is only available for PHP5 because PHP4 uses a different installer format which is [i]required[/i] to be created using the Publisher tool in the editor.

If you are good with vim then this might be a quick way to edit and test your application package.

Reference: Variables, Commands, and How-Tos

This section lists the variables and commands that can be used in application package installer and upgrader code, and some how-to explanations. See the Overview section for a closer look at the packaging format.

The values associated with the application's database. This requires that the "database" requirement is enabled.

These are; the hostname of the MySQL server, the database username, the username's password, the name of the database, the table prefix used by tables in the database, and finally, the type of database.

Reclaim

NOTE: If a directory is selected then this function is automatically recurrent; all files and directories under the chosen directory will also be reclaimed.

$this->_reclaim("path_and_filename");
// examples
$this->_reclaim("config.php"); // just this one file
$this->_reclaim("wp-content"); // this is a directory so this is automatically recurrent!
$this->_reclaim("wp-content/tmp/*"); // globbing works

Pro tip: be aware that this function name begins with the underscore ("_").

Var Export

Reference: Language Identifier

This table lists Installatron's Language Identifier for most languages that are in use today (used for the XML <languages> tag). If support is required for a language that is not listed, please contact us.

Pro Tips

Use array() in installer functions

You might have noticed in the entry for Fetch and Search-Replace above that an array() could be optionally provided in order to perform the same task multiple times. The ability to provide an array is available in many of the functions and in many combinations. Here is a dump of ways that array() can be used in the above functions.

Troubleshooting

If your application package isn't displaying or installing, the first place to check is the Installatron logs. These can be viewed from Administration, or if you need to see more than just the last few lines you can find them here:

/var/installatron/logs

The filesystem_log is usually the most useful as it logs the result of every $this-> command. The fetch_log logs the result of every call to a URL, so that includes all control panel API calls, all downloads, and all $this->fetch() commands.

Browse below for some of the more common application package problems and their fixes.

archive 'main' not found

CAUSE

Installatron failed to download the 'main' archive.

The causes are usually either a) the archive is not at a publically accessible location, or b) the MD5 checksum is wrong.

DOWNLOAD LOCATION SOLUTION

Make sure that the URL to the archive can be downloaded with a wget command from the server. If wget can get the file then Installatron can too.

INCORRECT MD5 CHECKSUM SOLUTION

The MD5 checksum, used to verify that the archive has downloaded correctly, is not shown in the Editor GUI at this time so to fix it you need to:

Go to the Source Editor tab and scroll down to the version info textarea (it contains the archive info).

Delete the md5= value. If you know the correct md5 value you can add it here. Then save.

If you didn't know the correct md5 value, go to the Version Info tab and then save. This will download the archive and find the md5 value.

my application package isn't listed

CAUSE

If the application package is listed in Administration > Access Groups > Edit but is not showing in the Application Browser then the cause is usually requirement filtering.

SOLUTION

Check the requirements you have configured for the script (Editor > Version Info > Requirements) and compare them with the Administration > Applications > Dependencies configuration in Installatron.