Integrating Dokuwiki with Mantis

原文链接：http://www.mantisbt.org/wiki/doku.php/mantisbt:issue:7075:integration_with_dokuwikiIntegrating DokuWiki with Mantis

Disclaimer

This document describes the steps needed to integrate DokuWiki with Mantis. The method described here was originally tested with mantis version 1.1.0rc2 and dokuwiki rc2009-12-02, and should work with subsequent versions (modulo bugs). It may work with older versions of mantis provided you make the File Changes described below.

Integration Functionality

The integration between Mantis and DokuWiki so far achieves the following:

• Customises DokuWiki to honour Mantis authentication (i.e. single sign-on).
• Customises DokuWiki authorisation based on Mantis access levels (i.e. groups).
• Adds a Wiki link on the issue view simple/advanced pages to their corresponding Wiki issue page.
• Adds a Wiki menu option which maps to the corresponding project Wiki page, or general page in case of “All Projects”.
• Provides a way for Wiki pages to link to Mantis issues, e.g. 7075.
• Correctly manages HTTP Authentication. See ( http://www.mantisbt.org/bugs/view.php?id=12458).

Tips

Following are some tips that are of interest to Mantis / DokuWiki integration:

• To define a template for all Wiki pages within a namespace, create _template.txt in the namespace folder (namespace is located into the DOKUWIKI_ROOT/data/mantis directory). All pages created within this namespace will use the contents of the templates as a start point. This will affect the way the Wiki is structured. For example, if all issues within a project have a namespace, then they can all share one template, if there is a namespace per category, then there can be a template per category. The exact structure to be used should be configurable through Mantis configuration. However, the actual structure currently implemented is described in a tip later on in this section.

• The Wiki menu links in Mantis are equivalent to internal links for mantis:project: where:
  • mantis is the value of $g_wiki_root_namespace from config_inc.php (note that this is not configurable per-project, it is specifically looked up as a global)
  • project is the name of the current project, or nothing for ALL PROJECTS (ie. you get just mantis: which resolves to mantis:start if your start config setting is still the install default)

• The View Issue Details Wiki links in Mantis are equivalent to internal links for mantis:project:issue:NNNN where:
  • mantis and project are as described above for that Mantis project
  • issue is just that word “issue” and is the namespace for all issues in this project
  • NNNN is the numeric ID of the Mantis issue without leading zeros, and is a page, not a namespace

• How Wiki access levels are determined: The Mantis auth backend included below takes the namespace containing the object being accessed, extracts the 2nd component, and looks it up in a flat list of Mantis projects. If there is a match, that project’s access level is used, and if not, the global (ALL PROJECTS) access level is used. This means that mantis:project: and mantis:subproject: both get the access level of those Mantis projects, but mantis:project:subproject: gets the access level of project, AND playground:project: also gets the access level of project even though it has nothing to do with the $g_wiki_root_namespace used by the various Wiki links on the Mantis side. This allows you to implement any number of areas in your wiki that use Mantis projects for access control, with the restriction that all namespaces must be of the form top_level:mantis_project:* (ie. any namespace just under a top-level namespace which matches a Mantis project name will use that project access level for itself and its child namespaces).

• Another consequence of the simplistic code here is that it fails to adjust when $g_wiki_root_namespace is an empty string. In that case, the mapping function on the Mantis side omits the mantis: component in the Wiki namespace string, thus popping the flat project list up to the top level. But then the auth backend code below fails to find it, and every project Wiki link from Mantis takes you to a place that has only global access levels and your project access settings appear to be ignored. Of course, if you create a namespace just under any top level namespace with a Mantis project’s name, that will continue to work fine.

• Rename (if necessary) your projects and subprojects so that all their names are legal pagename identifiers. Otherwise the access level code will fail to map Wiki namespaces back into Mantis projects, and users will get global access levels instead of their project access level.

• DokuWiki will see groups for each combination of Mantis project and access level that exist for the current user. For example:

my_namespace:my_project:* @ALL                 0
my_namespace:my_project:* @MYPROJECT_VIEWER    1
my_namespace:my_project:* @MYPROJECT_DEVELOPER 8

Mantis Configuration

Add the following configuration items to config_inc.php and customize them for your installation. Copy the corresponding block fromconfig_defaults_inc.php if your mantis version is recent enough to have it. Note however that the list of valid wiki engines may be out of date; as of 1.2.6 the correct list is in the switch statement incore/wiki_api.php.

	#####################
	# Wiki Integration
	#####################
 
	# Wiki Integration Enabled?
	$g_wiki_enable = OFF;
 
	# Wiki Engine
	$g_wiki_engine = 'dokuwiki';
 
	# Wiki namespace to be used as root for all pages relating to this mantis installation.
	$g_wiki_root_namespace = 'mantis';
 
	# URL under which the wiki engine is hosted.  Must be on the same server.
	$g_wiki_engine_url = $t_protocol . '://' . $t_host . '/%wiki_engine%/';

Tip: If you are using different subdomains (eg. mantis lives at: bugs.example.com and doku lives at wiki.example.com) then you need to make the cookies accessible to both subdomains. In your mantisconfig_inc.php, set

        $g_wiki_engine_url = 'http://wiki.example.com/';
        $g_cookie_domain = '.example.com';   // So wiki and bugs can share cookie info

Don’t forget to change g_wiki_enable to ON later once you are done setting up DokuWiki.

DokuWiki Steps

Installation

Install DokuWiki and make sure it is working properly. This involves making sure that you can create pages, edit them, view them, etc.

Core Configuration

Add/modify the configuration values show below in your DokuWiki installation. Recent versions (eg. 2011-05-25a “Rincewind”) can have these indokuwiki\conf\local.protected.php, but older versions will have to put them in a file that may be overwritten later. Usedokuwiki\conf\local.php if you do not use the Admin interface’s config plugin (it will delete manually added lines!). Otherwise usedokuwiki\conf\dokuwiki.php where the default settings are located, but beware this will get overwritten during updates, so you will need to manually merge changes.

In fact a fix is needed to implement the two settings to the config page. (fix in form of plugin is already done herehttp://www.mantisbt.org/wiki/doku.php/mantisbt:issue:8253 but contains other changes)

#
# Add the following lines:
#
 
define( 'MANTIS_ROOT', 'c:/inetpub/wwwroot/mantisbt/' );  // file path to Mantis, must terminate with /
define( 'MANTIS_URL', 'http://localhost/mantisbt/' );     // url to Mantis, must terminate with /
 
#
# Once you have inc\auth\mantis.class.php created, modify the following configuration options to match the values below.
# With modern versions of dokuwiki, the bundled config plugin can set these values, otherwise uncomment them here.
#
 
# $conf['useacl']       = 1;                // Use Access Control Lists to restrict access?
# $conf['authtype']     = 'mantis';         // which authentication backend should be used
# $conf['defaultgroup'] = 'VIEWER';         // Default groups new Users are added to
# $conf['superuser'] = '@ADMINISTRATOR';    // allows mantis administrator to access dokuwiki admin area
 
#
# If selecting the mantis auth backend results in fatal errors from redeclaration of utf8 functions, uncomment this:
#
# require_once( MANTIS_ROOT . 'core.php' );

(utf8 redeclaration error reference: http://www.mantisbt.org/bugs/view.php?id=11769)

Authorisation Configuration

Add the following to the end of acl.auth.php:

*	@VIEWER		1
*	@REPORTER	2
*	@UPDATER	4
*	@DEVELOPER	8
*	@MANAGER	16
*	@ADMINISTRATOR	16

This will get you started. See the Tips section above for information about per-project group mappings.

Mantis Authentication Backend (Single Sign-On)

Create dokuwiki\inc\auth\mantis.class.php with the code below.

cando['external'] = true;
 
        $this->cando['logoff' ] = true; // module has a logoff method
    }
    
    /**
     * Authenticates the user using Mantis APIs.
     */
    function trustExternal($user,$pass,$sticky=false){
        global $USERINFO;
        global $conf;
 
        $ValidUser = false;
 
        // Manage HTTP authentication with Negotiate protocol enabled
        $user = auth_prepare_username($user);
	$pass = auth_prepare_password($pass);
        // This is necessary in all cases where Authorization HTTP header is always set
	if(auth_is_user_authenticated())
	{
	    $user='';
	}
 
        // Has a user name been provided?
        if ( !empty ( $user ) )
        {   
            // User name provided, so login via form in progress...
            // Are the specified user name and password valid?
            if ( auth_attempt_login ( $user, $pass, $sticky ) )
            {   
                // Credential accepted...
                $_SERVER['REMOTE_USER'] = $user; // Set the user name (makes things work...)
                $ValidUser = true; // Report success.
            }
            else
            {   
                // Invalid credentials              
                        if ( !$silent )
                {   
                    msg ( $lang [ 'badlogin' ], -1 );
                }
                
                $ValidUser = false;
            }
        }
        else
        {   
            // No user name provided.
            // Is a user already logged in?
            if ( auth_is_user_authenticated ( ) )
            {   
                // Yes, a user is logged in, so set the globals...
                // is it a media display or a page?
                if (isset($_REQUEST['media'])) {
                    //media
                    $t_project_name = explode( ':', getNS( getID("media",false) ) );
                } else {
                    // normal page
                    $t_project_name = explode( ':', getNS( getID() ) );
                }
                $t_project_id = project_get_id_by_name( $t_project_name[1] );
                $t_access_level = access_get_project_level( $t_project_id );
                $t_access_level_string = strtoupper( MantisEnum::getLabel( config_get( 'access_levels_enum_string' ),  $t_access_level ) ); // mantis 1.2.0rc
                // $t_access_level_string = strtoupper( get_enum_to_string( config_get( 'access_levels_enum_string' ),  $t_access_level ) ); 
                $t_access_level_string_ex = strtoupper( $t_project_name[1] ) . '_' . $t_access_level_string;
 
                $USERINFO['grps'] = array( $t_access_level_string, $t_access_level_string_ex );
                $USERINFO[ 'pass' ] = current_user_get_field ( 'password' );
                $USERINFO[ 'name' ] = current_user_get_field ( 'username' );
                $USERINFO[ 'mail' ] = current_user_get_field ( 'email' );
                
                $_SERVER[ 'REMOTE_USER' ] = $USERINFO[ 'name' ];
                $_SESSION[ $conf[ 'title' ]][ 'auth' ][ 'user' ] = $USERINFO[ 'name' ];
                $_SESSION[ $conf[ 'title' ]][ 'auth' ][ 'info' ] = $USERINFO;
                
                $ValidUser = true;
            }
            else
            {   
                $ValidUser = false;
            }
        }
        
        // Is there a valid user login?
        if ( true != $ValidUser )
        {   
            // No, so make sure any existing authentication is revoked.
            auth_logoff ( );
        }
        
        return $ValidUser;
    }
    /**
     * Logout from Mantis
     */
    function logOff(){
        auth_logout();
    }
 
    /**
     * Get user data
     * (needed for e-mail subscriptions)
     *
     * @author Martin Arends http://www.web-gestaltung.de
     */
    function getUserData($user) 
    {
      $data = array();
      
      $t_user_id = user_get_id_by_name( $user );
 
      if (isset($_REQUEST['media'])) {
          //media
          $t_project_name = explode( ':', getNS( getID("media",false) ) );
      } else {
          // normal page
          $t_project_name = explode( ':', getNS( getID() ) );
      }
 
      $t_project_id   = project_get_id_by_name( $t_project_name[1] );
      $t_access_level = access_get_project_level( $t_project_id, $t_user_id );
      $t_access_level_string    = strtoupper( MantisEnum::getLabel( config_get( 'access_levels_enum_string' ),  $t_access_level ) );
      $t_access_level_string_ex = strtoupper( $t_project_name[1] ) . '_' . $t_access_level_string;
      
      $data['name'] = $user;
      $data['grps'] = array( $t_access_level_string, $t_access_level_string_ex );
      $data['mail'] = user_get_email( $t_user_id );
      return $data;
    }
}
 

This codes already contains the following mods:

• Issue 8249 which makes it possible to set project related user rights.
• Support logging in/out from DokuWiki’s login page Issue 8277

If you want the original code, you can see the wiki history

Mantis Syntax Plug-in

This plugin is to be placed in dokuwiki\lib\plugins\mantis\syntax.php. Create themantis subdirectory underplugins if necessary.

 'Victor Boctor',
            'email'  => 'vboctor at users . sourceforge . net',
            'date'   => '2006-05-18',
            'name'   => 'Mantis Issues Plugin',
            'desc'   => 'Support References to Mantis Issues',
            'url'    => 'http://www.futureware.biz',
        );
    }
 
    /**
     * What kind of syntax are we?
     */
    function getType(){
        return 'substition';  # typo is intentional
    }
   
    /**
     * What about paragraphs?
     */
    function getPType(){
        return 'normal';
    }
 
    /**
     * Where to sort in?
     */ 
    function getSort(){
        return 156;
    }
 
 
    /**
     * Connect pattern to lexer
     */
    function connectTo($mode) {
        $this->Lexer->addSpecialPattern('~~Mantis:[0-9]+~~', $mode, 'plugin_mantis');
    }
 
 
    /**
     * Handle the match
     */
    function handle($match, $state, $pos, &$handler){
        $match = substr( $match, 9, -2 ); // strip "~~Mantis:" from start and "~~" from end
        return array( strtolower( $match ) );
    }
 
    /**
     * Create output
     */
    function render($format, &$renderer, $data) {
        if ( $format == 'xhtml' ) {
			$renderer->externallink( MANTIS_URL . 'view.php?id=' . $data[0], $data[0] );
            return true;
        }
        return false;
    }
}
 

Mantis File Changes for versions before 1.1.0rc2

If you use mantis 1.1.0rc2 (or later), the following steps are already done and you just need to set

	$g_wiki_enable = ON;

in your config_inc.php.

If you use a mantis version which is older than 1.1.0rc2 please check if any of the changes below still need to be done.

wiki_api.php

Create mantis/core/wiki_api.php with the following content:

wiki_dokuwiki_api.php

Create mantis/core/wiki_dokuwiki_api.php with the following content:

html_api.php

Add the following with the rest of the includes:

require_once( $t_core_dir . 'wiki_api.php' );

In the print_menu() function, add the following code after the code which prints the Docs button (the block with the “Project Documentation Page” comment).

# Project Wiki
if ( wiki_is_enabled() ) {
	$t_current_project = helper_get_current_project();
	$t_menu_options[] = '$t_current_project . '">' . lang_get( 'wiki' ) . '';
}

Add the following function:

# --------------------
# Print a button to create a wiki page
function html_button_wiki( $p_bug_id ) {
	if ( ON == config_get( 'wiki_enable' ) ) {
		if ( access_has_bug_level( config_get( 'update_bug_threshold' ), $p_bug_id ) ) {
			html_button( 'wiki.php',
						 lang_get_defaulted( 'Wiki' ),
						 array( 'id' => $p_bug_id, 'type' => 'issue' ),
						 'get' );
		}
	}
}

Update html_button() to the following implementation:

# --------------------
# Print an html button inside a form
function html_button ( $p_action, $p_button_text, $p_fields = null, $p_method = 'post' ) {
	$p_action		= urlencode( $p_action );
	$p_button_text	= string_attribute( $p_button_text );
	if ( null === $p_fields ) {
		$p_fields = array();
	}
	
	if ( strtolower( $p_method ) == 'get' ) {
		$t_method = 'get';
	} else {
		$t_method = 'post';
	}
 
	PRINT "
\"$t_method\" action=\"$p_action\">\n";
 
	foreach ( $p_fields as $key => $val ) {
		$key = string_attribute( $key );
		$val = string_attribute( $val );
 
		PRINT "	\"hidden\" name=\"$key\" value=\"$val\" />\n";
	}
 
	PRINT "	\"submit\" class=\"button\" value=\"$p_button_text\" />\n";
	PRINT "\n"
;
}

lang/strings_english.txt

Add the following at the end of the file but before the PHP end block (?>):

# wiki related strings
$s_wiki = 'Wiki';

wiki.php

Create wiki.php file in Mantis root folder:

bug_view_*_page.php

Add the following code before the tag that comes before the “” comment in both bug_view_page.php and bug_view_advanced_page.php.

class="small">
     print_bracket_link( 'wiki.php?id='.$f_bug_id, lang_get( 'wiki' ) ) ?>