If your server is updated from PHP 7 to PHP 8 then you will need to change each line that starts with:
function
-to be replaced with:
public static function
The examples below have been updated.
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.
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
{
public static 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", "wordpressinstall");
}
public static 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:
<?php class i_installer_customcode {
Opening boiler-plate.
public static function init($o)
The init function is called prior to the execution of all Installatron tasks (install, update, clone, uninstall, etc). It registers callback functions at a variety of hook points within the tasks 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 during a selected task (aka subsystem).
$o->registerCustomCode("app", "limit_version", "subsystem", "hook", "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", "import", "importbackup", "uninstall", "backup", "restore", "clone", "edit", "template", "upgrade", "upgradeplugin", or "upgradetheme" subsystems. The keyword "all" can be specified.
hook specifies the hook location, within the install/upgrade/etc subsystem, that this callback function should be called. The available hooks are described in more detail below.
function specifies the name of the callback function that will be called when this hook is reached.
public static 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 task object contains a vast collection of information that can be used to help customize the application, from the path of the 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->.
} ?>
Closure boiler-plate.
All hooks have these variables available in your function:
$o->input stdin (array) $o->owner user details (array) $o->install->ini installation details (array)
And these are the full list of hooks that are available:
Will call your function at the beginning of the task, just after validating sanity. Available to "all" subsystems.
Will call your function to add app input fields. Available to "install" subsystem only.
Will call your function directly after any CHMOD action. Available to "all" subsystems.
These additional variables are available to your function. These variables describe the CHMOD that was just performed:
$o->customCodeArgs[0] list of the files/directories that were just chmod'd (array) $o->customCodeArgs[1] chmod value given to files (octal) $o->customCodeArgs[2] chmod value given to directories (octal) $o->customCodeArgs[3] was it recursive? (bool)
Will call your function directly prior to issuing any outgoing HTTP request. Available to "all" subsystems.
Will call your function at the end of any archive creation process. Available to "all" subsystems.
Will call your function at the end of the task, just before all processing is completed. Available to "all" subsystems.
This is the hook that you will most commonly use.
Will call your function at the very end of the task, after all processing is completed. Available to "all" subsystems.
Use this hook to send email notifications.
These additional variables are available to your function. These describe the success or failure of the task:
$o->hasErrors() was the task result an error? (bool) $o->getFinalMessage() the final task result message (string)
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
{
public static function init($o)
{
$o->registerArchive("wpthdivi", "http://example.com/divitheme_just_an_example.zip", "zip");
$o->registerCustomCode("wordpress", "all", "install", "input", "wordpressinstallinput");
$o->registerCustomCode("wordpress", "all", "install", "last", "wordpressinstall");
}
public static function wordpressinstallinput($o)
{
$o->setInputFields(array(
array(
"ID" => "package_type",
"LABEL" => "Divi",
"TEXT" => "Install the DIVI theme?",
"TYPE" => "radio",
"VALUE" => "yes",
"OPTIONS" => array( "yes" => "Yes", "no" => "No")
)
));
}
public static 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
{
public static function init($o)
{
$o->registerArchive("exampleplugin", "http://example.com/plugin_just_an_example.tar.gz", "tar.gz");
$o->registerCustomCode("wordpress", "all", "install", "input", "wordpressinstall");
}
public static function wordpressinstallinput($o)
{
$o->setInputFields(array(
array(
"ID" => "plugin",
"LABEL" => "Plugin",
"TEXT" => "Install the PLUGIN plugin?",
"TYPE" => "check",
),
));
}
public static 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
{
public static function init($o)
{
$o->registerArchive("jetpack", "http://downloads.wordpress.org/plugin/jetpack.zip", "zip");
$o->registerCustomCode("wordpress", "all", "install", "last", "wordpressinstall");
}
public static 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).
Don't hesitate to contact Installatron Support with any questions regarding this system.