*/ if(!defined('DOKU_INC')) die('meh.'); /** * The event */ class Doku_Event { // public properties public $name = ''; // READONLY event name, objects must register against this name to see the event public $data = null; // READWRITE data relevant to the event, no standardised format (YET!) public $result = null; // READWRITE the results of the event action, only relevant in "_AFTER" advise // event handlers may modify this if they are preventing the default action // to provide the after event handlers with event results public $canPreventDefault = true; // READONLY if true, event handlers can prevent the events default action // private properties, event handlers can effect these through the provided methods protected $_default = true; // whether or not to carry out the default action associated with the event protected $_continue = true; // whether or not to continue propagating the event to other handlers /** * event constructor * * @param string $name * @param mixed $data */ function __construct($name, &$data) { $this->name = $name; $this->data =& $data; } /** * @return string */ function __toString() { return $this->name; } /** * advise functions * * advise all registered handlers of this event * * if these methods are used by functions outside of this object, they must * properly handle correct processing of any default action and issue an * advise_after() signal. e.g. * $evt = new Doku_Event(name, data); * if ($evt->advise_before(canPreventDefault) { * // default action code block * } * $evt->advise_after(); * unset($evt); * * @param bool $enablePreventDefault * @return bool results of processing the event, usually $this->_default */ function advise_before($enablePreventDefault=true) { global $EVENT_HANDLER; $this->canPreventDefault = $enablePreventDefault; $EVENT_HANDLER->process_event($this,'BEFORE'); return (!$enablePreventDefault || $this->_default); } function advise_after() { global $EVENT_HANDLER; $this->_continue = true; $EVENT_HANDLER->process_event($this,'AFTER'); } /** * trigger * * - advise all registered (_BEFORE) handlers that this event is about to take place * - carry out the default action using $this->data based on $enablePrevent and * $this->_default, all of which may have been modified by the event handlers. * - advise all registered (_AFTER) handlers that the event has taken place * * @param null|callable $action * @param bool $enablePrevent * @return mixed $event->results * the value set by any _before or handlers if the default action is prevented * or the results of the default action (as modified by _after handlers) * or NULL no action took place and no handler modified the value */ function trigger($action=null, $enablePrevent=true) { if (!is_callable($action)) { $enablePrevent = false; if (!is_null($action)) { trigger_error('The default action of '.$this.' is not null but also not callable. Maybe the method is not public?', E_USER_WARNING); } } if ($this->advise_before($enablePrevent) && is_callable($action)) { if (is_array($action)) { list($obj,$method) = $action; $this->result = $obj->$method($this->data); } else { $this->result = $action($this->data); } } $this->advise_after(); return $this->result; } /** * stopPropagation * * stop any further processing of the event by event handlers * this function does not prevent the default action taking place */ public function stopPropagation() { $this->_continue = false; } /** * may the event propagate to the next handler? * * @return bool */ public function mayPropagate() { return $this->_continue; } /** * preventDefault * * prevent the default action taking place */ public function preventDefault() { $this->_default = false; } /** * should the default action be executed? * * @return bool */ public function mayRunDefault() { return $this->_default; } } /** * Controls the registration and execution of all events, */ class Doku_Event_Handler { // public properties: none // private properties protected $_hooks = array(); // array of events and their registered handlers /** * event_handler * * constructor, loads all action plugins and calls their register() method giving them * an opportunity to register any hooks they require */ function __construct() { // load action plugins /** @var DokuWiki_Action_Plugin $plugin */ $plugin = null; $pluginlist = plugin_list('action'); foreach ($pluginlist as $plugin_name) { $plugin = plugin_load('action',$plugin_name); if ($plugin !== null) $plugin->register($this); } } /** * register_hook * * register a hook for an event * * @param string $event string name used by the event, (incl '_before' or '_after' for triggers) * @param string $advise * @param object $obj object in whose scope method is to be executed, * if NULL, method is assumed to be a globally available function * @param string $method event handler function * @param mixed $param data passed to the event handler * @param int $seq sequence number for ordering hook execution (ascending) */ function register_hook($event, $advise, $obj, $method, $param=null, $seq=0) { $seq = (int)$seq; $doSort = !isset($this->_hooks[$event.'_'.$advise][$seq]); $this->_hooks[$event.'_'.$advise][$seq][] = array($obj, $method, $param); if ($doSort) { ksort($this->_hooks[$event.'_'.$advise]); } } /** * process the before/after event * * @param Doku_Event $event * @param string $advise BEFORE or AFTER */ function process_event($event,$advise='') { $evt_name = $event->name . ($advise ? '_'.$advise : '_BEFORE'); if (!empty($this->_hooks[$evt_name])) { foreach ($this->_hooks[$evt_name] as $sequenced_hooks) { foreach ($sequenced_hooks as $hook) { list($obj, $method, $param) = $hook; if (is_null($obj)) { $method($event, $param); } else { $obj->$method($event, $param); } if (!$event->mayPropagate()) return; } } } } /** * Check if an event has any registered handlers * * When $advise is empty, both BEFORE and AFTER events will be considered, * otherwise only the given advisory is checked * * @param string $name Name of the event * @param string $advise BEFORE, AFTER or empty * @return bool */ public function hasHandlerForEvent($name, $advise = '') { if($advise) { return isset($this->_hooks[$name . '_' . $advise]); } else { return isset($this->_hooks[$name . '_BEFORE']) || isset($this->_hooks[$name . '_AFTER']); } } } /** * trigger_event * * function wrapper to process (create, trigger and destroy) an event * * @param string $name name for the event * @param mixed $data event data * @param callback $action (optional, default=NULL) default action, a php callback function * @param bool $canPreventDefault (optional, default=true) can hooks prevent the default action * * @return mixed the event results value after all event processing is complete * by default this is the return value of the default action however * it can be set or modified by event handler hooks */ function trigger_event($name, &$data, $action=null, $canPreventDefault=true) { $evt = new Doku_Event($name, $data); return $evt->trigger($action, $canPreventDefault); }