Login/Register
Last Update: 2019-05-05 (WORK IN PROGRESS -- currently being updated to the new format)

Application Packaging SDK

Index




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)
        install.php      // PHP5 install code for this version
    version2/            // another version sub-directory (optional)
        LICENSE
        init.xml         // information for this version (including PHP7 install and upgrade code)
        install.php      // PHP5 install code for this version
        upgrade.php      // PHP5 upgrade code for upgrading to this version (optional)
Back to top▴

A Note About PHP5 Verses PHP7

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 is running on PHP5 and internal init.xml elements for when Installatron is running on any version of PHP7. The code used by both versions is very similar.

Note that the Installatron installer Editor tool lets you edit installers in the new format but it automatically builds the additional PHP5-only files each time you save.

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 blow for a closer look at each file and directory in an Installatron application package:

Back to top▴

installerid/version/install.php

The install.php file installs this version of the application.

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

Here is the format, with some example content included:


<?php

class i_{INSTALLERID}_{STRIPPEDVERSION}_install extends i_action_install
{
   
//==========================================================================
    // STEP II: ARCHIVE EXTRACTION
    //==========================================================================

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

    public function 
step2_process()
    {
        
// extract main archive:
        
$this->extract('main');
    }

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

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

    public function 
step3_process()
    {
        
// THIS IS AN EXAMPLE SET OF INSTALL STEPS

        // move the contents of this directory back into the install directory
        
$this->mv('myapplication-2.0.0/*','.');

        
// chmod files and/or directories
        
$this->chmod(array('CHMOD_DIRECTORY_ONE','CHMOD_DIRECTORY_TWO'),0777);
        
$this->chmod(array('CHMOD_FILE_ONE','CHMOD_FILE_TWO','PATH/CHMOD_FILE_THREE'),0666);

        
// use regex to edit a file (replace the hard-coded table prefix with the Installatron-generated prefix)
        
$this->sr('INSTALL/MYSQL_FILE_ONE.sql''#PREFIX_#'$this->db_prefix);

        
// import a MySQL .sql file to create or populate the database
        
$this->db_import('INSTALL/MYSQL_FILE_ONE.sql');

        
// use regex to edit a file:
        // - insert the Installatron-generated database values into the config file
        // - insert the path and url into the config file
        
$this->sr("CONFIG_FILE.php", array(
                
"#DB_VAR_HOST = '.*?'#" => "DB_VAR_HOST = ".var_export($this->db_host,true),
                
"#DB_VAR_NAME = '.*?'#" => "DB_VAR_NAME = ".var_export($this->db_name,true),
                
"#DB_VAR_USER = '.*?'#" => "DB_VAR_USER = ".var_export($this->db_user,true),
                
"#DB_VAR_PASS = '.*?'#" => "DB_VAR_PASS = ".var_export($this->db_pass,true),
                
"#DB_VAR_PREF = '.*?'#" => "DB_VAR_PREF = ".var_export($this->db_prefix,true),

                
"#SCRIPT_PATH_VAR = '.*?'#" => "SCRIPT_PATH_VAR = ".var_export($this->path,true),
                
"#SCRIPT_URL_VAR = '.*?'#" => "SCRIPT_URL_VAR = ".var_export($this->url,true),

        ));

        
// execute the applications own install API
        
$this->fetch('install.php',array( 'mode' => 'automatic' ));

        
// clean up
        
$this->chmod('FILEONE',0644);
        
$this->rm(array('FILETWO','DIRECTORYONE'));

    }

}

?>
Back to top▴

installerid/version/upgrade.php

The upgrade.php file upgrades an install to this version of the application from the previous version.

The upgrade file uses the same format as install.php (see above), with any number of steps and each step has an _init (for setting up the page for that step) and _process (for doing stuff). Unlike install.php, step 1 is not reserved for settings, and it's more common to have just one or two steps.

Here is the format, with some example content included:


<?php

class i_{INSTALLERID}_{STRIPPEDVERSION}_upgrade extends i_action_upgrade
{
    
//==========================================================================
    // STEP I: ARCHIVE EXTRACTION
    //==========================================================================

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

    public function 
step1_process()
    {
        
$this->extract("xtra1""upgradetemp");
    }

    
//==========================================================================
    // STEP II: CONFIGURING INSTALL
    //==========================================================================

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

    public function 
step2_process()
    {
        
$this->rm("upgradetemp/config.php");
        
$this->mv("upgradetemp/*");
        
$this->rm("upgradetemp");

        
$this->fetch("upgrade/update_to_latest.php");
        
$this->rm("upgrade");
        
    }

}

?>
Back to top▴

Using Your Installatron Application Package

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▴

Language Identifier Reference

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.

abAbkhazianaceAcehnese (Acèh)achAcoliadaAdangmeadyAdyghe; Adygei
aaAfarafhAfrihiliafAfrikaansafaAfro-AsiaticainAinu
akAkanakkAkkadianalnAlbanian (Gegë)sqAlbanian (Shqip)alsAlemannisch
aleAleutalgAlgonquianamAmharicanpAngikaarArabic
arzArabic (Egyptian)aryArabic (Moroccan); MaġribianAragonésarcAramaicarpArapaho
arwArawakhyArmenianroa_rupArmãneashcerupAromanian; Arumanian; Macedo-RomanianfrpArpetan
asAssameseastAsturian; Bable; Leonese; AsturleoneseathAthapascanausAustralianavAvar
aeAvestanayAymaraazAzerbaijanibjnBahasa BanjarbqiBakhtiari
bccBalochi SouthernbmBambara (Bamanankan)jvBasa JawabaBashkirminBaso Minangkabau
euBasque (Euskera)beBelarusianbe_taraskBelarusian (Taraškievica)bemBembabnBengali
bhoBhojpuridzBhutani (Dzongkha)bhBiharibclBikol Central (Bicolano)bpyBishnupria
biBislamabarBoarischbsBosanskibrBretonbugBuginese
bgBulgarianmyBurmesecpsCapiceñocaCatalancebCebuano
chChamorrocbkChavacano (Spanish)cbk_zamChavacano de ZamboangaceChechenchrCherokee
chyCheyennenyChichewaganChinese GanhakChinese HakkaczhChinese Huizhou
cjyChinese JinyucmnChinese MandarinmnpChinese Min BeicdoChinese Min DongnanChinese Min Nan
czoChinese Min ZhongcpxChinese Pu XianwuuChinese WuhsnChinese XiangyueChinese Yue (Cantonese)
choChoctawcvChuvashseiCmique ItomkwCornishcoCorsican
hrCroatiandaDanskpdcDeitschdeDeutschndsDeutsch (Plattdüütsch)
de_chDeutsch (Schweizer Hochdeutsch)de_formalDeutsch (Sie-Form)de_atDeutsch (Österreichisches)dsbDolnoserbskidtpDusun Bundu-liwan
emlEmiliàn e rumagnòlenEnglishangEnglish (Old)en_ukEnglish (United Kingdom)myvErzya
es_419Español (Latin American)es_mxEspañol (Mexico)esEspañol (Spanish)eoEsperantoetEstonian
extEstremeñueeEwefoFaroesefjFijianhifFiji Hindi
filFilipinovlsFlemish (West-Vlams)frFrançaisfrcFrançais (Cadien)fyFrysk
ffFulfuldefurFurlanglGaelggagGagauzkaGeorgian
glkGilakigotGothicklGreenlandicgnGuaraniguGujarati
htHaitian CreolehaHausahawHawai`iheHebrewhzHerero
hiHindihoHiri MotuhsbHornjoserbsceisIcelandicioIdo
igIgboiloIlokanohilIlonggoidIndonesianinhIngush
iaInterlinguaieInterlingueiuInuktitutike_cansInuktitut (ᐃᓄᒃᑎᑐᑦ)ikInupiak
gaIrishitItalianoit_formalItaliano (Formal)jaJapanesejwJavanese
jutJyskkbdKabardianxalKalmykknKannadakrKanuri
pamKapampangankrcKarachay-BalkarksKashmiricsbKaszëbsczikkKazakh
kmKhmer (Cambodian)khwKhowarkiKikuyukrjKinaray-arwKinyarwanda
kiuKirmanjkirnKirundikvKomikoiKomi-PermyakkgKongo
koKoreanavkKotavakriKriokuKurdishckbKurdish (Central)
kjKwanyamakyKyrgyzladLadinolbeLakloLaothian
ltgLatgaļulaLatinlvLatvianlzzLazurilezLezghian
ltLietuvių (Lithuanian)lijLigureliLimburgslnLingalalfnLingua Franca Nova
lzhLiterary Chinese (Classical)livLivjboLojbanlolLolspeaklgLuganda
lmoLumbaartluoLuolbLuxembourgishmkMacedonianhuMagyar (Hungarian)
vmfMainfränkischmaiMaithilimgMalagasymsMalay (Bahasa Malaysia)mlMalayalam
dvMaldivianmtMaltesegvManxmiMaoriarnMapuche (Mapudungun)
mhrMari (Eastern)mrjMari (Western)mhMarshallesemfeMauritian CreolemznMazanderani
xmfMingrelianmwlMirandésmdfMokshamoMoldavianmnMongolian
sr_meMontenegrinmusMvskokenaNaurunvNavajongNdonga
nlNederlands (Dutch)nl_informalNederlands InformeelnewNepal BhasaneNepaliniuNiuē
napNnapulitanofrrNordfriiskpihNorfuk; PitkernndNorth NdebelenoNorwegian
nbNorwegian (Bokmål)nnNorwegian (Nynorsk)nrmNouormandnahNāhuatlcrNēhiyawēwin (Cree)
ocOccitancuOld SlavonicorOriyaomOromoosOssetian
pagPangasinanpnbPanjabi (Western)papPapiamentupsPashtofaPersian
pflPfaelzischpcdPicardpmsPiemontesecpePijin SolomonpdtPlautdietsch
plPolskipntPonticptPortuguês (Portuguese)pt_brPortuguês do BrasilprgPrūsiskan
paPunjabikaaQaraqalpaqshaquQuechuacrhQırımtatarca (Chimean Tatar)kshRipoarisch
rgnRomagnolrmyRomaniruqRomanian MeglenormRomanshroRomână
qugRuna shimibxrRussia BuriatruRussianseSami (Northern)smaSami (Southern)
smSamoansgsSamogitiansgSangosaSanskritscSardinian
sdcSassaresusliSchläschscoScotsgdScots GaelicstqSeeltersk
srSerbiansr_elSerbian (Srpski)sr_ecSerbian (Српски)shSerbo-CroatianstSesotho
tnSetswanasnShonaiiSichuan Yi; NuosuscnSicilianuszlSilesian
lozSilozisdSindhisiSinhalesessSiswatiskSlovak (Slovakian)
slSlovenščina (Slovenian)soSomalinsoSotho (Northern); Pedi; SepedialtSouthern AltainrSouth Ndebele
srnSranantongosuSundanesefiSuomiswSwahilisvSwedish
gswSwiss GermanshiTachelhittlTagalogtyTahitiantgTajik
taTamilkabTaqbaylitroa_taraTarandínerifTarifitttTatar
teTelugutetTetunthThaiboTibetantiTigrinya
tpiTok PisintoTongaluTshilubatsTsongatcyTulu
tumTumbukatkTurkmentvlTuvaluantyvTuviniantwTwi
trTürkçe (Turkish)udmUdmurtugUighururUrduuzUzbek
veVendavecVenetianvepVepsanviVietnamesevoVolapük
votVoticvroVõrowaWaloncyWelshwarWinaray
woWolofxhXhosasahYakutyiYiddishyoYoruba
diqZazakizeaZeeuwszaZhuangzuZulucsČesky (Czech)
cs_informalČesky NeformálníelΕλληνικά (Greek)rueРусиньскый (Rusyn)ukУкраїнська (Ukrainian)piपािऴ (Pali)
mrमराठी (Marathi)grcἈρχαία ἑλληνικὴ (Ancient Greek)zh中文 (Chinese Simplified)zh_tw中文(台灣) (Chinese Traditional)
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 - 2019 Installatron LLC. All rights reserved.