functions/plugin.php

   1 <?php
   2
   3 /**
   4  * plugin.php
   5  *
   6  * Copyright (c) 1999-2005 The SquirrelMail Project Team
   7  * Licensed under the GNU GPL. For full terms see the file COPYING.
   8  *
   9  * This file provides the framework for a plugin architecture.
  10  *
  11  * Documentation on how to write plugins might show up some time.
  12  *
  13  * @version $Id$
  14  * @package squirrelmail
  15  */
  16
  17 /** Everything needs global.. */
  18 require_once(SM_PATH . 'functions/global.php');
  19 require_once(SM_PATH . 'functions/prefs.php');
  20
  21 global $squirrelmail_plugin_hooks;
  22 $squirrelmail_plugin_hooks = array();
  23
  24 /**
  25  * This function adds a plugin.
  26  * @param string $name Internal plugin name (ie. delete_move_next)
  27  * @return void
  28  */
  29 function use_plugin ($name) {
  30     if (file_exists(SM_PATH . "plugins/$name/setup.php")) {
  31         include_once(SM_PATH . "plugins/$name/setup.php");
  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 $function) {
  52             /* Add something to set correct gettext domain for plugin. */
  53             if (function_exists($function)) {
  54                 $function($data);
  55             }
  56         }
  57     }
  58
  59     $currentHookName = '';
  60
  61     /* Variable-length argument lists have a slight problem when */
  62     /* passing values by reference. Pity. This is a workaround.  */
  63     return $data;
  64 }
  65
  66 /**
  67  * This function executes a hook and allows for parameters to be passed.
  68  *
  69  * @param string name the name of the hook
  70  * @param mixed param the parameters to pass to the hook function
  71  * @return mixed the return value of the hook function
  72  */
  73 function do_hook_function($name,$parm=NULL) {
  74     global $squirrelmail_plugin_hooks, $currentHookName;
  75     $ret = '';
  76     $currentHookName = $name;
  77
  78     if (isset($squirrelmail_plugin_hooks[$name])
  79           && is_array($squirrelmail_plugin_hooks[$name])) {
  80         foreach ($squirrelmail_plugin_hooks[$name] as $function) {
  81             /* Add something to set correct gettext domain for plugin. */
  82             if (function_exists($function)) {
  83                 $ret = $function($parm);
  84             }
  85         }
  86     }
  87
  88     $currentHookName = '';
  89
  90     /* Variable-length argument lists have a slight problem when */
  91     /* passing values by reference. Pity. This is a workaround.  */
  92     return $ret;
  93 }
  94
  95 /**
  96  * This function executes a hook, concatenating the results of each
  97  * plugin that has the hook defined.
  98  *
  99  * @param string name the name of the hook
 100  * @param mixed parm optional hook function parameters
 101  * @return string a concatenation of the results of each plugin function
 102  */
 103 function concat_hook_function($name,$parm=NULL) {
 104     global $squirrelmail_plugin_hooks, $currentHookName;
 105     $ret = '';
 106     $currentHookName = $name;
 107
 108     if (isset($squirrelmail_plugin_hooks[$name])
 109           && is_array($squirrelmail_plugin_hooks[$name])) {
 110         foreach ($squirrelmail_plugin_hooks[$name] as $function) {
 111             /* Concatenate results from hook. */
 112             if (function_exists($function)) {
 113                 $ret .= $function($parm);
 114             }
 115         }
 116     }
 117
 118     $currentHookName = '';
 119
 120     /* Variable-length argument lists have a slight problem when */
 121     /* passing values by reference. Pity. This is a workaround.  */
 122     return $ret;
 123 }
 124
 125 /**
 126  * This function is used for hooks which are to return true or
 127  * false. If $priority is > 0, any one or more trues will override
 128  * any falses. If $priority < 0, then one or more falses will
 129  * override any trues.
 130  * Priority 0 means majority rules.  Ties will be broken with $tie
 131  *
 132  * @param string name the hook name
 133  * @param mixed parm the parameters for the hook function
 134  * @param int priority
 135  * @param bool tie
 136  * @return bool the result of the function
 137  */
 138 function boolean_hook_function($name,$parm=NULL,$priority=0,$tie=false) {
 139     global $squirrelmail_plugin_hooks, $currentHookName;
 140     $yea = 0;
 141     $nay = 0;
 142     $ret = $tie;
 143
 144     if (isset($squirrelmail_plugin_hooks[$name]) &&
 145         is_array($squirrelmail_plugin_hooks[$name])) {
 146
 147         /* Loop over the plugins that registered the hook */
 148         $currentHookName = $name;
 149         foreach ($squirrelmail_plugin_hooks[$name] as $function) {
 150             if (function_exists($function)) {
 151                 $ret = $function($parm);
 152                 if ($ret) {
 153                     $yea++;
 154                 } else {
 155                     $nay++;
 156                 }
 157             }
 158         }
 159         $currentHookName = '';
 160
 161         /* Examine the aftermath and assign the return value appropriately */
 162         if (($priority > 0) && ($yea)) {
 163             $ret = true;
 164         } elseif (($priority < 0) && ($nay)) {
 165             $ret = false;
 166         } elseif ($yea > $nay) {
 167             $ret = true;
 168         } elseif ($nay > $yea) {
 169             $ret = false;
 170         } else {
 171             // There's a tie, no action needed.
 172         }
 173         return $ret;
 174     }
 175     // If the code gets here, there was a problem - no hooks, etc.
 176     return NULL;
 177 }
 178
 179 /**
 180  * This function checks whether the user's USER_AGENT is known to
 181  * be broken. If so, returns true and the plugin is invisible to the
 182  * offending browser.
 183  * *** THIS IS A TEST FOR JAVASCRIPT SUPPORT ***
 184  * FIXME: This function needs to have its name changed!
 185  *
 186  * @return bool whether this browser properly supports JavaScript
 187  * @deprecated use checkForJavascript() since 1.5.1
 188  */
 189 function soupNazi(){
 190     return !checkForJavascript();
 191 }
 192 /*************************************/
 193 /*** MAIN PLUGIN LOADING CODE HERE ***/
 194 /*************************************/
 195
 196 /* On startup, register all plugins configured for use. */
 197 if (isset($plugins) && is_array($plugins)) {
 198     foreach ($plugins as $name) {
 199         use_plugin($name);
 200     }
 201 }
 202
 203 ?>