Massive update to plugin system architecture. Please test! Not all core plugins...
[squirrelmail.git] / 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
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 //}
36 }
37 }
38
39 /**
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.
70 *
71 */
72 function do_hook($name, &$args) {
73
74 global $squirrelmail_plugin_hooks, $currentHookName;
75 $currentHookName = $name;
76 $ret = NULL;
77
78 if (isset($squirrelmail_plugin_hooks[$name])
79 && is_array($squirrelmail_plugin_hooks[$name])) {
80 foreach ($squirrelmail_plugin_hooks[$name] as $plugin_name => $function) {
81 use_plugin($plugin_name);
82 if (function_exists($function)) {
83 $ret = $function($args, $ret);
84 }
85 }
86 }
87
88 $currentHookName = '';
89 return $ret;
90
91 }
92
93 /**
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.
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
107 * with all returned strings concatenated together is returned.
108 *
109 * If any plugin on this hook wants to modify the $args
110 * plugin parameter, it simply has to use call-by-reference
111 * syntax in the hook function that it has registered for the
112 * current hook. Note that this is in addition to (entirely
113 * independent of) the return value for this hook.
114 *
115 * @param string $name Name of hook being executed
116 * @param mixed $args A single value or an array of arguments
117 * that are to be passed to all plugins
118 * operating off the hook being called.
119 * Note that this argument is passed by
120 * reference thus it is liable to be
121 * changed after the hook completes.
122 *
123 * @return mixed the merged return arrays or strings of each
124 * plugin on this hook.
125 *
126 */
127 function concat_hook_function($name, &$args) {
128
129 global $squirrelmail_plugin_hooks, $currentHookName;
130 $currentHookName = $name;
131 $ret = '';
132
133 if (isset($squirrelmail_plugin_hooks[$name])
134 && is_array($squirrelmail_plugin_hooks[$name])) {
135 foreach ($squirrelmail_plugin_hooks[$name] as $plugin_name => $function) {
136 use_plugin($plugin_name);
137 if (function_exists($function)) {
138 $plugin_ret = $function($args);
139 if (!empty($plugin_ret)) {
140 $ret = sqm_array_merge($ret, $plugin_ret);
141 }
142 }
143 }
144 }
145
146 $currentHookName = '';
147 return $ret;
148
149 }
150
151 /**
152 * This function is used for hooks which are to return true or
153 * false. If $priority is > 0, any one or more trues will override
154 * any falses. If $priority < 0, then one or more falses will
155 * override any trues.
156 * Priority 0 means majority rules. Ties will be broken with $tie
157 *
158 * If any plugin on this hook wants to modify the $args
159 * plugin parameter, it simply has to use call-by-reference
160 * syntax in the hook function that it has registered for the
161 * current hook. Note that this is in addition to (entirely
162 * independent of) the return value for this hook.
163 *
164 * @param string $name The hook name
165 * @param mixed $args A single value or an array of arguments
166 * that are to be passed to all plugins
167 * operating off the hook being called.
168 * Note that this argument is passed by
169 * reference thus it is liable to be
170 * changed after the hook completes.
171 * @param int $priority See explanation above
172 * @param boolean $tie See explanation above
173 *
174 * @return boolean The result of the function
175 *
176 */
177 function boolean_hook_function($name, &$args, $priority=0, $tie=false) {
178
179 global $squirrelmail_plugin_hooks, $currentHookName;
180 $yea = 0;
181 $nay = 0;
182 $ret = $tie;
183
184 if (isset($squirrelmail_plugin_hooks[$name]) &&
185 is_array($squirrelmail_plugin_hooks[$name])) {
186
187 /* Loop over the plugins that registered the hook */
188 $currentHookName = $name;
189 foreach ($squirrelmail_plugin_hooks[$name] as $plugin_name => $function) {
190 use_plugin($plugin_name);
191 if (function_exists($function)) {
192 $ret = $function($args);
193 if ($ret) {
194 $yea++;
195 } else {
196 $nay++;
197 }
198 }
199 }
200 $currentHookName = '';
201
202 /* Examine the aftermath and assign the return value appropriately */
203 if (($priority > 0) && ($yea)) {
204 $ret = true;
205 } elseif (($priority < 0) && ($nay)) {
206 $ret = false;
207 } elseif ($yea > $nay) {
208 $ret = true;
209 } elseif ($nay > $yea) {
210 $ret = false;
211 } else {
212 // There's a tie, no action needed.
213 }
214 return $ret;
215 }
216 // If the code gets here, there was a problem - no hooks, etc.
217 return NULL;
218
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 }
367