Modules

This document describes how to implement Modules. A Module allows packages and services to be created. They define the fields requested when adding or editing packages and services, as well as handle all communication with remote servers to provision said packages and services.

Getting Started with Modules

For the purpose of this manual, the module name we'll refer to is my_module. Your module name will, of course, differ.

File Structure

Modules are fully contained within their named module directory and placed in the /installpath/components/modules/ directory. Each module is only required to contain a single class, representing the module, but the following is the recommended structure:

• /modules/
  • my_module/
    • views/
    • language/
    • my_module.php

Install Logic

If your module requires any code to execute when installed, place that logic in your module's install() method.

<?php
class MyModule extends Module {

    ...

    public function install() {
        #
        # TODO: Place installation logic here
        #
    }
}
?>

Uninstall Logic

If your module required code to install, it likely requires code to uninstall. Place that logic in your module's uninstall() method.

There are two parameters passed to the uninstall() method. The first ($module_id) is the ID of the module being uninstalled. Because a module can be installed independently under different companies you may need to perform uninstall logic for a single module instance. The second parameter ($last_instance) identifies whether or not this is the last instance of this module in the system. If true, be sure to remove any remaining remnants of the module.

<?php 
class MyModule extends Module {

    ... 

    public function uninstall($module_id, $last_instance) {
        #
        # TODO: Place uninstallation logic here 
        #
    } 
} 
?>

Upgrade Logic

When the version of your code differs from that recorded within Blesta a user may initiate an upgrade, which will invoke your module's upgrade() method.

The $current_version is the version currently installed. That is, the version that will be upgraded from.

<?php
class MyModule extends Module {

    ...

    public function upgrade($current_version) {
        #
        # TODO: Place upgrade logic here
        #
    }

}
?>

Error Passing

Blesta facilitates error message passing through the use of the Input component. Simply load the Input component into your module and set any errors you encounter using Input::setErrors(). The setErrors() method accepts an array of errors. This can be a multi-dimensional array (in the case of multiple errors triggered for the same input or criteria) or a single dimensional array. The first dimension should be the name of the input that triggered the error. The second dimension, if necessary, is used to identify the type of error encountered.

<?php
class MyModule extends Module {

    public function __construct() {
        Loader::loadComponents($this, array("Input"));
    }

    ...

    public function upgrade($current_version) {
        // Ensure new version is greater than installed version
        if (version_compare($this->version, $current_version) < 0) {
            $this->Input->setErrors(array(
                'version' => array(
                    'invalid' => "Downgrades are not allowed."
                )
            ));
            return;
        }
    }
}
?>

Module Methods

Now that we've looked at some of the basic of creating a module, let's take a look at all of the required methods each module must implement: Module Methods.

Registrar Modules

As of Blesta 5.1 we introduced a new type of module, the registrar module. Registrar modules are utilized by the Domain Manager plugin, which include specific functions for domain management. Registrar modules implement all the functions as standard modules in addition to the Blesta\Core\Util\Modules\Registrar interface.

<?php
use Blesta\Core\Util\Modules\Registrar;

class Namesilo extends Module implements Registrar
{
	...
	
    public function checkTransferAvailability($domain, $module_row_id = null)
    {
		#
		# TODO: Check if the domain can be transferred
		#
    }

	public function checkAvailability($domain, $module_row_id = null) {
		#
		# TODO: Check if the domain is available
		#
	}

	public function getExpirationDate($domain, $format = 'Y-m-d H:i:s', $module_row_id = null) {
		#
		# TODO: Get the expiration date of the domain
		#
	}

	public function getTlds($module_row_id = null) {
		// Returns a list of the TLDs supported by the module
		return [
			'.com',
			'.net',
			'.org'
		];
	}
	...
}