Page History

Plugins can do just about anything. Create custom cron jobstasks, listen for events, create pages, create widgets, extend the API, etc., etc. If it's not a Module or a Payment Gateway, it's a plugin. So let's dig in.

Getting Started

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_pluginplgn. Your plugin name will, of course, differ.

...

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_pluginplgn/
    • controllers/
    • models/
    • views/
    • language/
    • my_pluginplgn_controller.php
    • my_pluginplgn_model.php
    • my_pluginplgn_plugin.php
    • config.json (for version 3.1+)

my_pluginplgn_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_pluginplgn_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_pluginplgn/views/default/.

<?php
class MyPluginControllerMyPlgnController extends AppController {
    public function preAction() {
        // Set the view directory to the default core view directory so that AppController preAction code uses the appropriate
        // directory for the structure file
        $this->structure->setDefaultView(APPDIR);
        parent::preAction();
 
        // Override default view directory
 with that of     $this->view->view = "default";the plugin 
        $this->structure>view->view = "default";
    }
}
?>

Finally, my_pluginplgn_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 in conjunction with the config.json file.

Install Logic

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

<?php
class MyPluginPluginMyPlgnPlugin extends Plugin {

    ...

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

...

<?php 
class MyPluginPluginMyPlgnPlugin extends Plugin { 

    ... 

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

...

The $current_version is the version currently installed. That is, the version that will be upgraded from. The $plugin_id is the ID of the plugin being upgraded.

<?php
class MyPluginPluginMyPlgnPlugin extends Plugin {

    ...

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

}
?>

...

...

<?php
class MyPluginPluginMyPlgnPlugin extends Plugin {

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

    ...

    public function upgrade($current_version, $plugin_id) {
        // 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;
        }
    }
}
?>

Branding The Plugin

For version 3.1+ simply create a config.json file and include it in the constructor of your plugin.

{
    "version": "1.0.0",
    "name": "My Plugin Name",
    "description": "A plugin like no other!",
    "authors": [
        {
            "name": "Phillips Data, Inc.",
            "url": "http://www.blesta.com"
        }
    ]
}

<?php
class MyPlgnPlugin extends Plugin {
    public function __construct() {
        $this->loadConfig(dirname(__FILE__) . DS . "config.json");
    }
}
?>

For version 3.0, you must define all of the branding details through methods.

<?php
class 

MyPlgnPlugin extends Plugin {

    ...

    public function getName() {
		return "MyPlugin";
    }

	public function getVersion() {
		return "1.0.0";
	}

	public function getAuthors() {
		return 

[
			

[
				'name' => "MyCompany",
				'url' => "http://www.mycompanyplugindevelopment.com"
			

]
		

];
	}
}
?>

<?php
class MyPlgnPlugin extends Plugin {
    ...
    public function getLogo() {
        return "views" . DS . "default" . DS . "images" . DS . "some_other_logo.png";
    }
}
?>

Managing a Plugin

If your plugin requires certain configurable options, you can create a management link viewable to staff members that have access to installed plugins. To do so, all you need to do is create an AdminManagePlugin controller. This is a special controller that is initialized by Blesta internally, so all views must be returned (as strings) from the requested action methodsLastly, each plugin needs a logo. By default these are loaded from /plugins/my_plugin/views/default/images/logo.png. You can override the location of the logo file by implementing the getLogo() method in your plugin.

<?php
class MyPluginPlugin extends Plugin {

    ...AdminManagePlugin extends AppController {

    /**
     * Performs necessary initialization
     */
    private function init()
    {
        // Set the view to render for all actions under this controller
        $this->view->setView(null, 'MyPlgn.default');
    }

    public function getLogoindex() {
        $this->init();

		$var1 = "hello";
		$var2 = "world";
		return "views" . DS . "default" . DS . "images" . DS . "some_other_logo.png";
    }
}
?>$this->partial("admin_manage_plugin", compact("var1", "var2"));
    }

	public function foo() {
        $this->init();

		return $this->partial("admin_manage_plugin_foo");
	}
}
?>

By default the index() method is called. You can link to other controller and actions from your views using the following URL format:

<a href="<?php echo $this->Html->safe($this->base_uri . "settings/company/plugins/manage/" . $this->Html->_($plugin_id, true) . "/?controller=admin_manage_plugin&action=foo");?>">Link to other action</a>

The above link would render the AdminManagePlugin::foo() method.

Making It Interactive

So far all we've see is how to build a plugin that can be installed, uninstalled, upgraded, and managed, but that's the just tip of the iceberg. As we discussed earlier, plugins can do so much more.

Actions

By register actions, a plugin makes itself available in the interface in certain areas. See Plugin Actions for how to register actions.

Events

Some plugins need to be executed when certain events occur outside of the plugin's control. This is accomplished by registering events. See Plugin Events for how to register events.

Cron Jobs

Plugins that need to perform certain tasks automatically at either set intervals are certain times of the day can register cron tasks. See Plugin Cron Tasks for how to register cron tasks.