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