Login/Register

Customization Changes (2018-10-22)

The Customization class has changed slightly to support PHP 7.2 servers going forward. This new format will also work on pre-PHP 7.2 servers so you are free to update your code at any time. The old format is still supported for servers PHP pre-7.2.

The changes are minimal:

1. The init() function is updated to be: init($o)
2. All instances of $this-> in the init($o) function are now replaced with: $o->

That will allow Customization to work on PHP 7.2 and forward, and as a bonus it will also stop a number of logged warning on earlier versions of PHP.

Last Update: 2018-10-23

Application Package Modification and Customization Guide

Installatron Server and Installatron Plugin benefit from a robust modification and customization system that enables changes to be applied to any custom or Installatron-maintained application package. This system can be used to add additional languages, add plugins or templates, or make just about any convincible change. Best of all, the system is designed to be simple and only requires very minimal programming knowledge to use.

The idea behind this system is to "register" one or more sets of commands to be executed at specified locations within each install and/or upgrade process. These sets of commands should be formatted according to this guide and written to the /usr/local/installatron/etc/installercustomcode.php file or entered to the Customize installers code field in Administration >> Applications >> Customization.

For example, take this sample installercustomcode.php file:


<?php
class i_installer_customcode   
{   
       function 
init($o)
       {
               
$o->registerArchive("wp_supercache","http://downloads.wordpress.org/plugin/wp-super-cache.1.0.zip""zip");
               
$o->registerCustomCode("wordpress""all""install""last""process""wordpressinstall");
       }

       function 
wordpressinstall($o)
       {
               
$o->extract("wp_supercache""wp-content/plugins");
       }
}
?>

In this example we extract an archive containing the WordPress SuperCache plugin after each WordPress install. And if you were familiar with the old example code then note that $this-> has been replaced with $o-> in this updated example in order to be compatible with PHP 7.2+.

Let's look at each line of code in this example:

function init($o)

The init function is called prior to the execution of every install and upgrade. It registers callback functions and actions for later execution.

$o->registerArchive()

A registerArchive call registers an archive that a callback function can later extract. This can be used to add plugins or themes to the standard install.

$o->registerArchive("id", "url", "archive_type", "md5_checksum");

id is a unique id, typically within the A-Za-z0-9_ character set, for the archive being registered.

url is the URL to the archive.

archive_type is the type of archive and can be "tar", "tar.gz" or "zip". No other types are currently supported.

md5_checksum is the md5 checksum of the archive. This field is optional.

$o->registerCustomCode()

A registerCustomCode call registers a callback function to be executed at a specified hook during the install and/or upgrade processes.

$o->registerCustomCode("app", "limit_version", "subsystem", "hook", "hook2", "function");

app is the ID of the application package the code pertains to.

limit_version defines a specific version the code should be limited to, or if the code applies to all versions, the keyword "all" can be specified.

subsystem specifies whether the code should be executed for the "install", "uninstall", or "upgrade" processes.

hook specifies the hook location, within the install/upgrade process, that this callback function should be called. A value of "last" executes the code at the end (recommended). A value of "1" executes the code before the install/upgrade process has started (ie. when input fields are presented to the client). A value of "2" executes at the beginning of the actual install process.

hook2 provides further accuracy in regards to when the specified callback function should be called. Typically, a value of "process" is used. However, a value of "init" should be used when defining input fields.

function specifies the name of the callback function that will be called when this hook is reached.

function wordpressinstall($o)

The wordpressinstall($o) function is an example callback function. It will be called when the hook specified in the init($o) function is reached. The incoming $o object is an instance of the task object. This object contains a vast collection of information that can be used to help customize the application, from the path to its install directory ($o->path) to all of the incoming field values (eg. $o->input["field_login"]) to commands for creating/reading/editing files (eg. $o->write("test.txt", "test content") to commands for manipulating the application's database (eg. $o->db_query(...)).

See the Installatron Application Packaging SDK: A function reference for a full list of the commands and values available in this object, but just note that to use any of the examples from that reference page in Customization you need to replace $this-> with $o->.

Further Examples

This example uses the "init" stage of the "1" (1st step) install hook to add an extra field to the WordPress settings page. This example asks the user "Install the DIVI theme?" and the result of that selection is later used a callback from the very last hook in the install process ("last", "process") to optionally install an example WordPress theme:


<?php
class i_installer_customcode
{
    function 
init($o)
    {
        
$o->registerArchive("wpthdivi""http://example.com/divitheme_just_an_example.zip""zip");
        
$o->registerCustomCode("wordpress""all""install"1"init""wordpressinstallinput");
        
$o->registerCustomCode("wordpress""all""install""last""process""wordpressinstall");
    }
    
    function 
wordpressinstallinput($o)
    {
        
$o->setInputFields(array(
            array(
                
"ID" => "package_type",
                
"LABEL" => "Divi",
                
"TEXT" => "Install the DIVI theme?",
                
"TYPE" => "radio",
                
"OPTIONS" => array( "yes" => "Yes""no" => "No")
            )
        ));
    }
    
    function 
wordpressinstall($o)
    {
        if (
$o->input["field_package_type"] === "yes")
        {
            
$o->extract("wpthdivi""wp-content/themes");
            
$o->db_query("UPDATE {$o->db_prefix}options SET option_value='Divi' WHERE option_name='template' LIMIT 1;");
            
$o->db_query("UPDATE {$o->db_prefix}options SET option_value='Divi' WHERE option_name='stylesheet' LIMIT 1;");
        }
    }
}
?>

That example used a "radio" field but it could also be a checkbox:


<?php 
class i_installer_customcode 

    function 
init() 
    { 
        
$this->registerArchive("exampleplugin""http://example.com/plugin_just_an_example.tar.gz""tar.gz"); 
        
$this->registerCustomCode("wordpress""all""install"1"init""wordpressinstall"); 
    } 
    
    function 
wordpressinstallinput($o
    { 
        
$o->setInputFields(array( 
            array( 
                
"ID" => "plugin"
                
"LABEL" => "Plugin"
                
"TEXT" => "Install the PLUGIN plugin?"
                
"TYPE" => "check"
            ), 
        )); 
    } 
    
    function 
wordpressinstall($o
    { 
        if ( isset(
$o->input["field_plugin"]) && $o->input["field_plugin"] == "1" 
        { 
            
$o->extract("plugin""wp-content/plugins"); 
        } 
    } 

?>

That example installed an imaginary WordPress plugin, but it was an example where you only needed extract the plugin's archive into the correct location. Most WordPress plugins, however, require more work to enable them. Installatron has two built-in commands for enabling and disabling WordPress plugins that makes this process much simpler. Here's an example that installs one new example plugin and disables two other plugins:


<?php 
class i_installer_customcode 

    function 
init() 
    { 
        
$this->registerArchive("exampleplugin""http://example.com/plugin_just_an_example.tar.gz""tar.gz"); 
        
$this->registerCustomCode("wordpress""all""install"1"init""wordpressinstall"); 
    } 
    
    function 
wordpressinstall($o
    { 
        
// there's no need to extract the archive here; the installPlugin() command handles that automatically
        
$o->installPlugin("jetpack/jetpack.php""jetpack");
        
        
// you don't need to check if a plugin exists before disabling it this way; these commands fail 
        // gracefully if the plugin is not found
        
$o->disablePlugin("akismet/akismet.php");
        
$o->disablePlugin("hello.php");
        
$o->rm("wp-content/plugins/hello.php");
        
$o->rm("wp-content/plugins/akismet/");
    } 

?>

And finally, this link takes you to a Github-hosted repository of someone's own Customization code. This gives you a good idea of how much work it's possible to do inside this system: DTLT / installatron-custom-code.

And remember that the Installatron Application Packaging SDK: A function Reference has a full list of commands and values available in the $o-> object (and remember that all example code on that page needs $this-> replaced with $o->, as you see above, in order to work in Customization).

Need assistance?

Don't hesitate to contact Installatron Support with any questions regarding this system.

© 2004 - 2018 Installatron LLC. All rights reserved.