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