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     $ret = array();
 146     $currentHookName = $name;
 147
 148     if (isset($squirrelmail_plugin_hooks[$name])
 149           && is_array($squirrelmail_plugin_hooks[$name])) {
 150         foreach ($squirrelmail_plugin_hooks[$name] as $function) {
 151             /* Add something to set correct gettext domain for plugin. */
 152             if (function_exists($function)) {
 153 //                $ret .= $function($parm);
 154                 $ret = sqm_array_merge($ret, $function($parm));
 155             }
 156         }
 157     }
 158
 159     $currentHookName = '';
 160
 161     /* Variable-length argument lists have a slight problem when */
 162     /* passing values by reference. Pity. This is a workaround.  */
 163     // FIXME: empty return array breaks legacy use of this hook, so
 164     // as a workaround, return empty string (let's fix the
 165     // hook calls so we can pull this out)
 166     if (empty($ret)) return '';
 167     return $ret;
 168 }
 169
 170 /**
 171  * This function is used for hooks which are to return true or
 172  * false. If $priority is > 0, any one or more trues will override
 173  * any falses. If $priority < 0, then one or more falses will
 174  * override any trues.
 175  * Priority 0 means majority rules.  Ties will be broken with $tie
 176  *
 177  * @param string name the hook name
 178  * @param mixed parm the parameters for the hook function
 179  * @param int priority
 180  * @param bool tie
 181  * @return bool the result of the function
 182  */
 183 function boolean_hook_function($name,$parm=NULL,$priority=0,$tie=false) {
 184     global $squirrelmail_plugin_hooks, $currentHookName;
 185     $yea = 0;
 186     $nay = 0;
 187     $ret = $tie;
 188
 189     if (isset($squirrelmail_plugin_hooks[$name]) &&
 190         is_array($squirrelmail_plugin_hooks[$name])) {
 191
 192         /* Loop over the plugins that registered the hook */
 193         $currentHookName = $name;
 194         foreach ($squirrelmail_plugin_hooks[$name] as $function) {
 195             if (function_exists($function)) {
 196                 $ret = $function($parm);
 197                 if ($ret) {
 198                     $yea++;
 199                 } else {
 200                     $nay++;
 201                 }
 202             }
 203         }
 204         $currentHookName = '';
 205
 206         /* Examine the aftermath and assign the return value appropriately */
 207         if (($priority > 0) && ($yea)) {
 208             $ret = true;
 209         } elseif (($priority < 0) && ($nay)) {
 210             $ret = false;
 211         } elseif ($yea > $nay) {
 212             $ret = true;
 213         } elseif ($nay > $yea) {
 214             $ret = false;
 215         } else {
 216             // There's a tie, no action needed.
 217         }
 218         return $ret;
 219     }
 220     // If the code gets here, there was a problem - no hooks, etc.
 221     return NULL;
 222 }
 223
 224 /**
 225  * This function checks whether the user's USER_AGENT is known to
 226  * be broken. If so, returns true and the plugin is invisible to the
 227  * offending browser.
 228  * *** THIS IS A TEST FOR JAVASCRIPT SUPPORT ***
 229  * FIXME: This function needs to have its name changed!
 230  *
 231  * @return bool whether this browser properly supports JavaScript
 232  * @deprecated use checkForJavascript() since 1.5.1
 233  */
 234 function soupNazi(){
 235     return !checkForJavascript();
 236 }
 237
 238 /**
 239  * Check if plugin is enabled
 240  * @param string $plugin_name plugin name
 241  * @since 1.5.1
 242  * @return boolean
 243  */
 244 function is_plugin_enabled($plugin_name) {
 245   global $plugins;
 246
 247   /**
 248    * check if variable is empty. if var is not set, php empty
 249    * returns true without error notice.
 250    *
 251    * then check if it is an array
 252    */
 253   if (empty($plugins) || ! is_array($plugins))
 254     return false;
 255
 256   if ( in_array($plugin_name,$plugins) ) {
 257     return true;
 258   } else {
 259     return false;
 260   }
 261 }
 262
 263 /**
 264   * Check a plugin's version.
 265   *
 266   * Returns TRUE if the given plugin is installed,
 267   * activated and is at minimum version $a.$b.$c.
 268   * If any one of those conditions fails, FALSE
 269   * will be returned (careful of plugins that are
 270   * sufficiently versioned but are not activated).
 271   *
 272   * By overriding the default value of $force_inclusion,
 273   * this function will attempt to grab versioning
 274   * information from the given plugin even if it
 275   * is not activated (plugin still has to be
 276   * unpackaged and set in place in the plugins
 277   * directory).  Use with care - some plugins
 278   * might break SquirrelMail when this is used.
 279   *
 280   * Note that this function assumes plugin
 281   * versioning is consistently applied in the same
 282   * fashion that SquirrelMail versions are, with the
 283   * exception that an applicable SquirrelMail
 284   * version may be appended to the version number
 285   * (which will be ignored herein).  That is, plugin
 286   * version number schemes are expected in the following
 287   * format:  1.2.3, or 1.2.3-1.4.0.
 288   *
 289   * Any characters after the third number are discarded,
 290   * so formats such as the following will also work,
 291   * although extra information about beta versions can
 292   * possibly confuse the desired results of the version
 293   * check:  1.2.3-beta4, 1.2.3.RC2, and so forth.
 294   *
 295   * @since 1.5.2
 296   *
 297   * @param string plugin_name   name of the plugin to
 298   *                             check; must precisely
 299   *                             match the plugin
 300   *                             directory name
 301   * @param int  a               major version number
 302   * @param int  b               minor version number
 303   * @param int  c               release number
 304   * @param bool force_inclusion try to get version info
 305   *                             for plugins not activated?
 306   *                             (default FALSE)
 307   *
 308   * @return bool
 309   *
 310   */
 311 function check_plugin_version($plugin_name,
 312                               $a = 0, $b = 0, $c = 0,
 313                               $force_inclusion = FALSE)
 314 {
 315
 316    $info_function = $plugin_name . '_info';
 317    $version_function = $plugin_name . '_version';
 318    $plugin_info = array();
 319    $plugin_version = FALSE;
 320
 321
 322    // first attempt to find the plugin info function, wherein
 323    // the plugin version should be available
 324    //
 325    if (function_exists($info_function))
 326       $plugin_info = $info_function();
 327    else if ($force_inclusion
 328     && file_exists(SM_PATH . 'plugins/' . $plugin_name . '/setup.php'))
 329    {
 330       include_once(SM_PATH . 'plugins/' . $plugin_name . '/setup.php');
 331       if (function_exists($info_function))
 332          $plugin_info = $info_function();
 333    }
 334    if (!empty($plugin_info['version']))
 335       $plugin_version = $plugin_info['version'];
 336
 337
 338    // otherwise, look for older version function
 339    //
 340    if (!$plugin_version && function_exists($version_function))
 341          $plugin_version = $version_function();
 342
 343
 344    if (!$plugin_version) return FALSE;
 345
 346
 347    // now massage version number into something we understand
 348    //
 349    $plugin_version = trim(preg_replace(array('/[^0-9.]+.*$/', '/[^0-9.]/'),
 350                                        '', $plugin_version),
 351                           '.');
 352    $plugin_version = explode('.', $plugin_version);
 353    if (!isset($plugin_version[0])) $plugin_version[0] = 0;
 354    if (!isset($plugin_version[1])) $plugin_version[1] = 0;
 355    if (!isset($plugin_version[2])) $plugin_version[2] = 0;
 356 //   sm_print_r($plugin_version);
 357
 358
 359    // now test the version number
 360    //
 361    if ($plugin_version[0] < $a ||
 362       ($plugin_version[0] == $a && $plugin_version[1] < $b) ||
 363       ($plugin_version[0] == $a && $plugin_version[1] == $b && $plugin_version[2] < $c))
 364          return FALSE;
 365
 366
 367    return TRUE;
 368
 369 }
 370