Create plugin¶

How to create new plugin¶

To create a plugin, you will need a bit of knowledge about PHP language programming and OOP (object-oriented programming). The plugin interface is simple and it does not require knowing how Bacularis works internally.

In the Bacularis project directory is a new directory named Plugins:

[main project dir]/protected/Web/Plugins/

If you have installed Bacularis using binary packages, the path can be the following:

/usr/share/bacularis/protected/Web/Plugins/

In the Plugins directory please create a new PHP file that will contain the plugin code. Exmaple:

/usr/share/bacularis/protected/Web/Plugins/ExamplePlugin.php

It will contain a PHP class that needs to implement an interface according to desired plugin type. So far the only available interface is the notification plugin interface IBacularisNotificationPlugin. The plugin class should extend the plugin base class BacularisWebPluginBase.

<?php

use Bacularis\Common\Modules\IBacularisNotificationPlugin;
use Bacularis\Web\Modules\BacularisWebPluginBase;

class ExamplePlugin extends BacularisWebPluginBase implements IBacularisNotificationPlugin
{
    /**
     * Get plugin name displayed on the web interface.
     *
     * @return string plugin name
     */
    public static function getName(): string
    {
        return 'My example plugin';
    }

    /**
     * Get plugin version.
     *
     * @return string plugin version
     */
    public static function getVersion(): string
    {
        return '1.0.0';
    }

    /**
     * Get plugin type.
     * For notification plugins it should be 'notification'.
     *
     * @return string plugin type
     */
    public static function getType(): string
    {
        return 'notification';
    }

    /**
     * Get plugin configuration parameters.
     *
     * return array plugin parameters
     */
    public static function getParameters(): array
    {
        return [
            ['name' => 'myparameter1', 'type' => 'string', 'default' => 'Def. Value 123', 'label' => 'My parameter 1'],
            ['name' => 'myparameter2long', 'type' => 'string_long', 'default' => "One\nTwo\nThree", 'label' => 'My multi-line string'],
            ['name' => 'mynumber', 'type' => 'integer', 'default' => 10, 'label' => 'My number'],
            ['name' => 'mybool', 'type' => 'boolean', 'default' => true, 'label' => 'Option A'],
            ['name' => 'mylist', 'type' => 'array', 'data' => ['one', 'two', 'three'], 'default' => 'three', 'label' => 'List A'],
            ['name' => 'mymultilist', 'type' => 'array_multiple', 'data' => ['one', 'two', 'three', 'four'], 'default' => ['one', 'four'], 'label' => 'Multi-select list 2']
        ];
    }

     /**
      * Main execute command.
      *
      * @param string $type message type (INFO, WARNING, ERROR)
      * @param string $category message category (Config, Action, Application, Security)
      * @param string $msg message body
      * @return bool true on success, false otherwise
      */
     public function execute(string $type, string $category, string $msg): bool
     {
         // get plugin settings
         $config = $this->getConfig();

         // get plugin parameter settings
         $param1 = $config['parameters']['myparameter1'];
         $param2 = $config['parameters']['myparameter2long'];

         // do action
         $result = false;
         if ($param1 === 'XYZ') {
             // run some action
             $result = $this->someImportantAction($param2, $msg);
             // ...etc.
         }
         return $result;
    }

    private function someImportantAction($param, $msg)
    {
        // do some action...
    }
}

Parameters¶

The defined in getParameters() method plugin parameters become automatically available on the web interface. They are ready to configure in auto-generated HTML form. After saving the form, there is created a new settings for the plugin.

The getParameters() method return array of parameters. Each parameter has defined type property that determines what type of HTML field the parameter will be represented. Below you can find descriptions for supported parameters by type.

string - it is a simple input text field. It supports the following properties:

name - short parameter name

default - default value

label - parameter name displayed on the web interface.

string_long - it is a texarea type text field. It is for storing multi-line parameter values. The line separator is the new line \n character. It supports the following properties:

name - short parameter name

default - default value

label - parameter name displayed on the web interface.

integer - it is a simple input text field. It supports the following properties:

name - short parameter name

default - default value

label - parameter name displayed on the web interface.

boolean - it is a checkbox type field. It supports the following properties:

name - short parameter name

default - default boolean value (true/false)

label - parameter name displayed on the web interface.

array - it is a drop down list type field with list on values to select. There is possible to select only one value. It supports the following properties:

name - short parameter name

default - default value

label - parameter name displayed on the web interface.

data - array of available value items

array_multiple - it is a drop down list type field with list on values to select. There is possible to select multiple values. It supports the following properties:

name - short parameter name

default - array of default values

label - parameter name displayed on the web interface.

data - array of available value items

The form for this example plugin looks like on the image below.