Should be a better fix so this hook now works with plugins that have been using it...
[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");
0606ca1f 24 $function = "squirrelmail_plugin_init_$name";
25 if (function_exists($function)) {
26 $function();
2d367c68 27 }
2d367c68 28 }
0606ca1f 29}
2d367c68 30
d6c32258 31/**
32 * This function executes a hook.
33 * @param string $name Name of hook to fire
34 * @return mixed $data
35 */
31524bcd 36function do_hook ($name) {
eb1f02bc 37 global $squirrelmail_plugin_hooks, $currentHookName;
0606ca1f 38 $data = func_get_args();
eb1f02bc 39 $currentHookName = $name;
a3439b27 40
0606ca1f 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)) {
31524bcd 46 $function($data);
47 }
48 }
49 }
50
eb1f02bc 51 $currentHookName = '';
52
31524bcd 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
8b096f0a 58/**
e900d242 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 */
69function 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/**
8b096f0a 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 */
31524bcd 98function do_hook_function($name,$parm=NULL) {
eb1f02bc 99 global $squirrelmail_plugin_hooks, $currentHookName;
31524bcd 100 $ret = '';
eb1f02bc 101 $currentHookName = $name;
31524bcd 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);
dd389be5 109 }
2d367c68 110 }
2d367c68 111 }
7b086a80 112
eb1f02bc 113 $currentHookName = '';
114
0606ca1f 115 /* Variable-length argument lists have a slight problem when */
116 /* passing values by reference. Pity. This is a workaround. */
2586d588 117 return $ret;
0606ca1f 118}
7b086a80 119
8b096f0a 120/**
7edd8ad6 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.
8b096f0a 134 *
135 * @param string name the name of the hook
7edd8ad6 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 *
8b096f0a 141 */
09ac2863 142function concat_hook_function($name,$parm=NULL) {
eb1f02bc 143 global $squirrelmail_plugin_hooks, $currentHookName;
bbac5629 144 $ret = '';
145// $ret = array();
eb1f02bc 146 $currentHookName = $name;
31524bcd 147
09ac2863 148 if (isset($squirrelmail_plugin_hooks[$name])
149 && is_array($squirrelmail_plugin_hooks[$name])) {
150 foreach ($squirrelmail_plugin_hooks[$name] as $function) {
7edd8ad6 151 /* Add something to set correct gettext domain for plugin. */
09ac2863 152 if (function_exists($function)) {
7edd8ad6 153// $ret .= $function($parm);
918fcc1d 154 $ret = sqm_array_merge($ret, $function($parm));
09ac2863 155 }
156 }
157 }
158
eb1f02bc 159 $currentHookName = '';
160
09ac2863 161 /* Variable-length argument lists have a slight problem when */
162 /* passing values by reference. Pity. This is a workaround. */
163 return $ret;
164}
cd7fc9e6 165
166/**
5576644b 167 * This function is used for hooks which are to return true or
168 * false. If $priority is > 0, any one or more trues will override
169 * any falses. If $priority < 0, then one or more falses will
170 * override any trues.
8b096f0a 171 * Priority 0 means majority rules. Ties will be broken with $tie
172 *
173 * @param string name the hook name
174 * @param mixed parm the parameters for the hook function
175 * @param int priority
176 * @param bool tie
177 * @return bool the result of the function
178 */
5576644b 179function boolean_hook_function($name,$parm=NULL,$priority=0,$tie=false) {
eb1f02bc 180 global $squirrelmail_plugin_hooks, $currentHookName;
5576644b 181 $yea = 0;
182 $nay = 0;
183 $ret = $tie;
184
185 if (isset($squirrelmail_plugin_hooks[$name]) &&
186 is_array($squirrelmail_plugin_hooks[$name])) {
187
188 /* Loop over the plugins that registered the hook */
eb1f02bc 189 $currentHookName = $name;
5576644b 190 foreach ($squirrelmail_plugin_hooks[$name] as $function) {
191 if (function_exists($function)) {
192 $ret = $function($parm);
193 if ($ret) {
194 $yea++;
195 } else {
196 $nay++;
197 }
198 }
199 }
eb1f02bc 200 $currentHookName = '';
5576644b 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/**
cd7fc9e6 221 * This function checks whether the user's USER_AGENT is known to
222 * be broken. If so, returns true and the plugin is invisible to the
223 * offending browser.
7349fa12 224 * *** THIS IS A TEST FOR JAVASCRIPT SUPPORT ***
94ba79ce 225 * FIXME: This function needs to have its name changed!
8b096f0a 226 *
227 * @return bool whether this browser properly supports JavaScript
ccacde36 228 * @deprecated use checkForJavascript() since 1.5.1
cd7fc9e6 229 */
230function soupNazi(){
7349fa12 231 return !checkForJavascript();
cd7fc9e6 232}
fe0aa536 233
234/**
235 * Check if plugin is enabled
236 * @param string $plugin_name plugin name
237 * @since 1.5.1
238 * @return boolean
239 */
240function is_plugin_enabled($plugin_name) {
241 global $plugins;
242
e83cfcef 243 /**
202bcbcc 244 * check if variable is empty. if var is not set, php empty
e495bd68 245 * returns true without error notice.
246 *
247 * then check if it is an array
e83cfcef 248 */
e495bd68 249 if (empty($plugins) || ! is_array($plugins))
fe0aa536 250 return false;
251
252 if ( in_array($plugin_name,$plugins) ) {
253 return true;
254 } else {
255 return false;
256 }
257}
d99b6c56 258
259/**
260 * Check a plugin's version.
261 *
262 * Returns TRUE if the given plugin is installed,
263 * activated and is at minimum version $a.$b.$c.
264 * If any one of those conditions fails, FALSE
265 * will be returned (careful of plugins that are
266 * sufficiently versioned but are not activated).
267 *
268 * By overriding the default value of $force_inclusion,
269 * this function will attempt to grab versioning
270 * information from the given plugin even if it
271 * is not activated (plugin still has to be
272 * unpackaged and set in place in the plugins
273 * directory). Use with care - some plugins
274 * might break SquirrelMail when this is used.
275 *
276 * Note that this function assumes plugin
277 * versioning is consistently applied in the same
278 * fashion that SquirrelMail versions are, with the
279 * exception that an applicable SquirrelMail
280 * version may be appended to the version number
281 * (which will be ignored herein). That is, plugin
282 * version number schemes are expected in the following
283 * format: 1.2.3, or 1.2.3-1.4.0.
284 *
285 * Any characters after the third number are discarded,
286 * so formats such as the following will also work,
287 * although extra information about beta versions can
288 * possibly confuse the desired results of the version
289 * check: 1.2.3-beta4, 1.2.3.RC2, and so forth.
290 *
b2a6a14c 291 * @since 1.5.2
d99b6c56 292 *
293 * @param string plugin_name name of the plugin to
294 * check; must precisely
295 * match the plugin
296 * directory name
297 * @param int a major version number
298 * @param int b minor version number
299 * @param int c release number
300 * @param bool force_inclusion try to get version info
301 * for plugins not activated?
302 * (default FALSE)
303 *
304 * @return bool
305 *
306 */
307function check_plugin_version($plugin_name,
308 $a = 0, $b = 0, $c = 0,
309 $force_inclusion = FALSE)
310{
311
6b6bcf00 312 $info_function = $plugin_name . '_info';
d99b6c56 313 $version_function = $plugin_name . '_version';
6b6bcf00 314 $plugin_info = array();
d99b6c56 315 $plugin_version = FALSE;
316
317
6b6bcf00 318 // first attempt to find the plugin info function, wherein
319 // the plugin version should be available
d99b6c56 320 //
6b6bcf00 321 if (function_exists($info_function))
322 $plugin_info = $info_function();
d99b6c56 323 else if ($force_inclusion
324 && file_exists(SM_PATH . 'plugins/' . $plugin_name . '/setup.php'))
325 {
326 include_once(SM_PATH . 'plugins/' . $plugin_name . '/setup.php');
6b6bcf00 327 if (function_exists($info_function))
328 $plugin_info = $info_function();
d99b6c56 329 }
6b6bcf00 330 if (!empty($plugin_info['version']))
331 $plugin_version = $plugin_info['version'];
332
333
334 // otherwise, look for older version function
335 //
336 if (!$plugin_version && function_exists($version_function))
337 $plugin_version = $version_function();
338
d99b6c56 339
340 if (!$plugin_version) return FALSE;
341
342
343 // now massage version number into something we understand
344 //
345 $plugin_version = trim(preg_replace(array('/[^0-9.]+.*$/', '/[^0-9.]/'),
346 '', $plugin_version),
347 '.');
348 $plugin_version = explode('.', $plugin_version);
349 if (!isset($plugin_version[0])) $plugin_version[0] = 0;
350 if (!isset($plugin_version[1])) $plugin_version[1] = 0;
351 if (!isset($plugin_version[2])) $plugin_version[2] = 0;
352// sm_print_r($plugin_version);
353
354
355 // now test the version number
356 //
357 if ($plugin_version[0] < $a ||
358 ($plugin_version[0] == $a && $plugin_version[1] < $b) ||
359 ($plugin_version[0] == $a && $plugin_version[1] == $b && $plugin_version[2] < $c))
360 return FALSE;
361
362
363 return TRUE;
364
365}
366