Plugins

Plugins are "plug-and-play" applications that extend the functionality of Blesta. This document explains how to design and develop plugins, and highlights the roles plugins may assume when rendering data.

• The Standalone Plugins section describes how to build plugins that add additional pages in Blesta.
• The Widgets section explains how to build mini applications using plugins.
• The Extending the API section explains how to use plugins to add additional functionality to the Blesta API.
• The ACL section describes how to integrate a plugin into Blesta's Access Control List.
• The Plugin Events section describes how to trigger a plugin to execute during special events.
• The Email section explains how to manage and send email through a plugin.
• The Database Access section explains how to build and execute queries on the database.

Getting Started with Plugins

Plugins follow the same MVC design pattern that Blesta adheres to. The plugin system is provided as a feature of the minPHP framework, Blesta simply defines the naming convention. For the purpose of this manual, the plugin name we'll refer to is my_plugin. Your plugin name will, of course, differ.

File Structure

Plugins are fully contained within their named plugin directory and placed in the /plugins/ directory. Below is the minimum required file structure for a plugin:

• /plugins/
  • my_plugin/
    • controllers/
    • models/
    • views/
    • language/
    • my_plugin_controller.php
    • my_plugin_model.php
    • my_plugin_plugin.php

my_plugin_controller.php is the plugin's parent controller. This controller can be used to add supporting methods for the other controllers to inherit. Similarly, my_plugin_model.php is the plugin's parent model and can be used to add supporting methods for the other models to inherit.

Because plugins inherit from the application stack their views default to the view directory defined for application. For this reason, you should always declare the view directory for the views within your plugin. The example below requires that you place all views (.pdt files) into /plugins/my_plugin/views/default/.

<?php
class MyPluginController extends AppController {
    public function preAction() {
        parent::preAction();
 
        // Override default view directory
        $this->view->view = "default";
        $this->structure->view = "default";
    }
}
?>

Finally, my_plugin_plugin.php is a special class that must extend the Plugin class of /components/plugins/lib/plugin.php. This class is used for installing, upgrading, uninstalling, and branding the plugin.

Install Logic

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

<?php
class MyPluginPlugin {

    ...

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

Uninstall Logic

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

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

<?php 
class MyPluginPlugin { 

    ... 

    public function uninstall($plugin_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 plugin's upgrade() method.

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

<?php
class MyPluginPlugin {

    ...

    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 plugin and set any errors you encounter using Input::setErrors(). The setErrors() method accepts an array of errors. This can be a multiple 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 MyPluginPlugin {

    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;
        }
    }
}
?>