X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=functions%2Fplugin.php;h=c2fb367e2aee934f0673869595755be3bd8a4d9c;hb=fdf58ef92a0b69f93bd08e22be831aa8172bfe62;hp=844f9007c4089d0d3c4fb8bec6650a657d4bde46;hpb=d99b6c569279c121747d92e6feab576371f7828a;p=squirrelmail.git diff --git a/functions/plugin.php b/functions/plugin.php index 844f9007..c2fb367e 100644 --- a/functions/plugin.php +++ b/functions/plugin.php @@ -7,7 +7,7 @@ * * Documentation on how to write plugins might show up some time. * - * @copyright © 1999-2006 The SquirrelMail Project Team + * @copyright © 1999-2007 The SquirrelMail Project Team * @license http://opensource.org/licenses/gpl-license.php GNU Public License * @version $Id$ * @package squirrelmail @@ -21,97 +21,156 @@ function use_plugin ($name) { if (file_exists(SM_PATH . "plugins/$name/setup.php")) { include_once(SM_PATH . "plugins/$name/setup.php"); - $function = "squirrelmail_plugin_init_$name"; - if (function_exists($function)) { - $function(); - } - } -} -/** - * This function executes a hook. - * @param string $name Name of hook to fire - * @return mixed $data - */ -function do_hook ($name) { - global $squirrelmail_plugin_hooks, $currentHookName; - $data = func_get_args(); - $currentHookName = $name; - - if (isset($squirrelmail_plugin_hooks[$name]) - && is_array($squirrelmail_plugin_hooks[$name])) { - foreach ($squirrelmail_plugin_hooks[$name] as $function) { - /* Add something to set correct gettext domain for plugin. */ - if (function_exists($function)) { - $function($data); - } - } + /** + * As of SM 1.5.2, plugin hook registration is statically + * accomplished using the configuration utility (config/conf.pl). + * And this code is deprecated (but let's keep it until + * the new registration system is proven). + * + */ + //$function = "squirrelmail_plugin_init_$name"; + //if (function_exists($function)) { + // $function(); + //} } - - $currentHookName = ''; - - /* Variable-length argument lists have a slight problem when */ - /* passing values by reference. Pity. This is a workaround. */ - return $data; } /** - * This function executes a hook and allows for parameters to be passed. + * This function executes a plugin hook. + * + * It includes an arbitrary return value that is managed by + * all plugins on the same hook and returned to the core hook + * location. + * + * The desired format of the return value should be defined + * by the context in which the hook is called. + * + * Note that the master return value for this hook is passed + * to each plugin after the main argument(s) value/array as a + * convenience only - to show what the current return value is + * even though it is liable to be changed by other plugins. + * + * If any plugin on this hook wants to modify the $args + * plugin parameter, it simply has to use call-by-reference + * syntax in the hook function that it has registered for the + * current hook. Note that this is in addition to (entirely + * independent of) the return value for this hook. + * + * @param string $name Name of hook being executed + * @param mixed $args A single value or an array of arguments + * that are to be passed to all plugins + * operating off the hook being called. + * Note that this argument is passed by + * reference thus it is liable to be + * changed after the hook completes. + * + * @return mixed The return value that is managed by the plugins + * on the current hook. * - * @param string name the name of the hook - * @param mixed param the parameters to pass to the hook function - * @return mixed the return value of the hook function */ -function do_hook_function($name,$parm=NULL) { +function do_hook($name, &$args) { + global $squirrelmail_plugin_hooks, $currentHookName; - $ret = ''; $currentHookName = $name; + $ret = NULL; if (isset($squirrelmail_plugin_hooks[$name]) && is_array($squirrelmail_plugin_hooks[$name])) { - foreach ($squirrelmail_plugin_hooks[$name] as $function) { - /* Add something to set correct gettext domain for plugin. */ + foreach ($squirrelmail_plugin_hooks[$name] as $plugin_name => $function) { + use_plugin($plugin_name); if (function_exists($function)) { - $ret = $function($parm); + $ret = $function($args, $ret); + + // each plugin can call additional hooks, so need + // to make sure the current hook name is accurate + // again after each plugin has finished + // + $currentHookName = $name; } } } $currentHookName = ''; - - /* Variable-length argument lists have a slight problem when */ - /* passing values by reference. Pity. This is a workaround. */ return $ret; + } /** - * This function executes a hook, concatenating the results of each - * plugin that has the hook defined. + * This function executes a hook that allows for an arbitrary + * return value from each plugin that will be merged into one + * array (or one string if all return values are strings) and + * returned to the core hook location. + * + * Note that unlike PHP's array_merge function, matching array keys + * will not overwrite each other, instead, values under such keys + * will be concatenated if they are both strings, or merged if they + * are arrays (in the same (non-overwrite) manner recursively). + * + * Plugins returning non-arrays (strings, objects, etc) will have + * their output added to the end of the ultimate return array, + * unless ALL values returned are strings, in which case one string + * with all returned strings concatenated together is returned + * (unless $force_array is TRUE). + * + * If any plugin on this hook wants to modify the $args + * plugin parameter, it simply has to use call-by-reference + * syntax in the hook function that it has registered for the + * current hook. Note that this is in addition to (entirely + * independent of) the return value for this hook. + * + * @param string $name Name of hook being executed + * @param mixed $args A single value or an array of arguments + * that are to be passed to all plugins + * operating off the hook being called. + * Note that this argument is passed by + * reference thus it is liable to be + * changed after the hook completes. + * @param boolean $force_array When TRUE, guarantees the return + * value will ALWAYS be an array, + * (simple strings will be forced + * into a one-element array). + * When FALSE, behavior is as + * described above (OPTIONAL; + * default behavior is to return + * mixed - array or string). + * + * @return mixed the merged return arrays or strings of each + * plugin on this hook. * - * @param string name the name of the hook - * @param mixed parm optional hook function parameters - * @return string a concatenation of the results of each plugin function */ -function concat_hook_function($name,$parm=NULL) { +function concat_hook_function($name, &$args, $force_array=FALSE) { + global $squirrelmail_plugin_hooks, $currentHookName; - $ret = ''; $currentHookName = $name; + $ret = ''; if (isset($squirrelmail_plugin_hooks[$name]) && is_array($squirrelmail_plugin_hooks[$name])) { - foreach ($squirrelmail_plugin_hooks[$name] as $function) { - /* Concatenate results from hook. */ + foreach ($squirrelmail_plugin_hooks[$name] as $plugin_name => $function) { + use_plugin($plugin_name); if (function_exists($function)) { - $ret .= $function($parm); + $plugin_ret = $function($args); + if (!empty($plugin_ret)) { + $ret = sqm_array_merge($ret, $plugin_ret); + } + + // each plugin can call additional hooks, so need + // to make sure the current hook name is accurate + // again after each plugin has finished + // + $currentHookName = $name; } } } - $currentHookName = ''; + if ($force_array && is_string($ret)) { + $ret = array($ret); + } - /* Variable-length argument lists have a slight problem when */ - /* passing values by reference. Pity. This is a workaround. */ + $currentHookName = ''; return $ret; + } /** @@ -121,13 +180,27 @@ function concat_hook_function($name,$parm=NULL) { * override any trues. * Priority 0 means majority rules. Ties will be broken with $tie * - * @param string name the hook name - * @param mixed parm the parameters for the hook function - * @param int priority - * @param bool tie - * @return bool the result of the function + * If any plugin on this hook wants to modify the $args + * plugin parameter, it simply has to use call-by-reference + * syntax in the hook function that it has registered for the + * current hook. Note that this is in addition to (entirely + * independent of) the return value for this hook. + * + * @param string $name The hook name + * @param mixed $args A single value or an array of arguments + * that are to be passed to all plugins + * operating off the hook being called. + * Note that this argument is passed by + * reference thus it is liable to be + * changed after the hook completes. + * @param int $priority See explanation above + * @param boolean $tie See explanation above + * + * @return boolean The result of the function + * */ -function boolean_hook_function($name,$parm=NULL,$priority=0,$tie=false) { +function boolean_hook_function($name, &$args, $priority=0, $tie=false) { + global $squirrelmail_plugin_hooks, $currentHookName; $yea = 0; $nay = 0; @@ -138,14 +211,21 @@ function boolean_hook_function($name,$parm=NULL,$priority=0,$tie=false) { /* Loop over the plugins that registered the hook */ $currentHookName = $name; - foreach ($squirrelmail_plugin_hooks[$name] as $function) { + foreach ($squirrelmail_plugin_hooks[$name] as $plugin_name => $function) { + use_plugin($plugin_name); if (function_exists($function)) { - $ret = $function($parm); + $ret = $function($args); if ($ret) { $yea++; } else { $nay++; } + + // each plugin can call additional hooks, so need + // to make sure the current hook name is accurate + // again after each plugin has finished + // + $currentHookName = $name; } } $currentHookName = ''; @@ -166,14 +246,16 @@ function boolean_hook_function($name,$parm=NULL,$priority=0,$tie=false) { } // If the code gets here, there was a problem - no hooks, etc. return NULL; + } /** + * Do not use, use checkForJavascript() instead. + * * This function checks whether the user's USER_AGENT is known to * be broken. If so, returns true and the plugin is invisible to the * offending browser. * *** THIS IS A TEST FOR JAVASCRIPT SUPPORT *** - * FIXME: This function needs to have its name changed! * * @return bool whether this browser properly supports JavaScript * @deprecated use checkForJavascript() since 1.5.1 @@ -207,6 +289,119 @@ function is_plugin_enabled($plugin_name) { } } +/** + * Get a plugin's version. + * + * Determines and returns a plugin's version. + * + * By default, the desired plugin must be currently + * activated, and if it is not, this function will + * return FALSE. By overriding the default value + * of $force_inclusion, this function will attempt + * to grab versioning information from the given + * plugin even if it is not activated (plugin still + * has to be unpackaged and set in place in the + * plugins directory). Use with care - some plugins + * might break SquirrelMail when this is used. + * + * By turning on the $do_parse argument, the version + * string will be parsed by SquirrelMail into a + * SquirrelMail-compatible version string (such as + * "1.2.3") if it is not already. + * + * Note that this assumes plugin versioning is + * consistently applied in the same fashion that + * SquirrelMail versions are, with the exception that + * an applicable SquirrelMail version may be appended + * to the version number (which will be ignored herein). + * That is, plugin version number schemes are expected + * in the following format: 1.2.3, or 1.2.3-1.4.0. + * + * Any characters after the third version number + * indicating things such as beta or release candidate + * versions are discarded, so formats such as the + * following will also work, although extra information + * about beta versions can possibly confuse the desired + * results of the version check: 1.2.3-beta4, 1.2.3.RC2, + * and so forth. + * + * @since 1.5.2 + * + * @param string plugin_name name of the plugin to + * check; must precisely + * match the plugin + * directory name + * @param bool force_inclusion try to get version info + * for plugins not activated? + * (default FALSE) + * @param bool do_parse return the plugin version + * in SquirrelMail-compatible + * format (default FALSE) + * + * @return mixed The plugin version string if found, otherwise, + * boolean FALSE is returned indicating that no + * version information could be found for the plugin. + * + */ +function get_plugin_version($plugin_name, $force_inclusion = FALSE, $do_parse = FALSE) +{ + + $info_function = $plugin_name . '_info'; + $version_function = $plugin_name . '_version'; + $plugin_info = array(); + $plugin_version = FALSE; + + + // first attempt to find the plugin info function, wherein + // the plugin version should be available + // + if (function_exists($info_function)) + $plugin_info = $info_function(); + else if ($force_inclusion + && file_exists(SM_PATH . 'plugins/' . $plugin_name . '/setup.php')) + { + include_once(SM_PATH . 'plugins/' . $plugin_name . '/setup.php'); + if (function_exists($info_function)) + $plugin_info = $info_function(); + } + if (!empty($plugin_info['version'])) + $plugin_version = $plugin_info['version']; + + + // otherwise, look for older version function + // + if (!$plugin_version && function_exists($version_function)) + $plugin_version = $version_function(); + + + if ($plugin_version && $do_parse) + { + + // massage version number into something we understand + // + // the first regexp strips everything and anything that follows + // the first occurance of a non-digit (or non decimal point), so + // beware that putting letters in the middle of a version string + // will effectively truncate the version string right there (but + // this also just helps remove the SquirrelMail version part off + // of versions such as "1.2.3-1.4.4") + // + // the second regexp just strips out non-digits/non-decimal points + // (and might be redundant(?)) + // + // the regexps are wrapped in a trim that makes sure the version + // does not start or end with a decimal point + // + $plugin_version = trim(preg_replace(array('/[^0-9.]+.*$/', '/[^0-9.]/'), + '', $plugin_version), + '.'); + + } + + return $plugin_version; + +} + /** * Check a plugin's version. * @@ -219,7 +414,7 @@ function is_plugin_enabled($plugin_name) { * By overriding the default value of $force_inclusion, * this function will attempt to grab versioning * information from the given plugin even if it - * is not activated (plugin still has to be + * is not activated (the plugin still has to be * unpackaged and set in place in the plugins * directory). Use with care - some plugins * might break SquirrelMail when this is used. @@ -233,13 +428,14 @@ function is_plugin_enabled($plugin_name) { * version number schemes are expected in the following * format: 1.2.3, or 1.2.3-1.4.0. * - * Any characters after the third number are discarded, - * so formats such as the following will also work, - * although extra information about beta versions can - * possibly confuse the desired results of the version - * check: 1.2.3-beta4, 1.2.3.RC2, and so forth. + * Any characters after the third number indicating + * things such as beta or release candidate versions + * are discarded, so formats such as the following + * will also work, although extra information about + * beta versions can possibly confuse the desired results + * of the version check: 1.2.3-beta4, 1.2.3.RC2, and so forth. * - * @since 1.5.1 + * @since 1.5.2 * * @param string plugin_name name of the plugin to * check; must precisely @@ -260,30 +456,13 @@ function check_plugin_version($plugin_name, $force_inclusion = FALSE) { - $version_function = $plugin_name . '_version'; - $plugin_version = FALSE; - - - // attempt to find version function and get version from plugin - // - if (function_exists($version_function)) - $plugin_version = $version_function(); - else if ($force_inclusion - && file_exists(SM_PATH . 'plugins/' . $plugin_name . '/setup.php')) - { - include_once(SM_PATH . 'plugins/' . $plugin_name . '/setup.php'); - if (function_exists($version_function)) - $plugin_version = $version_function(); - } - + $plugin_version = get_plugin_version($plugin_name, $force_inclusion, TRUE); if (!$plugin_version) return FALSE; - // now massage version number into something we understand + // split the version string into sections delimited by + // decimal points, and make sure we have three sections // - $plugin_version = trim(preg_replace(array('/[^0-9.]+.*$/', '/[^0-9.]/'), - '', $plugin_version), - '.'); $plugin_version = explode('.', $plugin_version); if (!isset($plugin_version[0])) $plugin_version[0] = 0; if (!isset($plugin_version[1])) $plugin_version[1] = 0; @@ -303,3 +482,220 @@ function check_plugin_version($plugin_name, } +/** + * Get a plugin's other plugin dependencies. + * + * Determines and returns all the other plugins + * that a given plugin requires, as well as the + * minimum version numbers of the required plugins. + * + * By default, the desired plugin must be currently + * activated, and if it is not, this function will + * return FALSE. By overriding the default value + * of $force_inclusion, this function will attempt + * to grab dependency information from the given + * plugin even if it is not activated (plugin still + * has to be unpackaged and set in place in the + * plugins directory). Use with care - some plugins + * might break SquirrelMail when this is used. + * + * By turning on the $do_parse argument (it is on by + * default), the version string for each required + * plugin will be parsed by SquirrelMail into a + * SquirrelMail-compatible version string (such as + * "1.2.3") if it is not already. See notes about + * version formatting under get_plugin_version(). + * + * @since 1.5.2 + * + * @param string plugin_name name of the plugin to + * check; must precisely + * match the plugin + * directory name + * @param bool force_inclusion try to get version info + * for plugins not activated? + * (default FALSE) + * @param bool do_parse return the version numbers + * for required plugins in + * SquirrelMail-compatible + * format (default FALSE) + * + * @return mixed Boolean FALSE is returned if the plugin + * could not be found or does not indicate + * whether it has other plugin dependencies, + * otherwise an array is returned where keys + * are the names of required plugin dependencies, + * and values are the minimum version required + * for that plugin. Note that the array might + * be empty, indicating that the plugin has no + * dependencies. + * + */ +function get_plugin_dependencies($plugin_name, $force_inclusion = FALSE, $do_parse = TRUE) +{ + + $info_function = $plugin_name . '_info'; + $plugin_info = array(); + $plugin_dependencies = FALSE; + + + // first attempt to find the plugin info function, wherein + // the plugin dependencies should be available + // + if (function_exists($info_function)) + $plugin_info = $info_function(); + else if ($force_inclusion + && file_exists(SM_PATH . 'plugins/' . $plugin_name . '/setup.php')) + { + include_once(SM_PATH . 'plugins/' . $plugin_name . '/setup.php'); + if (function_exists($info_function)) + $plugin_info = $info_function(); + } + if (!empty($plugin_info['required_plugins'])) + $plugin_dependencies = $plugin_info['required_plugins']; + + + if (!empty($plugin_dependencies) && $do_parse) + { + + $new_plugin_dependencies = ''; + foreach ($plugin_dependencies as $plugin_name => $plugin_version) + { + + // massage version number into something we understand + // + // the first regexp strips everything and anything that follows + // the first occurance of a non-digit (or non decimal point), so + // beware that putting letters in the middle of a version string + // will effectively truncate the version string right there (but + // this also just helps remove the SquirrelMail version part off + // of versions such as "1.2.3-1.4.4") + // + // the second regexp just strips out non-digits/non-decimal points + // (and might be redundant(?)) + // + // the regexps are wrapped in a trim that makes sure the version + // does not start or end with a decimal point + // + $new_plugin_dependencies[$plugin_name] + = trim(preg_replace(array('/[^0-9.]+.*$/', '/[^0-9.]/'), + '', $plugin_version), + '.'); + + } + + $plugin_dependencies = $new_plugin_dependencies; + + } + + return $plugin_dependencies; + +} + +/** + * Check a plugin's other plugin dependencies. + * + * Determines whether or not all of the given + * plugin's required plugins are installed and + * up to the proper version. + * + * By default, the desired plugin must be currently + * activated, and if it is not, this function will + * return FALSE. By overriding the default value + * of $force_inclusion, this function will attempt + * to grab dependency information from the given + * plugin even if it is not activated (plugin still + * has to be unpackaged and set in place in the + * plugins directory). Use with care - some plugins + * might break SquirrelMail when this is used. + * + * NOTE that if a plugin does not report whether or + * not it has other plugin dependencies, this function + * will return TRUE, although that is possibly incorrect + * or misleading. + * +//FIXME: + * NOTE that currently, the dependencies are checked + * in such as way as they do not have to be activated; + * this is due to the large number of plugins that + * require the Compatibility plugin, which does (should) + * not need to be activated. Best solution would be to + * expand the plugin info function so that it indicates + * also whether or not the required plugin must be + * activated or not. +//FIXME: proposed info() change: + 'required_plugins' => array( + 'activated' => array( + 'blah' => '1.0', + ), + 'inactive' => array( + 'compatibility' => '2.0.5', + ), + ) +//FIXME: optional proposed info() change: (I vote for this, the problem, tho, is that it is a bit of a departure from what is already out there...) + 'required_plugins' => array( + 'compatibility' => array( + 'version' => '2.0.5', + 'activate' => FALSE, + ) + ) +//FIXME: optional proposed info() change: + 'required_plugins' => array( + 'compatibility::NO_NEED_TO_ACTIVATE::' => '2.0.5', + ) +//FIXME: optional proposed info() change: + 'required_plugins' => array( + 'compatibility' => '2.0.5::NO_NEED_TO_ACTIVATE::', + ) + * + * @since 1.5.2 + * + * @param string plugin_name name of the plugin to + * check; must precisely + * match the plugin + * directory name + * @param bool force_inclusion try to get version info + * for plugins not activated? + * (default FALSE) + * + * @return mixed Boolean TRUE if all of the plugin's + * required plugins are correctly installed, + * otherwise an array of the required plugins + * that are either not installed or not up to + * the minimum required version. The array is + * keyed by plugin name where values are the + * (printable, non-parsed) versions required. + * + */ +function check_plugin_dependencies($plugin_name, $force_inclusion = FALSE) +{ + + $dependencies = get_plugin_dependencies($plugin_name, $force_inclusion); + if (!$dependencies) return TRUE; + $missing_or_bad = array(); + + foreach ($dependencies as $depend_name => $depend_version) + { + $version = preg_split('/\./', $depend_version, 3); + $version[2] = intval($version[2]); +//FIXME: should fix plugin info function API to tell us what the value of $force_dependency_inclusion should be below + //$force_dependency_inclusion = !$the_plugin_info_thingy_array['required_plugins']['must_be_activated']; + $force_dependency_inclusion = TRUE; + if (!check_plugin_version($depend_name, $version[0], $version[1], $version[2], $force_dependency_inclusion)) + $missing_or_bad[$depend_name] = $depend_version; + } + + if (empty($missing_or_bad)) return TRUE; + + + // get non-parsed required versions + // + $non_parsed_dependencies = get_plugin_dependencies($plugin_name, $force_inclusion, FALSE); + $return_array = array(); + foreach ($missing_or_bad as $depend_name => $ignore) + $return_array[$depend_name] = $non_parsed_dependencies[$depend_name]; + + return $return_array; + +} +