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