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