functions/plugin.php

   1 <?php
   2
   3 /**
   4  * plugin.php
   5  *
   6  * This file provides the framework for a plugin architecture.
   7  *
   8  * Documentation on how to write plugins might show up some time.
   9  *
  10  * @copyright &copy; 1999-2006 The SquirrelMail Project Team
  11  * @license http://opensource.org/licenses/gpl-license.php GNU Public License
  12  * @version $Id$
  13  * @package squirrelmail
  14  */
  15
  16 /**
  17  * This function adds a plugin.
  18  * @param string $name Internal plugin name (ie. delete_move_next)
  19  * @return void
  20  */
  21 function use_plugin ($name) {
  22     if (file_exists(SM_PATH . "plugins/$name/setup.php")) {
  23         include_once(SM_PATH . "plugins/$name/setup.php");
  24
  25         /**
  26           * As of SM 1.5.2, plugin hook registration is statically
  27           * accomplished using the configuration utility (config/conf.pl).
  28           * And this code is deprecated (but let's keep it until
  29           * the new registration system is proven).
  30           *
  31           */
  32         //$function = "squirrelmail_plugin_init_$name";
  33         //if (function_exists($function)) {
  34         //    $function();
  35         //}
  36     }
  37 }
  38
  39 /**
  40  * This function executes a plugin hook.
  41  *
  42  * It includes an arbitrary return value that is managed by
  43  * all plugins on the same hook and returned to the core hook
  44  * location.
  45  *
  46  * The desired format of the return value should be defined
  47  * by the context in which the hook is called.
  48  *
  49  * Note that the master return value for this hook is passed
  50  * to each plugin after the main argument(s) value/array as a
  51  * convenience only - to show what the current return value is
  52  * even though it is liable to be changed by other plugins.
  53  *
  54  * If any plugin on this hook wants to modify the $args
  55  * plugin parameter, it simply has to use call-by-reference
  56  * syntax in the hook function that it has registered for the
  57  * current hook.  Note that this is in addition to (entirely
  58  * independent of) the return value for this hook.
  59  *
  60  * @param string $name Name of hook being executed
  61  * @param mixed  $args A single value or an array of arguments
  62  *                     that are to be passed to all plugins
  63  *                     operating off the hook being called.
  64  *                     Note that this argument is passed by
  65  *                     reference thus it is liable to be
  66  *                     changed after the hook completes.
  67  *
  68  * @return mixed The return value that is managed by the plugins
  69  *               on the current hook.
  70  *
  71  */
  72 function do_hook($name, &$args) {
  73
  74     global $squirrelmail_plugin_hooks, $currentHookName;
  75     $currentHookName = $name;
  76     $ret = NULL;
  77
  78     if (isset($squirrelmail_plugin_hooks[$name])
  79           && is_array($squirrelmail_plugin_hooks[$name])) {
  80         foreach ($squirrelmail_plugin_hooks[$name] as $plugin_name => $function) {
  81             use_plugin($plugin_name);
  82             if (function_exists($function)) {
  83                 $ret = $function($args, $ret);
  84             }
  85         }
  86     }
  87
  88     $currentHookName = '';
  89     return $ret;
  90
  91 }
  92
  93 /**
  94  * This function executes a hook that allows for an arbitrary
  95  * return value from each plugin that will be merged into one
  96  * array (or one string if all return values are strings) and
  97  * returned to the core hook location.
  98  *
  99  * Note that unlike PHP's array_merge function, matching array keys
 100  * will not overwrite each other, instead, values under such keys
 101  * will be concatenated if they are both strings, or merged if they
 102  * are arrays (in the same (non-overwrite) manner recursively).
 103  *
 104  * Plugins returning non-arrays (strings, objects, etc) will have
 105  * their output added to the end of the ultimate return array,
 106  * unless ALL values returned are strings, in which case one string
 107  * with all returned strings concatenated together is returned.
 108  *
 109  * If any plugin on this hook wants to modify the $args
 110  * plugin parameter, it simply has to use call-by-reference
 111  * syntax in the hook function that it has registered for the
 112  * current hook.  Note that this is in addition to (entirely
 113  * independent of) the return value for this hook.
 114  *
 115  * @param string $name Name of hook being executed
 116  * @param mixed  $args A single value or an array of arguments
 117  *                     that are to be passed to all plugins
 118  *                     operating off the hook being called.
 119  *                     Note that this argument is passed by
 120  *                     reference thus it is liable to be
 121  *                     changed after the hook completes.
 122  *
 123  * @return mixed the merged return arrays or strings of each
 124  *               plugin on this hook.
 125  *
 126  */
 127 function concat_hook_function($name, &$args) {
 128
 129     global $squirrelmail_plugin_hooks, $currentHookName;
 130     $currentHookName = $name;
 131     $ret = '';
 132
 133     if (isset($squirrelmail_plugin_hooks[$name])
 134           && is_array($squirrelmail_plugin_hooks[$name])) {
 135         foreach ($squirrelmail_plugin_hooks[$name] as $plugin_name => $function) {
 136             use_plugin($plugin_name);
 137             if (function_exists($function)) {
 138                 $plugin_ret = $function($args);
 139                 if (!empty($plugin_ret)) {
 140                     $ret = sqm_array_merge($ret, $plugin_ret);
 141                 }
 142             }
 143         }
 144     }
 145
 146     $currentHookName = '';
 147     return $ret;
 148
 149 }
 150
 151 /**
 152  * This function is used for hooks which are to return true or
 153  * false. If $priority is > 0, any one or more trues will override
 154  * any falses. If $priority < 0, then one or more falses will
 155  * override any trues.
 156  * Priority 0 means majority rules.  Ties will be broken with $tie
 157  *
 158  * If any plugin on this hook wants to modify the $args
 159  * plugin parameter, it simply has to use call-by-reference
 160  * syntax in the hook function that it has registered for the
 161  * current hook.  Note that this is in addition to (entirely
 162  * independent of) the return value for this hook.
 163  *
 164  * @param string  $name     The hook name
 165  * @param mixed   $args     A single value or an array of arguments
 166  *                          that are to be passed to all plugins
 167  *                          operating off the hook being called.
 168  *                          Note that this argument is passed by
 169  *                          reference thus it is liable to be
 170  *                          changed after the hook completes.
 171  * @param int     $priority See explanation above
 172  * @param boolean $tie      See explanation above
 173  *
 174  * @return boolean The result of the function
 175  *
 176  */
 177 function boolean_hook_function($name, &$args, $priority=0, $tie=false) {
 178
 179     global $squirrelmail_plugin_hooks, $currentHookName;
 180     $yea = 0;
 181     $nay = 0;
 182     $ret = $tie;
 183
 184     if (isset($squirrelmail_plugin_hooks[$name]) &&
 185         is_array($squirrelmail_plugin_hooks[$name])) {
 186
 187         /* Loop over the plugins that registered the hook */
 188         $currentHookName = $name;
 189         foreach ($squirrelmail_plugin_hooks[$name] as $plugin_name => $function) {
 190             use_plugin($plugin_name);
 191             if (function_exists($function)) {
 192                 $ret = $function($args);
 193                 if ($ret) {
 194                     $yea++;
 195                 } else {
 196                     $nay++;
 197                 }
 198             }
 199         }
 200         $currentHookName = '';
 201
 202         /* Examine the aftermath and assign the return value appropriately */
 203         if (($priority > 0) && ($yea)) {
 204             $ret = true;
 205         } elseif (($priority < 0) && ($nay)) {
 206             $ret = false;
 207         } elseif ($yea > $nay) {
 208             $ret = true;
 209         } elseif ($nay > $yea) {
 210             $ret = false;
 211         } else {
 212             // There's a tie, no action needed.
 213         }
 214         return $ret;
 215     }
 216     // If the code gets here, there was a problem - no hooks, etc.
 217     return NULL;
 218
 219 }
 220
 221 /**
 222  * Do not use, use checkForJavascript() instead.
 223  *
 224  * This function checks whether the user's USER_AGENT is known to
 225  * be broken. If so, returns true and the plugin is invisible to the
 226  * offending browser.
 227  * *** THIS IS A TEST FOR JAVASCRIPT SUPPORT ***
 228  *
 229  * @return bool whether this browser properly supports JavaScript
 230  * @deprecated use checkForJavascript() since 1.5.1
 231  */
 232 function soupNazi(){
 233     return !checkForJavascript();
 234 }
 235
 236 /**
 237  * Check if plugin is enabled
 238  * @param string $plugin_name plugin name
 239  * @since 1.5.1
 240  * @return boolean
 241  */
 242 function is_plugin_enabled($plugin_name) {
 243   global $plugins;
 244
 245   /**
 246    * check if variable is empty. if var is not set, php empty
 247    * returns true without error notice.
 248    *
 249    * then check if it is an array
 250    */
 251   if (empty($plugins) || ! is_array($plugins))
 252     return false;
 253
 254   if ( in_array($plugin_name,$plugins) ) {
 255     return true;
 256   } else {
 257     return false;
 258   }
 259 }
 260
 261 /**
 262   * Check a plugin's version.
 263   *
 264   * Returns TRUE if the given plugin is installed,
 265   * activated and is at minimum version $a.$b.$c.
 266   * If any one of those conditions fails, FALSE
 267   * will be returned (careful of plugins that are
 268   * sufficiently versioned but are not activated).
 269   *
 270   * By overriding the default value of $force_inclusion,
 271   * this function will attempt to grab versioning
 272   * information from the given plugin even if it
 273   * is not activated (plugin still has to be
 274   * unpackaged and set in place in the plugins
 275   * directory).  Use with care - some plugins
 276   * might break SquirrelMail when this is used.
 277   *
 278   * Note that this function assumes plugin
 279   * versioning is consistently applied in the same
 280   * fashion that SquirrelMail versions are, with the
 281   * exception that an applicable SquirrelMail
 282   * version may be appended to the version number
 283   * (which will be ignored herein).  That is, plugin
 284   * version number schemes are expected in the following
 285   * format:  1.2.3, or 1.2.3-1.4.0.
 286   *
 287   * Any characters after the third number are discarded,
 288   * so formats such as the following will also work,
 289   * although extra information about beta versions can
 290   * possibly confuse the desired results of the version
 291   * check:  1.2.3-beta4, 1.2.3.RC2, and so forth.
 292   *
 293   * @since 1.5.2
 294   *
 295   * @param string plugin_name   name of the plugin to
 296   *                             check; must precisely
 297   *                             match the plugin
 298   *                             directory name
 299   * @param int  a               major version number
 300   * @param int  b               minor version number
 301   * @param int  c               release number
 302   * @param bool force_inclusion try to get version info
 303   *                             for plugins not activated?
 304   *                             (default FALSE)
 305   *
 306   * @return bool
 307   *
 308   */
 309 function check_plugin_version($plugin_name,
 310                               $a = 0, $b = 0, $c = 0,
 311                               $force_inclusion = FALSE)
 312 {
 313
 314    $info_function = $plugin_name . '_info';
 315    $version_function = $plugin_name . '_version';
 316    $plugin_info = array();
 317    $plugin_version = FALSE;
 318
 319
 320    // first attempt to find the plugin info function, wherein
 321    // the plugin version should be available
 322    //
 323    if (function_exists($info_function))
 324       $plugin_info = $info_function();
 325    else if ($force_inclusion
 326     && file_exists(SM_PATH . 'plugins/' . $plugin_name . '/setup.php'))
 327    {
 328       include_once(SM_PATH . 'plugins/' . $plugin_name . '/setup.php');
 329       if (function_exists($info_function))
 330          $plugin_info = $info_function();
 331    }
 332    if (!empty($plugin_info['version']))
 333       $plugin_version = $plugin_info['version'];
 334
 335
 336    // otherwise, look for older version function
 337    //
 338    if (!$plugin_version && function_exists($version_function))
 339          $plugin_version = $version_function();
 340
 341
 342    if (!$plugin_version) return FALSE;
 343
 344
 345    // now massage version number into something we understand
 346    //
 347    $plugin_version = trim(preg_replace(array('/[^0-9.]+.*$/', '/[^0-9.]/'),
 348                                        '', $plugin_version),
 349                           '.');
 350    $plugin_version = explode('.', $plugin_version);
 351    if (!isset($plugin_version[0])) $plugin_version[0] = 0;
 352    if (!isset($plugin_version[1])) $plugin_version[1] = 0;
 353    if (!isset($plugin_version[2])) $plugin_version[2] = 0;
 354 //   sm_print_r($plugin_version);
 355
 356
 357    // now test the version number
 358    //
 359    if ($plugin_version[0] < $a ||
 360       ($plugin_version[0] == $a && $plugin_version[1] < $b) ||
 361       ($plugin_version[0] == $a && $plugin_version[1] == $b && $plugin_version[2] < $c))
 362          return FALSE;
 363
 364
 365    return TRUE;
 366
 367 }
 368