plugin_api.php

<?php
# Mantis - a php based bugtracking system

# Copyright (C) 2000 - 2002  Kenzaburo Ito - kenito@300baud.org
# Copyright (C) 2002 - 2007  Mantis Team   - mantisbt-dev@lists.sourceforge.

# Mantis is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 2 of the License, or
# (at your option) any later version.
#
# Mantis is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with Mantis.  If not, see <http://www.gnu.org/licenses/>.

$t_class_path = config_get_global( 'class_path' );
require_once( $t_class_path . 'MantisPlugin.class.php' );

/**
 * Plugin API
 * Handles the initialisation, management, and execution of plugins.
 *
 * @package PluginAPI
 */

##### Cache variables #####

$g_plugin_cache = array();
$g_plugin_current = array();

##### Public API #####

/**
 * Get the currently executing plugin's basename.
 * @return string Plugin basename, or null if no current plugin
 */
function plugin_get_current() {
	global $g_plugin_current;
	return ( isset( $g_plugin_current[0] ) ? $g_plugin_current[0] : null );
}

/**
 * Add the current plugin to the stack
 * @param string Plugin basename
 */
function plugin_push_current( $p_basename ) {
	global $g_plugin_current;
	array_unshift( $g_plugin_current, $p_basename );
}

/**
 * Remove the current plugin from the stack
 * @return string Plugin basename, or null if no current plugin
 */
function plugin_pop_current() {
	global $g_plugin_current;
	return ( isset( $g_plugin_current[0] ) ? array_shift( $g_plugin_current ) : null );
}

/**
 * Get the URL to the plugin wrapper page.
 * @param string Page name
 * @param string Plugin basename (defaults to current plugin)
 */
function plugin_page( $p_page, $p_redirect=false, $p_basename=null ) {
	if ( is_null( $p_basename ) ) {
		$t_current = plugin_get_current();
	} else {
		$t_current = $p_basename;
	}
	if ( $p_redirect ) {
		return 'plugin.php?page=' . $t_current . '/' . $p_page;
	} else {
		return helper_mantis_url( 'plugin.php?page=' . $t_current . '/' . $p_page );
	}
}

/**
 * Given a base table name for a plugin, add appropriate prefix and suffix.
 * Convenience for plugin schema definitions.
 * @param string Table name
 * @param string Plugin basename (defaults to current plugin)
 * @return string Full table name
 */
function plugin_table( $p_name, $p_basename=null ) {
	if ( is_null( $p_basename ) ) {
		$t_current = plugin_get_current();
	} else {
		$t_current = $p_basename;
	}
	return config_get_global( 'db_table_prefix' ) .
		'_plugin_' . $t_current . '_' . $p_name .
		config_get_global( 'db_table_suffix' );
}

/**
 * Get a plugin configuration option.
 * @param string Configuration option name
 * @param multi Default option value
 */
function plugin_config_get( $p_option, $p_default=null, $p_global=false ) {
	$t_basename = plugin_get_current();
	$t_full_option = 'plugin_' . $t_basename . '_' . $p_option;

	if ( $p_global ) {
		return config_get_global( $t_full_option, $p_default );
	} else {
		return config_get( $t_full_option, $p_default );
	}
}

/**
 * Set a plugin configuration option in the database.
 * @param string Configuration option name
 * @param multi Option value
 * @param int User ID
 * @param int Project ID
 * @param int Access threshold
 */
function plugin_config_set( $p_option, $p_value, $p_user=NO_USER, $p_project=ALL_PROJECTS, $p_access=ADMINISTRATOR ) {
	$t_basename = plugin_get_current();
	$t_full_option = 'plugin_' . $t_basename . '_' . $p_option;

	config_set( $t_full_option, $p_value, $p_user, $p_project, $p_access );
}

/**
 * Set plugin default values to global values without overriding anything.
 * @param array Array of configuration option name/value pairs.
 */
function plugin_config_defaults( $p_options ) {
	if ( ! is_array( $p_options ) ) {
		return;
	}

	$t_basename = plugin_get_current();
	$t_option_base = 'plugin_' . $t_basename . '_';

	foreach( $p_options as $t_option => $t_value ) {
		$t_full_option = $t_option_base . $t_option;

		config_set_global( $t_full_option, $t_value, false );
	}
}

/**
 * Hook a plugin's callback function to an event.
 * @param string Event name
 * @param string Callback function
 */
function plugin_event_hook( $p_name, $p_callback ) {
	$t_basename = plugin_get_current();
	event_hook( $p_name, $p_callback, $t_basename );
}

/**
 * Hook multiple plugin callbacks at once.
 * @param array Array of event name/callback key/value pairs
 */
function plugin_event_hook_many( $p_hooks ) {
	if ( ! is_array( $p_hooks ) ) {
		return;
	}

	$t_basename = plugin_get_current();

	foreach( $p_hooks as $t_event => $t_callbacks ) {
		if ( !is_array( $t_callbacks ) ) {
			event_hook( $t_event, $t_callbacks, $t_basename );
			continue;
		}

		foreach( $t_callbacks as $t_callback ) {
			event_hook( $t_event, $t_callback, $t_basename );
		}
	}
}

### Plugin Management Helpers

/**
 * Converts a version string to an array, using some punctuation and
 * number/lettor boundaries as splitting points.
 * @param string Version string
 * @return array Version array
 */
function plugin_version_array( $p_version ) {
	$t_version = preg_replace( '/([a-zA-Z]+)([0-9]+)/', '\1.\2', $p_version );
	$t_version = preg_replace( '/([0-9]+)([a-zA-Z]+)/', '\1.\2', $p_version );

	$t_search = array(
		',',
		'-',
		'_',
	);

	$t_replace = array(
		'.',
		'.',
		'.',
	);

	$t_version = explode( '.', str_replace( $t_search, $t_replace, $t_version ) );

	return $t_version;
}

/**
 * Checks two version arrays sequentially for minimum or maximum version dependencies.
 * @param array Version array to check
 * @param array Version array required
 * @param boolean Minimum (false) or maximum (true) version check
 */
function plugin_version_check( $p_version1, $p_version2, $p_maximum = false ) {
	while ( count( $p_version1 ) > 0 && count ( $p_version2 ) > 0 ) {
		# Grab the next version bits
		$t_version1 = array_shift( $p_version1 );
		$t_version2 = array_shift( $p_version2 );

		# Convert to integers if possible
		if ( is_numeric( $t_version1 ) ) {
			$t_version1 = (int) $t_version1;
		}
		if ( is_numeric( $t_version2 ) ) {
			$t_version2 = (int) $t_version2;
		}

		# Check for immediate version differences
		if ( $p_maximum ) {
			if ( $t_version1 < $t_version2 ){
				return 1;
			} elseif ( $t_version1 > $t_version2 ) {
				return -1;
			}
		} else {
			if ( $t_version1 > $t_version2 ) {
				return 1;
			} elseif ( $t_version1 < $t_version2 ) {
				return -1;
			}
		}
	}

	# Handle unmatched version bits
	if ( $p_maximum ) {
		if ( count( $p_version2 ) > 0 ) {
			return 1;
		}
	} else {
		if ( count( $p_version1 ) > 0 ) {
			return 1;
		} elseif( count( $p_version1 ) == 0 && count( $p_version2 ) == 0 ) {
			return 1;
		}
	}

	# No more comparisons
	return -1;
}

/**
 * Check a plugin dependency given a basename and required version.
 * Versions are checked using PHP's library version_compare routine
 * and allows both minimum and maximum version requirements.
 * Returns 1 if plugin dependency is met, 0 if dependency not met,
 * or -1 if dependency is the wrong version.
 * @param string Plugin basename
 * @param string Required version
 * @return integer Plugin dependency status
 */
function plugin_dependency( $p_basename, $p_required ) {
	global $g_plugin_cache;

	# check for registered dependency
	if ( isset( $g_plugin_cache[$p_basename] ) ) {
		$t_required = trim( $p_required );
		$t_maximum =  false;

		# check for a less-than version requirement
		$t_ltpos = strpos( $t_required, '<' );
		if ( $t_ltpos !== false ) {
			$t_required = substr( $t_required, $t_ltpos + 1 );
			$t_maximum = true;
		}

		$t_version1 = plugin_version_array( $g_plugin_cache[$p_basename]->version );
		$t_version2 = plugin_version_array( $t_required );

		return plugin_version_check( $t_version1, $t_version2, $t_maximum );
	} else {
		return 0;
	}
}

### Plugin management functions

/**
 * Determine if a given plugin is installed.
 * @param string Plugin basename
 * @retrun boolean True if plugin is installed
 */
function plugin_is_installed( $p_basename ) {
	$t_plugin_table	= db_get_table( 'mantis_plugin_table' );
	$c_basename 	= db_prepare_string( $p_basename );

	$t_query = "SELECT COUNT(*) FROM $t_plugin_table WHERE basename=" . db_param(0);
	$t_result = db_query_bound( $t_query, array( $c_basename ) );
	return ( 0 < db_result( $t_result ) );
}

/**
 * Install a plugin to the database.
 * @param string Plugin basename
 */
function plugin_install( $p_plugin ) {
	access_ensure_global_level( config_get_global( 'manage_plugin_threshold' ) );

	if ( plugin_is_installed( $p_plugin->basename ) ) {
		trigger_error( ERROR_PLUGIN_ALREADY_INSTALLED, WARNING );
		return null;
	}

	plugin_push_current( $p_plugin->basename );

	if ( ! $p_plugin->install() ) {
		plugin_pop_current( $p_basename );
		return null;
	}

	$t_plugin_table	= db_get_table( 'mantis_plugin_table' );

	$c_basename = db_prepare_string( $p_plugin->basename );

	$t_query = "INSERT INTO $t_plugin_table ( basename, enabled )
				VALUES ( ".db_param(0).", '1' )";
	db_query_bound( $t_query, array( $c_basename ) );

	if ( false === ( plugin_config_get( 'schema', false ) ) ) {
		plugin_config_set( 'schema', -1 );
	}

	plugin_upgrade( $p_plugin );

	plugin_pop_current();
}

/**
 * Determine if an installed plugin needs to upgrade its schema.
 * @param string Plugin basename
 * @return boolean True if plugin needs schema ugrades.
 */
function plugin_needs_upgrade( $p_plugin ) {
	plugin_push_current( $p_plugin->basename );

	$t_plugin_schema = $p_plugin->schema();
	if ( is_null( $t_plugin_schema ) ) {
		return false;
	}

	$t_plugin_schema_version = plugin_config_get( 'schema', -1 );

	plugin_pop_current();

	return ( $t_plugin_schema_version < count( $t_plugin_schema ) - 1 );
}

/**
 * Upgrade an installed plugin's schema.
 * @param string Plugin basename
 * @return multi True if upgrade completed, null if problem
 */
function plugin_upgrade( $p_plugin ) {
	access_ensure_global_level( config_get_global( 'manage_plugin_threshold' ) );

	if ( !plugin_is_installed( $p_plugin->basename ) ) {
		return;
	}

	plugin_push_current( $p_plugin->basename );

	$t_schema_version = plugin_config_get( 'schema', -1 );
	$t_schema = $p_plugin->schema();

	global $g_db;
	$t_dict = NewDataDictionary( $g_db );

	$i = $t_schema_version + 1;
	while ( $i < count( $t_schema ) ) {
		if ( ! $p_plugin->upgrade( $i ) ) {
			plugin_pop_current();
			return false;
		}

		$t_target = $t_schema[$i][1][0];

		if ( $t_schema[$i][0] == 'InsertData' ) {
			$t_sqlarray = call_user_func_array( $t_schema[$i][0], $t_schema[$i][1] );
		} else if ( $t_schema[$i][0] == 'UpdateSQL' ) {
			$t_sqlarray = array( $t_schema[$i][1] );
			$t_target = $t_schema[$i][1];
		} else {
			$t_sqlarray = call_user_func_array( Array( $t_dict, $t_schema[$i][0] ), $t_schema[$i][1] );
		}
		$t_status = $t_dict->ExecuteSQLArray( $t_sqlarray );

		if ( 2 == $t_status ) {
			plugin_config_set( 'schema', $i );
		} else {
			return null;
		}

		$i++;
	}

	plugin_pop_current();

	return true;
}

/**
 * Uninstall a plugin from the database.
 * @param string Plugin basename
 */
function plugin_uninstall( $p_plugin ) {
	access_ensure_global_level( config_get_global( 'manage_plugin_threshold' ) );

	if ( !plugin_is_installed( $p_plugin->basename ) ) {
		return;
	}

	$t_plugin_table	= db_get_table( 'mantis_plugin_table' );
	$c_basename = db_prepare_string( $p_plugin->basename );

	$t_query = "DELETE FROM $t_plugin_table WHERE basename=" . db_param(0);
	db_query_bound( $t_query, array( $c_basename ) );

	plugin_push_current( $p_plugin->basename );

	$p_plugin->uninstall();

	plugin_pop_current();
}



### Core usage only.

/**
 * Search the plugins directory for plugins.
 * @return array Plugin basename/info key/value pairs.
 */
function plugin_find_all() {
	$t_plugin_path = config_get_global( 'plugin_path' );
	$t_plugins = array( 'MantisCore' => new MantisCorePlugin( 'MantisCore' ) );

	if ( $t_dir = opendir( $t_plugin_path ) ) {
		while ( ($t_file = readdir( $t_dir )) !== false ) {
			if ( '.' == $t_file || '..' == $t_file ) {
				continue;
			}
			if ( is_dir( $t_plugin_path.$t_file ) ) {
				$t_plugin = plugin_register( $t_file, true );

				if ( !is_null( $t_plugin ) ) {
					$t_plugins[$t_file] = $t_plugin;
				}
			}
		}
		closedir( $t_dir );
	}
	return $t_plugins;
}

/**
 * Load a plugin's core class file.
 * @param string Plugin basename
 */
function plugin_include( $p_basename ) {
		$t_path = config_get_global( 'plugin_path' ) . DIRECTORY_SEPARATOR . $p_basename . DIRECTORY_SEPARATOR;
		$t_plugin_file = $t_path . $p_basename . '.php';

		$t_included = false;
		if ( is_file( $t_plugin_file ) ) {
			include_once( $t_plugin_file );
			$t_included = true;
		}

		return $t_included;
}

/**
 * Register a plugin with Mantis.
 * The plugin class must already be loaded before calling.
 * @param string Plugin classname without 'Plugin' postfix
 */
function plugin_register( $p_basename, $p_return=false ) {
	global $g_plugin_cache;

	if ( !isset( $g_plugin_cache[$p_basename] ) ) {
		$t_classname = $p_basename . 'Plugin';

		# Include the plugin script if the class is not already declared.
		if ( !class_exists( $t_classname ) ) {
			if ( ! plugin_include( $p_basename ) ) {
				return null;
			}
		}

		# Make sure the class exists and that it's of the right type.
		if ( class_exists( $t_classname ) &&
			is_subclass_of( $t_classname, 'MantisPlugin' )
	   		) {
				plugin_push_current( $p_basename );

				$t_plugin = new $t_classname( $p_basename );

				plugin_pop_current();

				# Final check on the class
				if ( is_null( $t_plugin->name ) || is_null( $t_plugin->version ) ) {
						return null;
				}

				if ( $p_return ) {
					return $t_plugin;
				} else {
					$g_plugin_cache[$p_basename] = $t_plugin;
				}
		}
	}

	return $g_plugin_cache[$p_basename];
}

/**
 * Find and register all installed plugins.
 */
function plugin_register_installed() {
	$t_plugin_table = db_get_table( 'mantis_plugin_table' );

	$t_query = "SELECT basename FROM $t_plugin_table WHERE enabled=1";
	$t_result = db_query( $t_query );

	while ( $t_row = db_fetch_array( $t_result ) ) {
		$t_basename = $t_row['basename'];
		plugin_register( $t_basename );
	}
}

/**
 * Initialize all installed plugins.
 * Post-signals EVENT_PLUGIN_INIT.
 */
function plugin_init_installed() {
	if ( OFF == config_get_global( 'plugins_enabled' ) || !db_table_exists( db_get_table( 'mantis_plugin_table' ) ) ) {
		return;
	}

	global $g_plugin_cache, $g_plugin_current;
	$g_plugin_cache = array();
	$g_plugin_current = array();

	plugin_register( 'MantisCore' );
	plugin_register_installed();

	$t_plugins = array();
	foreach ( $g_plugin_cache as $t_basename => $t_plugin ) {
		$t_plugins[] = $t_basename;
	}

	$t_passes = 0;
	do {
		$t_plugins_retry = array();

		foreach( $t_plugins as $t_basename ) {
			if ( !plugin_init( $t_basename ) ) {
				# Dependent plugin
				$t_plugins_retry[] = $t_basename;
			}
		}

		$t_plugins = $t_plugins_retry;
		$t_passes++;

	} while ( $t_passes < count( $t_plugins ) );

	event_signal( 'EVENT_PLUGIN_INIT' );
}

/**
 * Initialize a single plugin.
 * @param string Plugin basename
 * @return boolean True if plugin initialized, false otherwise.
 */
function plugin_init( $p_basename ) {
	global $g_plugin_cache;

	# handle dependent plugins
	if ( isset( $g_plugin_cache[$p_basename] ) ) {
		$t_plugin = $g_plugin_cache[$p_basename];

		if ( is_array( $t_plugin->requires ) ) {
			foreach ( $t_plugin->requires as $t_required => $t_version ) {
				if ( plugin_dependency( $t_required, $t_version ) !== 1 ) {
					return false;
				}
			}
		}

		plugin_push_current( $p_basename );

		$t_plugin->__init();

		plugin_pop_current();
	}

	return true;
}