Initial Setup

There are a few steps the MantisBT team requires of contributers and developers when accepting code submissions. The user needs to configure Git to know their full name (not a screen name) and an email address they can be contacted at (not a throwaway address).

To set up your name and email address with Git, run the following commands, substituting your own real name and email address:

$ git config --global user.name "John Smith"
$ git config --global user.email "jsmith@mantisbt.org"
		

Optionally, you may want to also configure Git to use terminal colors when displaying file diffs and other information, and you may want to alias certain Git actions to shorter phrases for less typing:

$ git config --global color.diff "auto"
$ git config --global color.status "auto"
$ git config --global color.branch "auto"

$ git config --global alias.st "status"
$ git config --global alias.di "diff"
$ git config --global alias.co "checkout"
$ git config --global alias.ci "commit"
		

Cloning the Repository

The primary repository for MantisBT is hosted and available in multiple methods depending on user status and intentions. For most contributers, the public clone URL is git://mantisbt.org/mantisbt.git. To clone the repository, perform the following from your target workspace:

$ git clone git://mantisbt.org/mantisbt.git
		

If you are a member of the MantisBT development team with write access to the repository, there is a special clone URL that uses your SSH key to handle access permissions and allow you read and write access. Note: This action will fail if you do not have developer access or do not have your public SSH key set up correctly.

$ git clone git@mantisbt.org:mantisbt.git
		

After performing the cloning operation, you should end up with a new directory in your workspace, mantisbt/. By default, it will only track code from the primary remote branch, master, which is the latest development version of MantisBT. For contributers planning to work with stable release branches, or other development branches, you will need to set up local tracking branches in your repository. The following commands will set up a tracking branch for the current stable branch, master-1.1.x.

$ git checkout -b master-1.1.x origin/master-1.1.x
		

Maintaining Tracking Branches

In order to keep your local repository up to date with the official, there are a few simple commands needed for any tracking branches that you may have, including master and master-1.1.x.

First, you'll need to got the latest information from the remote repo:

$ git fetch origin
		

Then for each tracking branch you have, enter the following commands:

$ git checkout master
$ git rebase origin/master
		

Alternatively, you map combine the above steps into a single command for each remote tracking branch:

$ git checkout master
$ git pull --rebase
		

Preparing Feature Branches

Submitting Changes

When you have a set of changes to MantisBT that you would like to contribute to the project, there are two preferred methods of making those changes available for project developers to find, retrieve, test, and commit. The simplest method uses Git to generate a specially-formatted patch, and the other uses a public repository to host changes that developers can pull from.

Formatted patches are very similar to file diffs generated by other tools or source control systems, but contain far more information, including your name and email address, and for every commit in the set, the commit's timestamp, message, author, and more. This formatted patch allows anyone to import the enclosed changesets directly into Git, where all of the commit information is preserved.

Using a public repository to host your changes is marginally more complicated than submitting a formatted patch, but is more versatile. It allows you to keep your changesets up to date with the offiicial development repository, and it lets anyone stay up to date with your repository, without needing to constantly upload and download new formatted patches whenever you change anything. There is no need for a special server, as free hosting for public repositories can be found on many sites, such as MantisForge.org, GitHub, or Gitorious.

$ git format-patch --binary --stdout origin/master..HEAD > feature_branch.patch
			

$ git am --signoff feature_branch.patch
			

$ git remote add public git@mantisbt.org:contrib.git
$ git push public feature
			

$ git request-pull origin/master git://mantisbt.org/contrib.git feature
			

$ git remote add feature git://mantisbt.org/contrib.git
$ git checkout -b feature feature/feature
			

Schema Definition

TODO: Discuss the ADODB datadict formats and the format MantisBT expects for schema deinitions.

Installation / Upgrade Process

TODO: Discuss how MantisBT handles a database installation / upgrade, including the use of the config system and schema definitions.

General Concepts

The event system in MantisBT uses the concept of signals and hooked events to drive dynamic actions. Functions, or plugin methods, can be hooked during runtime to various defined events, which can be signalled at any point to initiate execution of hooked functions.

Events are defined at runtime by name and event type (covered in the next section). Depending on the event type, signal parameters and return values from hooked functions will be handled in different ways to make certain types of common communication simplified.

API Usage

This is a general overview of the event API. For more detailed analysis, you may reference the file core/event_api.php in the codebase.

Declaring Events

When declaring events, the only information needed is the event name and event type. Events can be declared alone using the form:

event_declare( $name, $type=EVENT_TYPE_DEFAULT );

or they can be declared in groups using key/value pairs of name => type relations, stored in a single array, such as:

$events = array(
	$name_1 => $type_1,
	$name_2 => $type_2,
	...
	);

event_declare_many( $events );
			

Hooking Events

Hooking events requires knowing the name of an already-declared event, and the name of the callback function (and possibly associated plugin) that will be hooked to the event. If hooking only a function, it must be declared in the global namespace.

event_hook( $event_name, $callback, [$plugin] );

In order to hook many functions at once, using key/value pairs of name => callback relations, in a single array:

$events = array(
	$event_1 => $callback_1,
	$event_2 => $callback_2,
	...
	);

event_hook( $events, [$plugin] );
			

Signalling Events

When signalling events, the event type of the target event must be kept in mind when handling event parameters and return values. The general format for signalling an event uses the following structure:

$value = event_signal( $event_name, [ array( $param, ... ), [ array( $static_param, ... ) ] ] );

Each type of event (and individual events themselves) will use different combinations of parameters and return values, so use of the Event Reference is reccommended for determining the unique needs of each event when signalling and hooking them.

Event Types

There are five standard event types currently defined in MantisBT. Each type is a generalization of a certain "class" of solution to the problems that the event system is designed to solve. Each type allows for simplifying a different set of communication needs between event signals and hooked callback functions.

Each type of event (and individual events themselves) will use different combinations of parameters and return values, so use of the Event Reference is reccommended for determining the unique needs of each event when signalling and hooking them.

EVENT_TYPE_EXECUTE

This is the simplest event type, meant for initiating basic hook execution without needing to communicate more than a set of immutable parameters to the event, and expecting no return of data.

These events only use the first parameter array, and return values from hooked functions are ignored. Example usage:

event_signal( $event_name, [ array( $param, ... ) ] );

EVENT_TYPE_OUTPUT

This event type allows for simple output and execution from hooked events. A single set of immutable parameters are sent to each callback, and the return value is inlined as output. This event is generally used for an event with a specific purpose of adding content or markup to the page.

These events only use the first parameter array, and return values from hooked functions are immediatly sent to the output buffer via 'echo'. Example usage:

event_signal( $event_name, [ array( $param, ... ) ] );

EVENT_TYPE_CHAIN

This event type is designed to allow plugins to succesively alter the parameters given to them, such that the end result returned to the caller is a mutated version of the original parameters. This is very useful for such things as output markup parsers.

The first set of parameters to the event are sent to the first hooked callback, which is then expected to alter the parameters and return the new values, which are then sent to the next callback to modify, and this continues for all callbacks. The return value from the last callback is then returned to the event signaller.

This type allows events to optionally make use of the second parameter set, which are sent to every callback in the series, but should not be returned by each callback. This allows the signalling function to send extra, immutable information to every callback in the chain. Example usage:

$value = event_signal( $event_name, $param, [ array( $static_param, ... ) ] );

EVENT_TYPE_FIRST

The design of this event type allows for multiple hooked callbacks to 'compete' for the event signal, based on priority and execution order. The first callback that can satisfy the needs of the signal is the last callback executed for the event, and its return value is the only one sent to the event caller. This is very useful for topics like user authentication.

These events only use the first parameter array, and the first non-null return value from a hook function is returned to the caller. Subsequent callbacks are never executed. Example usage:

$value = event_signal( $event_name, [ array( $param, ... ) ] );

EVENT_TYPE_DEFAULT

This is the fallback event type, in which the return values from all hooked callbacks are stored in a special array structure. This allows the event caller to gather data separately from all events.

These events only use the first parameter array, and return values from hooked functions are returned in a multi-dimensional array keyed by plugin name and hooked function name. Example usage:

$values = event_signal( $event_name, [ array( $param, ... ) ] );

General Concepts

The plugin system for MantisBT is designed as a lightweight extension to the standard MantisBT API, allowing for simple and flexible addition of new features and customization of core operations. It takes advantage ofthe new Event System to offer developers rapid creation and testing of extensions, without the need to modify core files.

Plugins are defined as implementations, or subclasses, of the MantisPlugin class as defined in core/classes/MantisPlugin.php. Each plugin may define information about itself, as well as a list of conflicts and dependencies upon other plugins. There are many methods defined in the MantisPlugin class that may be used as convenient places to define extra behaviors, such as configuration options, event declarations, event hooks, errors, and database schemas. Outside a plugin's core class, there is a standard method of handling language strings, content pages, and files.

At page load, the core MantisBT API will find and process any conforming plugins. Plugins will be checked for minimal information, such as its name, version, and dependencies. Plugins that meet requirements will then be initialized. At this point, MantisBT will interact with the plugins when appropriate.

The plugin system includes a special set of API functions that provide convenience wrappers around the more useful MantisBT API calls, including configuration, language strings, and link generation. This API allows plugins to use core API's in "sandboxed" fashions to aid interoperation with other plugins, and simplification of common functionality.

Building a Plugin

This section will act as a walkthrough of how to build a plugin, from the bare basics all the way up to advanced topics. A general understanding of 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 walkthrough will be working towards building a single end result: the "Example" plugin as listed in the next section. You may refer to the final source code along the way, although every part of it will be built up in steps throughout this section.

Example/
	Example.php
				

register()

abstract

register()

Example/Example.php

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

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

        $this->author = '';         # Author/team name
        $this->contact = '';        # Author/team e-mail address
        $this->url = '';            # Support webpage
    }
}
				

Example Plugin Source Listing

The code in this section, for the Example plugin, is available for use, modification, and redistribution without any restrictions and without any warranty or implied warranties. You may use this code however you want.

API Usage

This is a general overview of the plugin API. For more detailed analysis, you may reference the file core/plugin_api.php in the codebase.

Introduction

In this chapter, an attempt will be made to list all events used (or planned for later use) in the MantisBT event system. Each listed event will include details for the event type, when the event is called, and the expected parameters and return values for event callbacks.

Here we show an example event definition. For each event, the event identifier will be listed along with the event type in parentheses. Below that should be a concise but thorough description of how the event is called and how to use it. Following that should be a list of event parameters (if any), as well as the expected return value (if any).

EVENT_EXAMPLE (Default)

This is an example event description.

Parameters

• <Type>: Description of parameter one

• <Type>: Description of parameter two

Return Value

• <Type>: Description of return value

Plugin System

These events are initiated by the plugin system itself to allow certain functionality to simplify plugin development.

EVENT_PLUGIN_INIT (Execute)

This event is triggered by the MantisBT plugin system after all registered and enabled plugins have been initialized (their init() functions have been called). This event should always be the first event triggered for any page load. No parameters are passed to hooked functions, and no return values are expected.

This event is the first point in page execution where all registered plugins are guaranteed to be enabled (assuming dependencies and such are met). At any point before this event, any or all plugins may not yet be loaded.

Suggested uses for the event include:

• Checking for plugins that aren't require for normal usage.

• Interacting with other plugins outside the context of pages or events.

Logging

The following event is used to submit a logging message to the plugins. The event gets the logging string as a parameter. Logging plugins can capture extra context information like timestamp, current logged in user, etc.

EVENT_LOG (Execute)

This event is triggered by MantisBT to log a message. The contents of the message should be hyper linked based on the following rules: #123 means issue 123, ~123 means issue note 123, @P123 means project 123, @U123 means user 123. expected.

Output Modifiers

Bug / Bugnote Actions

Git References

• Git Official Documentation

• Git Tutorial

• Everyday Git With 20 Commands

• Git Crash Course for SVN Users

• Git From the Bottom Up

• GitCasts