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.
Plugin names must be unique
A user will not be able to install two plugins with the same name, so try to use descriptive and non-generic terms for your plugin name.
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:
- config.json (for version 3.1+)
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/.
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 in conjunction with the config.json file.
If your plugin requires any code to execute when installed, place that logic in your plugin's install() method.
Need access to the database?
See how you can use the Record component to manipulate the database in the Database Access section of this manual.
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 any remaining remnants of the plugin.
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. The $plugin_id is the ID of the plugin being upgraded.
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 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.
1 != 0
Data validation is an important part of logic, and user friendly application design. Be sure to check out the Error Checking section of this manual for a full explanation on error handling.
Branding The Plugin
For version 3.1+ simply create a config.json file and include it in the constructor of your plugin.
For version 3.0, you must define all of the branding details through methods.
All that any plugin truly requires is branding. These options come from three methods: getName(), getVersion(), getAuthors().
The getAuthors() method requires a multi-dimensional array, so you can specify multiple authors if needed.
Lastly, 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.
Use the Language library to help internationalize your plugin. Just create a language directory in your plugin, then a directory for each language (i.e. /plugins/my_plugin/language/en_us/) and place your language files in there. See Translating Blesta for how to load, format, and use language definitions.
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 methods.
By default the index() method is called. You can link to other controller and actions from your views using the following URL format:
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.
By register actions, a plugin makes itself available in the interface in certain areas. See Plugin Actions for how to register actions.
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.
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.