1: <?php
2:
3: /**
4: * Filter functions used by zenphoto
5: *
6: * The filter/plugin API is located in this file, which allows for creating filters
7: * and hooking functions, and methods. The functions or methods will be run when
8: * the filter is called.
9: *
10: * Any of the syntaxes explained in the PHP documentation for the
11: * {@link http://us2.php.net/manual/en/language.pseudo-types.php#language.types.callback 'callback'}
12: * type are valid.
13: *
14: * This API is heavily inspired by the plugin API used in WordPress.
15: *
16: * @package functions
17: * @author Ozh
18: * @since 1.3
19: */
20: // force UTF-8 Ø
21:
22: global $_zp_filters;
23: $_zp_filters = array();
24: /* This global var will collect filters with the following structure:
25: * $_zp_filter['hook']['array of priorities']['serialized function names']['array of ['array (functions, accepted_args)]']
26: */
27:
28: /**
29: * Registers a filtering function
30: * Filtering functions are used to post process zenphoto elements or to trigger functions when a filter occur
31: *
32: * Typical use:
33: *
34: * zp_register_filter('some_hook', 'function_handler_for_hook');
35: *
36: * global array $_zp_filters Storage for all of the filters
37: * @param string $hook the name of the zenphoto element to be filtered
38: * @param callback $function_name the name of the function that is to be called.
39: * @param integer $priority optional. Used to specify the order in which the functions associated with a particular
40: * action are executed (default=5, higher=earlier execution, and functions with
41: * the same priority are executed in the order in which they were added to the filter)
42: */
43: function zp_register_filter($hook, $function_name, $priority = NULL) {
44: global $_zp_filters, $_EnabledPlugins;
45: $bt = @debug_backtrace();
46: if (is_array($bt)) {
47: $b = array_shift($bt);
48: $base = basename($b['file']);
49: if (is_null($priority) && isset($_EnabledPlugins[stripSuffix($base)])) {
50: $priority = $_EnabledPlugins[stripSuffix($base)]['priority'] & PLUGIN_PRIORITY;
51: }
52: } else {
53: $base = 'unknown';
54: }
55: if (is_null($priority)) {
56: $priority = 5;
57: }
58:
59: // At this point, we cannot check if the function exists, as it may well be defined later (which is OK)
60:
61: $id = zp_filter_unique_id($hook, $function_name, $priority);
62:
63: $_zp_filters[$hook][$priority][$id] = array(
64: 'function' => $function_name,
65: 'script' => $base
66: );
67: if (DEBUG_FILTERS)
68: debugLog($base . '=>' . $function_name . ' registered to ' . $hook . ' at priority ' . $priority);
69: }
70:
71: /**
72: * Build Unique ID for storage and retrieval.
73: *
74: * Simply using a function name is not enough, as several functions can have the same name when they are enclosed in classes.
75: *
76: * global array $_zp_filters storage for all of the filters
77: * @param string $hook hook to which the function is attached
78: * @param string|array $function used for creating unique id
79: * @param int|bool $priority used in counting how many hooks were applied. If === false and $function is an object reference, we return the unique id only if it already has one, false otherwise.
80: * @param string $type filter or action
81: * @return string unique ID for usage as array key
82: */
83: function zp_filter_unique_id($hook, $function, $priority) {
84: global $_zp_filters;
85:
86: // If function then just skip all of the tests and not overwrite the following.
87: if (is_string($function))
88: return $function;
89: // Object Class Calling
90: else if (is_object($function[0])) {
91: $obj_idx = get_class($function[0]) . $function[1];
92: if (!isset($function[0]->_zp_filters_id)) {
93: if (false === $priority)
94: return false;
95: $count = isset($_zp_filters[$hook][$priority]) ? count((array) $_zp_filters[$hook][$priority]) : 0;
96: $function[0]->_zp_filters_id = $count;
97: $obj_idx .= $count;
98: unset($count);
99: } else {
100: $obj_idx .= $function[0]->_zp_filters_id;
101: }
102: return $obj_idx;
103: }
104: // Static Calling
105: else if (is_string($function[0]))
106: return $function[0] . $function[1];
107: }
108:
109: /**
110: * Performs a filtering operation on a zenphoto element or event.
111: * This function is called for each zenphoto element which supports
112: * plugin filtering. It is called after any zenphoto specific actions are
113: * completed and before the element is used.
114: *
115: * Typical use:
116: *
117: * 1) Modify a variable if a function is attached to hook 'zp_hook'
118: * $zp_var = "default value";
119: * $zp_var = zp_apply_filter( 'zp_hook', $zp_var );
120: *
121: * 2) Trigger functions is attached to event 'zp_event'
122: * zp_apply_filter( 'zp_event' );
123: *
124: * Returns an element which may have been filtered by a filter.
125: *
126: * global array $_zp_filters storage for all of the filters
127: * @param string $hook the name of the zenphoto element
128: * @param mixed $value the value of the element before filtering
129: * @return mixed
130: */
131: function zp_apply_filter($hook, $value = '') {
132: global $_zp_filters;
133: if (!isset($_zp_filters[$hook])) {
134: return $value;
135: }
136: $args = func_get_args();
137: // Sort filters by priority
138: krsort($_zp_filters[$hook]);
139: // Loops through each filter
140: reset($_zp_filters[$hook]);
141: if (DEBUG_FILTERS)
142: $debug = 'Apply filters for ' . $hook;
143: do {
144: foreach ((array) current($_zp_filters[$hook]) as $the_) {
145: if (!is_null($the_['function'])) {
146: if (DEBUG_FILTERS)
147: $debug .= "\n " . $the_['function'];
148: $args[1] = $value;
149: $new_value = call_user_func_array($the_['function'], array_slice($args, 1));
150: if (!is_null($new_value)) {
151: $value = $new_value;
152: }
153: }
154: }
155: } while (next($_zp_filters[$hook]) !== false);
156: if (DEBUG_FILTERS)
157: debugLog($debug);
158:
159: return $value;
160: }
161:
162: /**
163: * Removes a function from a specified filter hook.
164: *
165: * This function removes a function attached to a specified filter hook. This
166: * method can be used to remove default functions attached to a specific filter
167: * hook and possibly replace them with a substitute.
168: *
169: * To be removed the $function_to_remove and $priority arguments must match
170: * when the hook was added.
171: *
172: * global array $_zp_filters storage for all of the filters
173: * @param string $hook The filter hook to which the function to be removed is hooked.
174: * @param callback $function_to_remove The name of the function which should be removed.
175: * @param int $priority optional. The priority of the function. If not supplied we will get it from zp_has_filter
176: * @param int $accepted_args optional. The number of arguments the function accpets (default: 1).
177: * @return boolean Whether the function was registered as a filter before it was removed.
178: */
179: function zp_remove_filter($hook, $function_to_remove, $priority = NULL, $accepted_args = 1) {
180: global $_zp_filters;
181:
182: if (is_null($priority)) {
183: $priority = zp_has_filter($hook, $function_to_remove);
184: }
185: $function_to_remove = zp_filter_unique_id($hook, $function_to_remove, $priority);
186:
187: $remove = isset($_zp_filters[$hook][$priority][$function_to_remove]);
188: if ($remove) {
189: unset($_zp_filters[$hook][$priority][$function_to_remove]);
190: if (empty($_zp_filters[$hook][$priority]))
191: unset($_zp_filters[$hook][$priority]);
192: if (empty($_zp_filters[$hook]))
193: unset($_zp_filters[$hook]);
194: if (DEBUG_FILTERS)
195: debugLog($function_to_remove . ' removed from ' . $hook);
196: }
197: return $remove;
198: }
199:
200: /**
201: * Check if any filter has been registered for a hook.
202: *
203: * global array $_zp_filters storage for all of the filters
204: * @param string $hook The name of the filter hook.
205: * @param callback $function_to_check optional. If specified, return the priority of that function on this hook or false if not attached.
206: * @return int|boolean Optionally returns the priority on that hook for the specified function.
207: */
208: function zp_has_filter($hook, $function_to_check = false) {
209: global $_zp_filters;
210: $has = !empty($_zp_filters[$hook]);
211: if (false === $function_to_check || false == $has) {
212: return $has;
213: }
214: if (!$idx = zp_filter_unique_id($hook, $function_to_check, false)) {
215: return false;
216: }
217: foreach ((array) array_keys($_zp_filters[$hook]) as $key => $priority) {
218: if (isset($_zp_filters[$hook][$priority][$idx]))
219: return $priority;
220: }
221: return false;
222: }
223:
224: /**
225: *
226: * returns a list of scripts that have attached to the hook
227: * @param string $hook
228: * @return string
229: */
230: function get_filterScript($hook) {
231: global $_zp_filters;
232: $scripts = array();
233: foreach ($_zp_filters[$hook] as $priority) {
234: foreach ($priority as $actor) {
235: $scripts[] = $actor['script'];
236: }
237: }
238: return implode(', ', $scripts);
239: }
240:
241: /**
242: *
243: * Returns the position of the function in the hook queue
244: * @param $hook
245: * @param $function
246: */
247: function zp_filter_slot($hook, $function) {
248: global $_zp_filters;
249: if (empty($_zp_filters[$hook])) {
250: return false;
251: }
252: if (!$idx = zp_filter_unique_id($hook, $function, false)) {
253: return false;
254: }
255: // Sort filters by priority
256: $filters = $_zp_filters[$hook];
257: krsort($filters);
258: $c = 0;
259: foreach ((array) array_keys($filters) as $priority) {
260: foreach ($filters[$priority] as $filter => $data) {
261: if ($filter == $idx) {
262: return $c;
263: }
264: $c++;
265: }
266: }
267: return false;
268: }
269:
270: ?>
271: