4.2. Building a Plugin

⁠4.2. Building a Plugin

This section will act as a tutorial to build a new plugin, from the bare basics all the way up to advanced topics.

A general understanding of HTML, PHP and the concepts covered in the last section is assumed, as well as knowledge of how the event system works. Later topics in this section will require knowledge of database schemas and how they are used with MantisBT.

This walk-through will be working towards building a single end result: the Example Plugin. You may refer to the final code along the way (see Section 4.2.8, “Example Plugin source code”), although every part of it will be built up in steps throughout this section.

⁠4.2.1. Plugin Structure

This section will introduce the general concepts of plugin structure, and how to get a bare-bones plugin working with MantisBT. Not much will be mentioned yet on the topic of adding functionality to plugins, just how to get the development process rolling.

The backbone of every plugin is what MantisBT calls the basename, a succinct, and most importantly, unique name that identifies the plugin. It may not contain any spacing or special characters beyond the ASCII upper- and lowercase alphabet, numerals, and underscore. This is used to identify the plugin everywhere except for what the end-user sees. For our "Example" plugin, the basename we will use should be obvious enough: Example.

Every plugin must be contained in a single directory, named to match the plugin's basename. It must hold a PHP file with the plugin's code, also named after the basename, like so:

Example/
	Example.php

Note that for plugins that require a database schema to operate, the basename is also used to build the table names, using the MantisBT table prefixes and suffix (please refer to the Admin Guide's Configuration section for further information). If our Example plugin were to create a table named 'foo', assuming default values for prefixes and suffix in MantisBT configuration, the physical table name would be mantis_plugin_Example_foo_table.

Warning

These names must exactly match the plugin's base name. If the underlying file system is case-sensitive, example will not work.

The PHP file (Example.php in our case) must contain a concrete class deriving from the MantisPlugin base class; its name must be the plugin's basename with the Plugin suffix appended to it. For our purposes, the class' name will therefore be ExamplePlugin.

Because of how MantisPlugin declares the register() method as abstract, our plugin must implement that method before PHP will find it semantically valid. This method is meant for one simple purpose, and should never be used for any other task: setting the plugin's information properties including the plugin's name, description, version, and more. Please refer to Section 4.2.2, “Properties” below for details about available properties.

Once your plugin defines its class, implements the register() method, and sets at least the name and version properties, it is then considered a "complete" plugin, and can be loaded and installed within MantisBT's plugin manager. At this stage, our Example plugin, with all the possible plugin properties set at registration, looks like this:

Example/Example.php

<?php
class ExamplePlugin extends MantisPlugin {
    function register() {
        $this->name = 'Example Plugin';      # Proper name of plugin
        $this->description = 'Example Plugin from MantisBT Developers Guide';
                                             # Short description of the plugin
        $this->page = '';                    # Default plugin page

        $this->version = '2.0';              # Plugin version string
        $this->requires = array(             # Plugin dependencies
            'MantisCore' => '2.0',           # Should always depend on an appropriate
                                             # version of MantisBT
        );

        $this->author = 'MantisBT Team';     # Author/team name
        $this->contact = 'mantisbt-dev@lists.sourceforge.net';
                                             # Author/team e-mail address
        $this->url = 'https://mantisbt.org'; # Support webpage
    }
}

This alone will allow our Example plugin to be installed with MantisBT, and is the foundation of any plugin. More of the plugin development process will be continued in the next sections.