Remove embedded HTML for displaying submit buttons on option pages, also display...
[squirrelmail.git] / functions / plugin.php
CommitLineData
7b086a80 1<?php
2
35586184 3/**
4 * plugin.php
5 *
35586184 6 * This file provides the framework for a plugin architecture.
7 *
8 * Documentation on how to write plugins might show up some time.
9 *
47ccfad4 10 * @copyright &copy; 1999-2006 The SquirrelMail Project Team
4b4abf93 11 * @license http://opensource.org/licenses/gpl-license.php GNU Public License
31841a9e 12 * @version $Id$
d6c32258 13 * @package squirrelmail
35586184 14 */
15
d6c32258 16/**
17 * This function adds a plugin.
18 * @param string $name Internal plugin name (ie. delete_move_next)
19 * @return void
20 */
0606ca1f 21function use_plugin ($name) {
bd9c880b 22 if (file_exists(SM_PATH . "plugins/$name/setup.php")) {
23 include_once(SM_PATH . "plugins/$name/setup.php");
8b56e282 24
25 /**
26 * As of SM 1.5.2, plugin hook registration is statically
27 * accomplished using the configuration utility (config/conf.pl).
28 * And this code is deprecated (but let's keep it until
29 * the new registration system is proven).
30 *
31 */
32 //$function = "squirrelmail_plugin_init_$name";
33 //if (function_exists($function)) {
34 // $function();
35 //}
2d367c68 36 }
0606ca1f 37}
2d367c68 38
d6c32258 39/**
40 * This function executes a hook.
41 * @param string $name Name of hook to fire
42 * @return mixed $data
43 */
31524bcd 44function do_hook ($name) {
eb1f02bc 45 global $squirrelmail_plugin_hooks, $currentHookName;
0606ca1f 46 $data = func_get_args();
eb1f02bc 47 $currentHookName = $name;
a3439b27 48
0606ca1f 49 if (isset($squirrelmail_plugin_hooks[$name])
50 && is_array($squirrelmail_plugin_hooks[$name])) {
8b56e282 51 foreach ($squirrelmail_plugin_hooks[$name] as $plugin_name => $function) {
52 use_plugin($plugin_name);
0606ca1f 53 /* Add something to set correct gettext domain for plugin. */
54 if (function_exists($function)) {
31524bcd 55 $function($data);
56 }
57 }
58 }
59
eb1f02bc 60 $currentHookName = '';
61
31524bcd 62 /* Variable-length argument lists have a slight problem when */
63 /* passing values by reference. Pity. This is a workaround. */
64 return $data;
65}
66
8b096f0a 67/**
e900d242 68 * This function executes a hook and allows for parameters to be
69 * passed, wherein each plugin can modify the parameters before
70 * they are passed to the next funciton. Whether or not the
71 * parameters are modified, plugins on this hook should always
72 * return the given parameters.
73 *
74 * @param string name the name of the hook
75 * @param mixed param the parameters to pass to the hook function
76 * @return mixed the possibly modified hook parameters
77 */
78function filter_hook_function($name,$parm=NULL) {
79 global $squirrelmail_plugin_hooks, $currentHookName;
e900d242 80 $currentHookName = $name;
81
82 if (isset($squirrelmail_plugin_hooks[$name])
83 && is_array($squirrelmail_plugin_hooks[$name])) {
8b56e282 84 foreach ($squirrelmail_plugin_hooks[$name] as $plugin_name => $function) {
85 use_plugin($plugin_name);
e900d242 86 /* Add something to set correct gettext domain for plugin. */
87 if (function_exists($function)) {
88 $parm = $function($parm);
89 }
90 }
91 }
92
93 $currentHookName = '';
94
95 /* Variable-length argument lists have a slight problem when */
96 /* passing values by reference. Pity. This is a workaround. */
97 return $parm;
98}
99
100/**
8b096f0a 101 * This function executes a hook and allows for parameters to be passed.
102 *
103 * @param string name the name of the hook
104 * @param mixed param the parameters to pass to the hook function
105 * @return mixed the return value of the hook function
106 */
31524bcd 107function do_hook_function($name,$parm=NULL) {
eb1f02bc 108 global $squirrelmail_plugin_hooks, $currentHookName;
31524bcd 109 $ret = '';
eb1f02bc 110 $currentHookName = $name;
31524bcd 111
112 if (isset($squirrelmail_plugin_hooks[$name])
113 && is_array($squirrelmail_plugin_hooks[$name])) {
8b56e282 114 foreach ($squirrelmail_plugin_hooks[$name] as $plugin_name => $function) {
115 use_plugin($plugin_name);
31524bcd 116 /* Add something to set correct gettext domain for plugin. */
117 if (function_exists($function)) {
118 $ret = $function($parm);
dd389be5 119 }
2d367c68 120 }
2d367c68 121 }
7b086a80 122
eb1f02bc 123 $currentHookName = '';
124
0606ca1f 125 /* Variable-length argument lists have a slight problem when */
126 /* passing values by reference. Pity. This is a workaround. */
2586d588 127 return $ret;
0606ca1f 128}
7b086a80 129
8b096f0a 130/**
7edd8ad6 131 * This function executes a hook, allows for parameters to be passed,
132 * and looks for an array returned from each plugin: each array is
133 * then merged into one and returned to the core hook location.
134 *
135 * Note that unlike PHP's array_merge function, matching array keys
136 * will not overwrite each other, instead, values under such keys
137 * will be concatenated if they are both strings, or merged if they
138 * are arrays (in the same (non-overwrite) manner recursively).
139 *
140 * Plugins returning non-arrays (strings, objects, etc) will have
141 * their output added to the end of the ultimate return array,
142 * unless ALL values returned are strings, in which case one string
143 * with all returned strings concatenated together is returned.
8b096f0a 144 *
145 * @param string name the name of the hook
7edd8ad6 146 * @param mixed param the parameters to pass to the hook function
147 *
148 * @return mixed the merged return arrays or strings of each
149 * plugin on this hook
150 *
8b096f0a 151 */
09ac2863 152function concat_hook_function($name,$parm=NULL) {
eb1f02bc 153 global $squirrelmail_plugin_hooks, $currentHookName;
bbac5629 154 $ret = '';
eb1f02bc 155 $currentHookName = $name;
31524bcd 156
09ac2863 157 if (isset($squirrelmail_plugin_hooks[$name])
158 && is_array($squirrelmail_plugin_hooks[$name])) {
8b56e282 159 foreach ($squirrelmail_plugin_hooks[$name] as $plugin_name => $function) {
160 use_plugin($plugin_name);
7edd8ad6 161 /* Add something to set correct gettext domain for plugin. */
09ac2863 162 if (function_exists($function)) {
5fba72db 163 $plugin_ret = $function($parm);
164 if (!empty($plugin_ret)) {
165 $ret = sqm_array_merge($ret, $plugin_ret);
166 }
09ac2863 167 }
168 }
169 }
170
eb1f02bc 171 $currentHookName = '';
172
09ac2863 173 /* Variable-length argument lists have a slight problem when */
174 /* passing values by reference. Pity. This is a workaround. */
175 return $ret;
176}
cd7fc9e6 177
178/**
5576644b 179 * This function is used for hooks which are to return true or
180 * false. If $priority is > 0, any one or more trues will override
181 * any falses. If $priority < 0, then one or more falses will
182 * override any trues.
8b096f0a 183 * Priority 0 means majority rules. Ties will be broken with $tie
184 *
185 * @param string name the hook name
186 * @param mixed parm the parameters for the hook function
187 * @param int priority
188 * @param bool tie
189 * @return bool the result of the function
190 */
5576644b 191function boolean_hook_function($name,$parm=NULL,$priority=0,$tie=false) {
eb1f02bc 192 global $squirrelmail_plugin_hooks, $currentHookName;
5576644b 193 $yea = 0;
194 $nay = 0;
195 $ret = $tie;
196
197 if (isset($squirrelmail_plugin_hooks[$name]) &&
198 is_array($squirrelmail_plugin_hooks[$name])) {
199
200 /* Loop over the plugins that registered the hook */
eb1f02bc 201 $currentHookName = $name;
8b56e282 202 foreach ($squirrelmail_plugin_hooks[$name] as $plugin_name => $function) {
203 use_plugin($plugin_name);
5576644b 204 if (function_exists($function)) {
205 $ret = $function($parm);
206 if ($ret) {
207 $yea++;
208 } else {
209 $nay++;
210 }
211 }
212 }
eb1f02bc 213 $currentHookName = '';
5576644b 214
215 /* Examine the aftermath and assign the return value appropriately */
216 if (($priority > 0) && ($yea)) {
217 $ret = true;
218 } elseif (($priority < 0) && ($nay)) {
219 $ret = false;
220 } elseif ($yea > $nay) {
221 $ret = true;
222 } elseif ($nay > $yea) {
223 $ret = false;
224 } else {
225 // There's a tie, no action needed.
226 }
227 return $ret;
228 }
229 // If the code gets here, there was a problem - no hooks, etc.
230 return NULL;
231}
232
233/**
cd7fc9e6 234 * This function checks whether the user's USER_AGENT is known to
235 * be broken. If so, returns true and the plugin is invisible to the
236 * offending browser.
7349fa12 237 * *** THIS IS A TEST FOR JAVASCRIPT SUPPORT ***
94ba79ce 238 * FIXME: This function needs to have its name changed!
8b096f0a 239 *
240 * @return bool whether this browser properly supports JavaScript
ccacde36 241 * @deprecated use checkForJavascript() since 1.5.1
cd7fc9e6 242 */
243function soupNazi(){
7349fa12 244 return !checkForJavascript();
cd7fc9e6 245}
fe0aa536 246
247/**
248 * Check if plugin is enabled
249 * @param string $plugin_name plugin name
250 * @since 1.5.1
251 * @return boolean
252 */
253function is_plugin_enabled($plugin_name) {
254 global $plugins;
255
e83cfcef 256 /**
202bcbcc 257 * check if variable is empty. if var is not set, php empty
e495bd68 258 * returns true without error notice.
259 *
260 * then check if it is an array
e83cfcef 261 */
e495bd68 262 if (empty($plugins) || ! is_array($plugins))
fe0aa536 263 return false;
264
265 if ( in_array($plugin_name,$plugins) ) {
266 return true;
267 } else {
268 return false;
269 }
270}
d99b6c56 271
272/**
273 * Check a plugin's version.
274 *
275 * Returns TRUE if the given plugin is installed,
276 * activated and is at minimum version $a.$b.$c.
277 * If any one of those conditions fails, FALSE
278 * will be returned (careful of plugins that are
279 * sufficiently versioned but are not activated).
280 *
281 * By overriding the default value of $force_inclusion,
282 * this function will attempt to grab versioning
283 * information from the given plugin even if it
284 * is not activated (plugin still has to be
285 * unpackaged and set in place in the plugins
286 * directory). Use with care - some plugins
287 * might break SquirrelMail when this is used.
288 *
289 * Note that this function assumes plugin
290 * versioning is consistently applied in the same
291 * fashion that SquirrelMail versions are, with the
292 * exception that an applicable SquirrelMail
293 * version may be appended to the version number
294 * (which will be ignored herein). That is, plugin
295 * version number schemes are expected in the following
296 * format: 1.2.3, or 1.2.3-1.4.0.
297 *
298 * Any characters after the third number are discarded,
299 * so formats such as the following will also work,
300 * although extra information about beta versions can
301 * possibly confuse the desired results of the version
302 * check: 1.2.3-beta4, 1.2.3.RC2, and so forth.
303 *
b2a6a14c 304 * @since 1.5.2
d99b6c56 305 *
306 * @param string plugin_name name of the plugin to
307 * check; must precisely
308 * match the plugin
309 * directory name
310 * @param int a major version number
311 * @param int b minor version number
312 * @param int c release number
313 * @param bool force_inclusion try to get version info
314 * for plugins not activated?
315 * (default FALSE)
316 *
317 * @return bool
318 *
319 */
320function check_plugin_version($plugin_name,
321 $a = 0, $b = 0, $c = 0,
322 $force_inclusion = FALSE)
323{
324
6b6bcf00 325 $info_function = $plugin_name . '_info';
d99b6c56 326 $version_function = $plugin_name . '_version';
6b6bcf00 327 $plugin_info = array();
d99b6c56 328 $plugin_version = FALSE;
329
330
6b6bcf00 331 // first attempt to find the plugin info function, wherein
332 // the plugin version should be available
d99b6c56 333 //
6b6bcf00 334 if (function_exists($info_function))
335 $plugin_info = $info_function();
d99b6c56 336 else if ($force_inclusion
337 && file_exists(SM_PATH . 'plugins/' . $plugin_name . '/setup.php'))
338 {
339 include_once(SM_PATH . 'plugins/' . $plugin_name . '/setup.php');
6b6bcf00 340 if (function_exists($info_function))
341 $plugin_info = $info_function();
d99b6c56 342 }
6b6bcf00 343 if (!empty($plugin_info['version']))
344 $plugin_version = $plugin_info['version'];
345
346
347 // otherwise, look for older version function
348 //
349 if (!$plugin_version && function_exists($version_function))
350 $plugin_version = $version_function();
351
d99b6c56 352
353 if (!$plugin_version) return FALSE;
354
355
356 // now massage version number into something we understand
357 //
358 $plugin_version = trim(preg_replace(array('/[^0-9.]+.*$/', '/[^0-9.]/'),
359 '', $plugin_version),
360 '.');
361 $plugin_version = explode('.', $plugin_version);
362 if (!isset($plugin_version[0])) $plugin_version[0] = 0;
363 if (!isset($plugin_version[1])) $plugin_version[1] = 0;
364 if (!isset($plugin_version[2])) $plugin_version[2] = 0;
365// sm_print_r($plugin_version);
366
367
368 // now test the version number
369 //
370 if ($plugin_version[0] < $a ||
371 ($plugin_version[0] == $a && $plugin_version[1] < $b) ||
372 ($plugin_version[0] == $a && $plugin_version[1] == $b && $plugin_version[2] < $c))
373 return FALSE;
374
375
376 return TRUE;
377
378}
379