Fix typo
[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 *
4b5049de 10 * @copyright &copy; 1999-2007 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/**
d849b570 40 * This function executes a plugin hook.
41 *
42 * It includes an arbitrary return value that is managed by
43 * all plugins on the same hook and returned to the core hook
44 * location.
45 *
46 * The desired format of the return value should be defined
47 * by the context in which the hook is called.
48 *
49 * Note that the master return value for this hook is passed
50 * to each plugin after the main argument(s) value/array as a
51 * convenience only - to show what the current return value is
52 * even though it is liable to be changed by other plugins.
53 *
54 * If any plugin on this hook wants to modify the $args
55 * plugin parameter, it simply has to use call-by-reference
56 * syntax in the hook function that it has registered for the
57 * current hook. Note that this is in addition to (entirely
58 * independent of) the return value for this hook.
59 *
60 * @param string $name Name of hook being executed
61 * @param mixed $args A single value or an array of arguments
62 * that are to be passed to all plugins
63 * operating off the hook being called.
64 * Note that this argument is passed by
65 * reference thus it is liable to be
66 * changed after the hook completes.
67 *
68 * @return mixed The return value that is managed by the plugins
69 * on the current hook.
8b096f0a 70 *
8b096f0a 71 */
d849b570 72function do_hook($name, &$args) {
73
eb1f02bc 74 global $squirrelmail_plugin_hooks, $currentHookName;
eb1f02bc 75 $currentHookName = $name;
d849b570 76 $ret = NULL;
31524bcd 77
78 if (isset($squirrelmail_plugin_hooks[$name])
79 && is_array($squirrelmail_plugin_hooks[$name])) {
8b56e282 80 foreach ($squirrelmail_plugin_hooks[$name] as $plugin_name => $function) {
81 use_plugin($plugin_name);
31524bcd 82 if (function_exists($function)) {
0fe6826d 83 $ret = $function($args, $ret);
dd389be5 84 }
2d367c68 85 }
2d367c68 86 }
7b086a80 87
eb1f02bc 88 $currentHookName = '';
2586d588 89 return $ret;
d849b570 90
0606ca1f 91}
7b086a80 92
8b096f0a 93/**
d849b570 94 * This function executes a hook that allows for an arbitrary
95 * return value from each plugin that will be merged into one
96 * array (or one string if all return values are strings) and
97 * returned to the core hook location.
7edd8ad6 98 *
99 * Note that unlike PHP's array_merge function, matching array keys
100 * will not overwrite each other, instead, values under such keys
101 * will be concatenated if they are both strings, or merged if they
102 * are arrays (in the same (non-overwrite) manner recursively).
103 *
104 * Plugins returning non-arrays (strings, objects, etc) will have
105 * their output added to the end of the ultimate return array,
106 * unless ALL values returned are strings, in which case one string
0db60ced 107 * with all returned strings concatenated together is returned
108 * (unless $force_array is TRUE).
8b096f0a 109 *
d849b570 110 * If any plugin on this hook wants to modify the $args
111 * plugin parameter, it simply has to use call-by-reference
112 * syntax in the hook function that it has registered for the
113 * current hook. Note that this is in addition to (entirely
114 * independent of) the return value for this hook.
115 *
0db60ced 116 * @param string $name Name of hook being executed
117 * @param mixed $args A single value or an array of arguments
118 * that are to be passed to all plugins
119 * operating off the hook being called.
120 * Note that this argument is passed by
121 * reference thus it is liable to be
122 * changed after the hook completes.
123 * @param boolean $force_array When TRUE, guarantees the return
124 * value will ALWAYS be an array,
125 * (simple strings will be forced
126 * into a one-element array).
127 * When FALSE, behavior is as
128 * described above (OPTIONAL;
129 * default behavior is to return
130 * mixed - array or string).
7edd8ad6 131 *
132 * @return mixed the merged return arrays or strings of each
d849b570 133 * plugin on this hook.
7edd8ad6 134 *
8b096f0a 135 */
0db60ced 136function concat_hook_function($name, &$args, $force_array=FALSE) {
d849b570 137
eb1f02bc 138 global $squirrelmail_plugin_hooks, $currentHookName;
eb1f02bc 139 $currentHookName = $name;
d849b570 140 $ret = '';
31524bcd 141
09ac2863 142 if (isset($squirrelmail_plugin_hooks[$name])
143 && is_array($squirrelmail_plugin_hooks[$name])) {
8b56e282 144 foreach ($squirrelmail_plugin_hooks[$name] as $plugin_name => $function) {
145 use_plugin($plugin_name);
09ac2863 146 if (function_exists($function)) {
d849b570 147 $plugin_ret = $function($args);
5fba72db 148 if (!empty($plugin_ret)) {
149 $ret = sqm_array_merge($ret, $plugin_ret);
150 }
09ac2863 151 }
152 }
153 }
154
0db60ced 155 if ($force_array && is_string($ret)) {
156 $ret = array($ret);
157 }
158
eb1f02bc 159 $currentHookName = '';
09ac2863 160 return $ret;
d849b570 161
09ac2863 162}
cd7fc9e6 163
164/**
5576644b 165 * This function is used for hooks which are to return true or
166 * false. If $priority is > 0, any one or more trues will override
167 * any falses. If $priority < 0, then one or more falses will
168 * override any trues.
8b096f0a 169 * Priority 0 means majority rules. Ties will be broken with $tie
170 *
d849b570 171 * If any plugin on this hook wants to modify the $args
172 * plugin parameter, it simply has to use call-by-reference
173 * syntax in the hook function that it has registered for the
174 * current hook. Note that this is in addition to (entirely
175 * independent of) the return value for this hook.
176 *
177 * @param string $name The hook name
178 * @param mixed $args A single value or an array of arguments
179 * that are to be passed to all plugins
180 * operating off the hook being called.
181 * Note that this argument is passed by
182 * reference thus it is liable to be
183 * changed after the hook completes.
184 * @param int $priority See explanation above
185 * @param boolean $tie See explanation above
186 *
187 * @return boolean The result of the function
188 *
8b096f0a 189 */
d849b570 190function boolean_hook_function($name, &$args, $priority=0, $tie=false) {
191
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)) {
d849b570 205 $ret = $function($args);
5576644b 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;
d849b570 231
5576644b 232}
233
234/**
141105fc 235 * Do not use, use checkForJavascript() instead.
236 *
cd7fc9e6 237 * This function checks whether the user's USER_AGENT is known to
238 * be broken. If so, returns true and the plugin is invisible to the
239 * offending browser.
7349fa12 240 * *** THIS IS A TEST FOR JAVASCRIPT SUPPORT ***
8b096f0a 241 *
242 * @return bool whether this browser properly supports JavaScript
ccacde36 243 * @deprecated use checkForJavascript() since 1.5.1
cd7fc9e6 244 */
245function soupNazi(){
7349fa12 246 return !checkForJavascript();
cd7fc9e6 247}
fe0aa536 248
249/**
250 * Check if plugin is enabled
251 * @param string $plugin_name plugin name
252 * @since 1.5.1
253 * @return boolean
254 */
255function is_plugin_enabled($plugin_name) {
256 global $plugins;
257
e83cfcef 258 /**
202bcbcc 259 * check if variable is empty. if var is not set, php empty
e495bd68 260 * returns true without error notice.
261 *
262 * then check if it is an array
e83cfcef 263 */
e495bd68 264 if (empty($plugins) || ! is_array($plugins))
fe0aa536 265 return false;
266
267 if ( in_array($plugin_name,$plugins) ) {
268 return true;
269 } else {
270 return false;
271 }
272}
d99b6c56 273
274/**
d95b10b3 275 * Get a plugin's version.
276 *
277 * Determines and returns a plugin's version.
278 *
279 * By default, the desired plugin must be currently
280 * activated, and if it is not, this function will
281 * return FALSE. By overriding the default value
282 * of $force_inclusion, this function will attempt
283 * to grab versioning information from the given
284 * plugin even if it is not activated (plugin still
285 * has to be unpackaged and set in place in the
286 * plugins directory). Use with care - some plugins
287 * might break SquirrelMail when this is used.
288 *
9c2f2d2e 289 * By turning on the $do_parse argument, the version
290 * string will be parsed by SquirrelMail into a
291 * SquirrelMail-compatible version string (such as
292 * "1.2.3") if it is not already.
293 *
294 * Note that this assumes plugin versioning is
295 * consistently applied in the same fashion that
296 * SquirrelMail versions are, with the exception that
297 * an applicable SquirrelMail version may be appended
298 * to the version number (which will be ignored herein).
299 * That is, plugin version number schemes are expected
300 * in the following format: 1.2.3, or 1.2.3-1.4.0.
301 *
302 * Any characters after the third version number
303 * indicating things such as beta or release candidate
304 * versions are discarded, so formats such as the
305 * following will also work, although extra information
306 * about beta versions can possibly confuse the desired
307 * results of the version check: 1.2.3-beta4, 1.2.3.RC2,
308 * and so forth.
309 *
d95b10b3 310 * @since 1.5.2
311 *
312 * @param string plugin_name name of the plugin to
313 * check; must precisely
314 * match the plugin
315 * directory name
316 * @param bool force_inclusion try to get version info
317 * for plugins not activated?
318 * (default FALSE)
9c2f2d2e 319 * @param bool do_parse return the plugin version
320 * in SquirrelMail-compatible
321 * format (default FALSE)
d95b10b3 322 *
323 * @return mixed The plugin version string if found, otherwise,
324 * boolean FALSE is returned indicating that no
325 * version information could be found for the plugin.
326 *
327 */
9c2f2d2e 328function get_plugin_version($plugin_name, $force_inclusion = FALSE, $do_parse = FALSE)
d95b10b3 329{
330
331 $info_function = $plugin_name . '_info';
332 $version_function = $plugin_name . '_version';
333 $plugin_info = array();
334 $plugin_version = FALSE;
335
336
337 // first attempt to find the plugin info function, wherein
338 // the plugin version should be available
339 //
340 if (function_exists($info_function))
341 $plugin_info = $info_function();
342 else if ($force_inclusion
343 && file_exists(SM_PATH . 'plugins/' . $plugin_name . '/setup.php'))
344 {
345 include_once(SM_PATH . 'plugins/' . $plugin_name . '/setup.php');
346 if (function_exists($info_function))
347 $plugin_info = $info_function();
348 }
349 if (!empty($plugin_info['version']))
350 $plugin_version = $plugin_info['version'];
351
352
353 // otherwise, look for older version function
354 //
355 if (!$plugin_version && function_exists($version_function))
356 $plugin_version = $version_function();
357
358
9c2f2d2e 359 if ($plugin_version && $do_parse)
360 {
361
362 // massage version number into something we understand
363 //
364 // the first regexp strips everything and anything that follows
365 // the first occurance of a non-digit (or non decimal point), so
366 // beware that putting letters in the middle of a version string
367 // will effectively truncate the version string right there (but
368 // this also just helps remove the SquirrelMail version part off
369 // of versions such as "1.2.3-1.4.4")
370 //
371 // the second regexp just strips out non-digits/non-decimal points
372 // (and might be redundant(?))
373 //
374 // the regexps are wrapped in a trim that makes sure the version
375 // does not start or end with a decimal point
376 //
377 $plugin_version = trim(preg_replace(array('/[^0-9.]+.*$/', '/[^0-9.]/'),
378 '', $plugin_version),
379 '.');
380
381 }
382
d95b10b3 383 return $plugin_version;
384
385}
386
387/**
d99b6c56 388 * Check a plugin's version.
389 *
390 * Returns TRUE if the given plugin is installed,
391 * activated and is at minimum version $a.$b.$c.
392 * If any one of those conditions fails, FALSE
393 * will be returned (careful of plugins that are
394 * sufficiently versioned but are not activated).
395 *
396 * By overriding the default value of $force_inclusion,
397 * this function will attempt to grab versioning
398 * information from the given plugin even if it
9c2f2d2e 399 * is not activated (the plugin still has to be
d99b6c56 400 * unpackaged and set in place in the plugins
401 * directory). Use with care - some plugins
402 * might break SquirrelMail when this is used.
403 *
404 * Note that this function assumes plugin
405 * versioning is consistently applied in the same
406 * fashion that SquirrelMail versions are, with the
407 * exception that an applicable SquirrelMail
408 * version may be appended to the version number
409 * (which will be ignored herein). That is, plugin
410 * version number schemes are expected in the following
411 * format: 1.2.3, or 1.2.3-1.4.0.
412 *
9c2f2d2e 413 * Any characters after the third number indicating
414 * things such as beta or release candidate versions
415 * are discarded, so formats such as the following
416 * will also work, although extra information about
417 * beta versions can possibly confuse the desired results
418 * of the version check: 1.2.3-beta4, 1.2.3.RC2, and so forth.
d99b6c56 419 *
b2a6a14c 420 * @since 1.5.2
d99b6c56 421 *
422 * @param string plugin_name name of the plugin to
423 * check; must precisely
424 * match the plugin
425 * directory name
426 * @param int a major version number
427 * @param int b minor version number
428 * @param int c release number
429 * @param bool force_inclusion try to get version info
430 * for plugins not activated?
431 * (default FALSE)
432 *
433 * @return bool
434 *
435 */
436function check_plugin_version($plugin_name,
437 $a = 0, $b = 0, $c = 0,
438 $force_inclusion = FALSE)
439{
440
9c2f2d2e 441 $plugin_version = get_plugin_version($plugin_name, $force_inclusion, TRUE);
d99b6c56 442 if (!$plugin_version) return FALSE;
443
444
9c2f2d2e 445 // split the version string into sections delimited by
446 // decimal points, and make sure we have three sections
d99b6c56 447 //
d99b6c56 448 $plugin_version = explode('.', $plugin_version);
449 if (!isset($plugin_version[0])) $plugin_version[0] = 0;
450 if (!isset($plugin_version[1])) $plugin_version[1] = 0;
451 if (!isset($plugin_version[2])) $plugin_version[2] = 0;
452// sm_print_r($plugin_version);
453
454
455 // now test the version number
456 //
457 if ($plugin_version[0] < $a ||
458 ($plugin_version[0] == $a && $plugin_version[1] < $b) ||
459 ($plugin_version[0] == $a && $plugin_version[1] == $b && $plugin_version[2] < $c))
460 return FALSE;
461
462
463 return TRUE;
464
465}
466