Login/Register
Support
Last Update: 2020-11-15 (WORK IN PROGRESS)

Application Packaging SDK

Index

  1. Quickstart Guide
  2. Installer Structure
  3. A Note About PHP5 Verses PHP7
  4. Creating an application package
  5. Using Your Installer



Back to top▴

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.

Back to top▴

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 app
    version1/            // 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)
Back to top▴

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.

Back to top▴

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.

See the Reference: Variables, Commands, and How-Tos section for a closer look at the things you can use in application package installer and upgrader code, the Using an Installer section for information on adding the application package to your server, or read The Package Files for a look at each file and directory in an Installatron application package.

What follows is a close look at the 5 main files and functions associated with the installer, where 99% of the work is performed. If you understand the installer init.xml, the version init.xml, the installer, the upgrader, and finally fields, then you know how Installatron installers work.

Back to top▴

The Installer init.xml

The top-level init.xml file contains general information about the installer and the application it installs. Here is the format:

<?xml version='2.0'?>
<installer>
    <information>
        <info id="id" value="{ID}"/>
        <info id="build" value="{INSTALLER_BUILD_NUMBER}"/>
        <info id="status" value="{enabled|disabled}"/>
        <info id="name" value="{NAME}"/>
        <info id="type" value="{TYPE}"/>
        <info id="category" value="{CATEGORY}"/>
        <info id="created" value="{YYYY-MM-DD}"/>
        <info id="description" value="{INTRODUCTION}"/>
        <info id="authordescription" value="{APP_AUTHOR'S_DESCRIPTION}"/>
    </information>
    <links>
        <!-- a collection of links associated with this application -->
    </links>
    <versions>
        <branch id="current">
        <branch id="current">
            <version id="{VERSION3}" upgrade="{auto|skip|manual|none}" install="{auto|none}"/>
            <version id="{VERSION2}" upgrade="{auto|skip|manual|none}" install="{auto|none}"/>
            <version id="{VERSION1}" upgrade="none" install="auto"/>
        </branch>
        </branch>
    </versions>
</installer>

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

Back to top▴

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>

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

Back to top▴

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.

Back to top▴

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).

Back to top▴

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>
	<field id="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>
			<option value="yes">{LOCALE_TAG_2}</option>
			<option value="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.

Back to top▴

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:

And now we'll look at the two types of Installatron fields; internal fields (those that Installatron automatically recognises and automates much of), and custom fields:



Back to top▴

The Other Package Files

todo...

Back to top▴

Using Your Installer

There are three ways to add your Installatron application package to your server. The three methods are:

Back to top▴

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.

Variables

Functions

Back to top▴

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.

(the language identifier table is hidden)

Back to top▴

Pro Tips

Back to top▴

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.

Back to top▴

Change log


© 2004 - 2023 Installatron LLC. All rights reserved. Privacy Policy.