*
* 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
* 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.
+ * 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
* 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 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.
*
*/
-function concat_hook_function($name, &$args) {
+function concat_hook_function($name, &$args, $force_array=FALSE) {
global $squirrelmail_plugin_hooks, $currentHookName;
$currentHookName = $name;
}
}
+ if ($force_array && is_string($ret)) {
+ $ret = array($ret);
+ }
+
$currentHookName = '';
return $ret;
}
/**
+ * 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
}
/**
- * Check a plugin's version.
+ * Get a plugin's version.
*
- * Returns TRUE if the given plugin is installed,
- * activated and is at minimum version $a.$b.$c.
- * If any one of those conditions fails, FALSE
- * will be returned (careful of plugins that are
- * sufficiently versioned but are not activated).
+ * Determines and returns a plugin's version.
*
- * 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
+ * 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 function 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.
+ * 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 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 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
*
* check; must precisely
* match the plugin
* directory name
- * @param int a major version number
- * @param int b minor version number
- * @param int c release number
* @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 bool
+ * @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 check_plugin_version($plugin_name,
- $a = 0, $b = 0, $c = 0,
- $force_inclusion = FALSE)
+function get_plugin_version($plugin_name, $force_inclusion = FALSE, $do_parse = FALSE)
{
$info_function = $plugin_name . '_info';
// otherwise, look for older version function
//
if (!$plugin_version && function_exists($version_function))
- $plugin_version = $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.
+ *
+ * Returns TRUE if the given plugin is installed,
+ * activated and is at minimum version $a.$b.$c.
+ * If any one of those conditions fails, FALSE
+ * will be returned (careful of plugins that are
+ * sufficiently versioned but are not activated).
+ *
+ * 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 (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.
+ *
+ * Note that this function 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 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 int a major version number
+ * @param int b minor version number
+ * @param int c release number
+ * @param bool force_inclusion try to get version info
+ * for plugins not activated?
+ * (default FALSE)
+ *
+ * @return bool
+ *
+ */
+function check_plugin_version($plugin_name,
+ $a = 0, $b = 0, $c = 0,
+ $force_inclusion = FALSE)
+{
+ $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;
projects / squirrelmail.git / blobdiff