Source for file plugin.php

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

Documentation generated on Sat, 07 Oct 2006 16:13:04 +0300 by phpDocumentor 1.3.0RC6