1:   2:   3:   4:   5:   6:   7:   8:   9:  10:  11:  12:  13:  14:  15:  16:  17:  18:  19:  20:  21:  22:  23:  24:  25:  26:  27:  28:  29:  30:  31:  32:  33:  34:  35:  36:  37:  38:  39:  40:  41:  42:  43:  44:  45:  46:  47:  48:  49:  50:  51:  52:  53:  54:  55:  56:  57:  58:  59:  60:  61:  62:  63:  64:  65:  66:  67:  68:  69:  70:  71:  72:  73:  74:  75:  76:  77:  78:  79:  80:  81:  82:  83:  84:  85:  86:  87:  88:  89:  90:  91:  92:  93:  94:  95:  96:  97:  98:  99: 100: 101: 102: 103: 104: 105: 106: 107: 108: 109: 110: 111: 112: 113: 114: 115: 116: 117: 118: 119: 120: 121: 122: 123: 124: 125: 126: 127: 128: 129: 130: 131: 132: 133: 134: 135: 136: 137: 138: 139: 140: 141: 142: 143: 144: 145: 146: 147: 148: 149: 150: 151: 152: 153: 154: 155: 156: 157: 158: 159: 160: 161: 162: 163: 164: 165: 166: 167: 168: 169: 170: 171: 172: 173: 174: 175: 176: 177: 178: 179: 180: 181: 182: 183: 184: 185: 186: 187: 188: 189: 190: 191: 192: 193: 194: 195: 196: 197: 198: 199: 200: 201: 202: 203: 204: 205: 206: 207: 208: 209: 210: 211: 212: 213: 214: 215: 216: 217: 218: 219: 220: 221: 222: 223: 224: 225: 226: 227: 228: 229: 230: 231: 232: 233: 234: 235: 236: 237: 238: 239: 240: 241: 242: 243: 244: 245: 246: 247: 248: 249: 250: 251: 252: 253: 254: 255: 256: 257: 258: 259: 260: 261: 262: 263: 264: 265: 266: 267: 268: 269: 270: 271: 272: 

<?php

/**
 * Filter functions used by zenphoto
 *
 * The filter/plugin API is located in this file, which allows for creating filters
 * and hooking functions, and methods. The functions or methods will be run when
 * the filter is called.
 *
 * Any of the syntaxes explained in the PHP documentation for the
 * {@link http://us2.php.net/manual/en/language.pseudo-types.php#language.types.callback 'callback'}
 * type are valid.
 *
 * This API is heavily inspired by the plugin API used in WordPress.
 *
 * @package core
 * @subpackage functions\functions-filter
 * @author Ozh
 * @since 1.3
 */
// force UTF-8 Ø

global $_zp_filters;
$_zp_filters = array();
/* This global var will collect filters with the following structure:
 * $_zp_filter['hook']['array of priorities']['serialized function names']['array of ['array (functions, accepted_args)]']
 */

/**
 * Registers a filtering function
 * Filtering functions are used to post process zenphoto elements or to trigger functions when a filter occur
 *
 * Typical use:
 *
 *      zp_register_filter('some_hook', 'function_handler_for_hook');
 *
 * global array $_zp_filters Storage for all of the filters
 * @param string $hook the name of the zenphoto element to be filtered
 * @param callback $function_name the name of the function that is to be called.
 * @param integer $priority optional. Used to specify the order in which the functions associated with a particular
 *                                                                      action are executed (default=5, higher=earlier execution, and functions with
 *                                                                      the same priority are executed in the order in which they were added to the filter)
 */
function zp_register_filter($hook, $function_name, $priority = NULL) {
    global $_zp_filters, $_EnabledPlugins;
    $bt = @debug_backtrace();
    if (is_array($bt)) {
        $b = array_shift($bt);
        $base = basename($b['file']);
        if (is_null($priority) && isset($_EnabledPlugins[stripSuffix($base)])) {
            $priority = $_EnabledPlugins[stripSuffix($base)]['priority'] & PLUGIN_PRIORITY;
        }
    } else {
        $base = 'unknown';
    }
    if (is_null($priority)) {
        $priority = 5;
    }

    // At this point, we cannot check if the function exists, as it may well be defined later (which is OK)

    $id = zp_filter_unique_id($hook, $function_name, $priority);

    $_zp_filters[$hook][$priority][$id] = array(
                    'function' => $function_name,
                    'script'     => $base
    );
    if (DEBUG_FILTERS)
        debugLog($base . '=>' . $function_name . ' registered to ' . $hook . ' at priority ' . $priority);
}

/**
 * Build Unique ID for storage and retrieval.
 *
 * Simply using a function name is not enough, as several functions can have the same name when they are enclosed in classes.
 *
 * global array $_zp_filters storage for all of the filters
 * @param string $hook hook to which the function is attached
 * @param string|array $function used for creating unique id
 * @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.
 * @param string $type filter or action
 * @return string unique ID for usage as array key
 */
function zp_filter_unique_id($hook, $function, $priority) {
    global $_zp_filters;

    // If function then just skip all of the tests and not overwrite the following.
    if (is_string($function))
        return $function;
    // Object Class Calling
    else if (is_object($function[0])) {
        $obj_idx = get_class($function[0]) . $function[1];
        if (!isset($function[0]->_zp_filters_id)) {
            if (false === $priority)
                return false;
            $count = isset($_zp_filters[$hook][$priority]) ? count((array) $_zp_filters[$hook][$priority]) : 0;
            $function[0]->_zp_filters_id = $count;
            $obj_idx .= $count;
            unset($count);
        } else {
            $obj_idx .= $function[0]->_zp_filters_id;
        }
        return $obj_idx;
    }
    // Static Calling
    else if (is_string($function[0]))
        return $function[0] . $function[1];
}

/**
 * Performs a filtering operation on a zenphoto element or event.
 * This function is called for each zenphoto element which supports
 * plugin filtering. It is called after any zenphoto specific actions are
 * completed and before the element is used.
 *
 * Typical use:
 *
 *      1) Modify a variable if a function is attached to hook 'zp_hook'
 *      $zp_var = "default value";
 *      $zp_var = zp_apply_filter( 'zp_hook', $zp_var );
 *
 *      2) Trigger functions is attached to event 'zp_event'
 *      zp_apply_filter( 'zp_event' );
 *
 * Returns an element which may have been filtered by a filter.
 *
 * global array $_zp_filters storage for all of the filters
 * @param string $hook the name of the zenphoto element
 * @param mixed $value the value of the element before filtering
 * @return mixed
 */
function zp_apply_filter($hook, $value = '') {
    global $_zp_filters;
    if (!isset($_zp_filters[$hook])) {
        return $value;
    }
    $args = func_get_args();
    // Sort filters by priority
    krsort($_zp_filters[$hook]);
    // Loops through each filter
    reset($_zp_filters[$hook]);
    if (DEBUG_FILTERS)
        $debug = 'Apply filters for ' . $hook;
    do {
        foreach ((array) current($_zp_filters[$hook]) as $the_) {
            if (!is_null($the_['function'])) {
                if (DEBUG_FILTERS)
                    $debug .= "\n    " . $the_['function'];
                $args[1] = $value;
                $new_value = call_user_func_array($the_['function'], array_slice($args, 1));
                if (!is_null($new_value)) {
                    $value = $new_value;
                }
            }
        }
    } while (next($_zp_filters[$hook]) !== false);
    if (DEBUG_FILTERS)
        debugLog($debug);

    return $value;
}

/**
 * Removes a function from a specified filter hook.
 *
 * This function removes a function attached to a specified filter hook. This
 * method can be used to remove default functions attached to a specific filter
 * hook and possibly replace them with a substitute.
 *
 * To be removed the $function_to_remove and $priority arguments must match
 * when the hook was added.
 *
 * global array $_zp_filters storage for all of the filters
 * @param string $hook The filter hook to which the function to be removed is hooked.
 * @param callback $function_to_remove The name of the function which should be removed.
 * @param int $priority optional. The priority of the function. If not supplied we will get it from zp_has_filter
 * @param int $accepted_args optional. The number of arguments the function accpets (default: 1).
 * @return boolean Whether the function was registered as a filter before it was removed.
 */
function zp_remove_filter($hook, $function_to_remove, $priority = NULL, $accepted_args = 1) {
    global $_zp_filters;

    if (is_null($priority)) {
        $priority = zp_has_filter($hook, $function_to_remove);
    }
    $function_to_remove = zp_filter_unique_id($hook, $function_to_remove, $priority);

    $remove = isset($_zp_filters[$hook][$priority][$function_to_remove]);
    if ($remove) {
        unset($_zp_filters[$hook][$priority][$function_to_remove]);
        if (empty($_zp_filters[$hook][$priority]))
            unset($_zp_filters[$hook][$priority]);
        if (empty($_zp_filters[$hook]))
            unset($_zp_filters[$hook]);
        if (DEBUG_FILTERS)
            debugLog($function_to_remove . ' removed from ' . $hook);
    }
    return $remove;
}

/**
 * Check if any filter has been registered for a hook.
 *
 * global array $_zp_filters storage for all of the filters
 * @param string $hook The name of the filter hook.
 * @param callback $function_to_check optional.  If specified, return the priority of that function on this hook or false if not attached.
 * @return int|boolean Optionally returns the priority on that hook for the specified function.
 */
function zp_has_filter($hook, $function_to_check = false) {
    global $_zp_filters;
    $has = !empty($_zp_filters[$hook]);
    if (false === $function_to_check || false == $has) {
        return $has;
    }
    if (!$idx = zp_filter_unique_id($hook, $function_to_check, false)) {
        return false;
    }
    foreach ((array) array_keys($_zp_filters[$hook]) as $key => $priority) {
        if (isset($_zp_filters[$hook][$priority][$idx]))
            return $priority;
    }
    return false;
}

/**
 *
 * returns a list of scripts that have attached to the hook
 * @param string $hook
 * @return string
 */
function get_filterScript($hook) {
    global $_zp_filters;
    $scripts = array();
    foreach ($_zp_filters[$hook] as $priority) {
        foreach ($priority as $actor) {
            $scripts[] = $actor['script'];
        }
    }
    return implode(', ', $scripts);
}

/**
 *
 * Returns the position of the function in the hook queue
 * @param $hook
 * @param $function
 */
function zp_filter_slot($hook, $function) {
    global $_zp_filters;
    if (empty($_zp_filters[$hook])) {
        return false;
    }
    if (!$idx = zp_filter_unique_id($hook, $function, false)) {
        return false;
    }
    // Sort filters by priority
    $filters = $_zp_filters[$hook];
    krsort($filters);
    $c = 0;
    foreach ((array) array_keys($filters) as $priority) {
        foreach ($filters[$priority] as $filter => $data) {
            if ($filter == $idx) {
                return $c;
            }
            $c++;
        }
    }
    return false;
}

?>