Mantis Plug-ins Requirements

• Author: Victor Boctor
• Status: In Progress

Mantis currently supports some extensibility features like custom fields, custom functions, custom constants, and custom strings. These has proven to be useful features that allowed Mantis users to tweak their own installations without having to change Mantis code base and hence making the upgrade experience much easier. The aim of Mantis Plug-ins support is to take this to the next level and enable users to do more powerful additions to Mantis and be able to make these publicly available to other users. Some of the Plug-ins will be distributed with Mantis and others will be available through Mantis website / bugtracker.

• Display Filters - Provides the ability to pre-process strings before they outputted to the web page. This can be used to implement features like the ones built-in Mantis to link to issues, issue notes and cvs web. This is where # + 123 is converted to a hyperlink to issue number 123.
• Group Action - Provides the ability to process a set of issues that have been selected from the View Issues page and based on user's input process such issues in a custom way.
• Issue Action - Ability to add an action button to the Issue View page, this is like the Monitor and Delete buttons.
• Reports - Users should be able to easily develop extra reports
• Extensions - Ability to implement a Mantis extension which cuts across all different areas of Mantis, extra fields, extra reporting, configuration, reports, menu options, etc.

• Ability to detect all plug-ins in the Mantis directory structure.
• From the manage plug-ins page, allow administrators (configurable threshold) to install / un-install a plug-in.
• Keep track of the installed plug-ins and make sure to provide them with the needed integration points.
• Extend the database scheme upgrade script to support modules.
• Detailed documentation about how to implement Mantis plug-ins.

• Name
• Publisher (e.g. Mantis Group)
• Publisher's Website (e.g. http://www.mantisbt.org)
• Description
• Status (stable, beta, etc?)
• Creation Date
• Mantis Minimum Version
• PHP Minimum Version
• PHP Maximum Version (?)
• RequiredModules (array)

We can add support for dependencies on DB type, DB version, web server, etc. However, ideally we should target to reduce such dependencies when possible.

mantis/
  admin/
  core/
  lang/
  modules/
    #modulename#/
      css/
        *.css
      images/
        logo.jpg (some plugins may have logos, file name is configurable)
      core/
      javascript/
        *.js
      doc/
        readme.html
      lang/
        strings_english.txt
      pages/
        (new pages - included from module_page.php based on module name and action)
      #modulename#_constants_inc.php
      #modulename#_defaults_inc.php
      #modulename#_inc.php

• #modulename#_inc.php - This file includes the following actions:
  • register in events
  • register necessary css based on current page.
  • register necessary javascript based on current page.
  • register menu options (menu, label_id, url)
  • register string_display_filter
  • register view issues links (e.g. csv, graphs, etc)
  • register view issue links (e.g. Wiki)
  • register the pages to include the plug-in (or ALL).
  • register the pages to exclude the plug-in (or empty array)
  • Support system exclude from pages (e.g. download attachment, module management page, etc)

• manage_plugins_threshold.

Note that the plugins are always applied to all projects. It is up to the plugin to scope down its functionality (if necessary).

The following pages will allow management of plug-ins and all their related details:

• manage_modules_page.php: This pages lists all the available modules, their minimum requirements, dependencies, etc. It also allows administrators to the install / uninstall the available plugins.
• manage_modules_add.php: The action page for installing modules.
• manage_modules_remove.php: The action page for uninstalling modules.
• module_page.php: This page takes in the plugin name, action as mandatory parameters. Depending on the “action” there can be other parameters. For example, module_page.php?module=last_visited&action=readme will view the readme of the plugin. The modules folder will have a .htaccess file that blocks direct access to files in the modules tree.

This is the standard APIs that are used in managing modules and allowing modules to interact with some standard Mantis functionality. In addition to these APIs, the plug-in implementation can use the rest of the APIs like strings_api, etc.

• module_event - trigger an event with the appropriate parameters.
• module_event_is_subscribed() - check before doing extra work for the event.
• module_include_all()
• module_include_lang()
• module_include_css()
• module_include_javascript()
• module_get_info( $p_module_name );
• module_install( $p_module_name );
• module_get_dependencies( $p_module_name )
• module_can_install( $p_module_name )
• module_get_depedents( $p_module )
• module_can_uninstall( $p_module )

Events are integration points that are similar to custom functions, however, they can be handled by one or more of the installed plug-ins. Typically, events take in parameters and do not have a return value.

• issue created
• issue updated
• issue deleted
• issue viewed
• issue cloned
• issue moved
• issue assigned
• issue re-assigned
• issue status changed
• issue attachment attached
• issue attachment deleted
• issue attachment preview
• user created by administrator
• user signed up
• user logged in for first time
• user pruned
• user deleted
• user disabled
• user authentication failed
• user logged in
• user updated
• user added to project
• user removed from project
• cronjob
• news added
• news updated
• news deleted
• note added
• note updated
• note deleted
• issue monitored
• issue unmonitored
• relationship_added
• relationship_deleted
• relationship_updated
• sponsorship_added
• sponsorship_updated
• sponsorship_deleted
• category_added
• category_updated
• category_deleted
• version_added
• version_updated
• version_deleted
• checkin
• project file attached
• project file deleted
• tag created
• tag updated
• tag deleted
• tag attached
• tag detached
• user heartbeat (can be used for users online)
• error (only for php errors, email errors, etc - i.e. system errors).

Plug-ins should be able to create new pages, however, they should also be able to enrich the content of some of the existing pages. This is through some pre-defined output hooks. Following are the initial set. In the future, it should be easy to add more of these hooks. In each of these pages there can be one or more places where content can be injected.

• issue view
• user view
• project page view
• my view page
• below menu (similar to the current location of “last visited”)

• notification plugins
  • email plugin
  • twitter pluggin
  • sms pluggin
• attachment preview
  • files (e.g. images, txt, flash)
  • urls (e.g. youtube)
• bbcode
• Issue Action Group (may need a bit of cleanup)
• Audit Log
• Issues Last Visited (as a plug-in rather than built-in feature)
• Email admin on errors
• Wiki integration?
• Email Reports: e.g. issues matching filter sent to <myself>
  • created by a user
  • can be public, hence, will trigger for each user
  • min access level
  • max access level
  • for each project?

• Detail the parameters sent to each of the events.
• How are the plug-ins going to be distributed.

This is still in progress, but you are free to contribute ideas.

• (DGtlRift) I would say that in “Information about a plugin” there should also be:
  • plugin version - could be used by a plugin manager to query if there is an updated plugin available from the plugin's website.
  • minimum mantis compatibility version - verify that this plugin will actually work with this version of mantis. I could picture as time goes on the new events, apis, etc could be introduced to mantis, which newer plugins would start using, but would be incompatible with legacy versions of mantis.
• (DGtlRift) I would also suggest that the “Information about a plugin” should be either in well known variables within #modulename#_constants_inc.php and if there are missing a mandatory constant, do not “load/register” the plugin.
  • I'm also thinking that it may be easier to use a hash table to store the constants in #modulename#_constants_inc.php plugins[“#modulename#”]→ver etc
  • Perhaps XML would be better for having this info
• (deboutv) In my plugin manager, I have chosen to provide Mantis plugin in pkg format. This file is the result of a zip and a serialize of an array ⇒ gzcompress( serialize( array ), 9 ); The array contains the following fields:

$t_pkg['plugin'] = 'string'; // The plugin name
$t_pkg['check'] = array(); // The array of requirements to be checked, eg: array( 'mantis' => array( 'min' => '1.0.5' ), 
                           //    'php' => array( 'min' => '4.0.0' ), 'plugins' => array( 'pluginmanager' => array( 'min' => '0.1.2' ) ) );
$t_pkg['files'] = array(); // The files of the plugin (base64 encoded), eg: array( 'plugins/bbcode/core.php' => base64_string, ... )
$t_pkg['remove'] = array(); // The list of files to remove.
$t_pkg['info'] = array(); // The plugin info (version, name, id...)
$t_pkg['info_pm'] = array(); // The plugin manager info

• (deboutv) Hacking Mantis with a plugin. We need to think about the security of the Mantis application and its data. Allowing plugins is dangerous because of the content of the plugin (it could pretend to be a BBCode interpreter but in reality it could be a BBCode interpreter and a spy). With a plugin (ie: code of third parties), you can read/write the SQL database, grant priviledges to the users…
• (DGtlRift) There should also be a description of how plugins themselves should generate events. This would allow additional optional functionality between plugins. EI: plugin doesSomething generates event pe_doesSomething_special so that plugin somethingElse which doesn't require plugin doesSomething, can optionally do something additional if that plugin is installed.
• (DGtlRift) Re: Distribution.
  • The most simple way is to just have a list of tar.gz compressed archives of each plugin. The admin would have to download them and uncompress them into the plugins directory. After that, they would be available for activation from with Admin for Managing plugins.
  • The next option would be to offer the ability to install via the admin interface, where Mantis would check against a web list of available plugins and download (to the server) and install the plugin (requiring Mantis to have write privileges) to the plugins directory. There are some serious security issues involved with this method, but it gives one unified interface for the admin.
  • Another option is to have all the plgins in RPM form - which would automate installation for the sysadmin.
• (DGtlRift) Should the plugins be globally “turned on” by the Mantis Admin or should each project have the ability to enable/disable installed plugins?

A first implementation has been written, you can find it here. This implementation does not respect the requirements. You can play with it here, create an account and go to the plugin page (take care this is a real bugtracker, not a demo version).

• Ability to detect add-ons.
• Allow configuration of the add-ons.

• No install/uninstall script (but plugin can be enable/disabled).
• Check the requirements.
• Directory structure not respected:

mantis/
  admin/
  core/
  lang/
  plugins_page.php
  plugins/
    plugin1/
    plugin2/
    plugin3/
      index.php
      info.php
      core/
        functions_api.php
      lang/
        strings_english.txt

• It is in charge to load the strings_*.txt file according to the current language
• It is in charge to allow configuration of the plugin according to the access_level. The configuration page is located into index.php
• It checks new release of the plugin (optional).