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