xref: /dokuwiki/inc/Extension/Event.php (revision e1d9dcc8b460b6f029ac9c8d5d3b8d23b6e73402) 
1<?php
2
3namespace dokuwiki\Extension;
4
5/**
6 * The Action plugin event
7 */
8class Event
9{
10
11    // public properties
12    public $name = '';                // READONLY  event name, objects must register against this name to see the event
13    public $data = null;              // READWRITE data relevant to the event, no standardised format (YET!)
14    public $result = null;            // READWRITE the results of the event action, only relevant in "_AFTER" advise
15    //    event handlers may modify this if they are preventing the default action
16    //    to provide the after event handlers with event results
17    public $canPreventDefault = true; // READONLY  if true, event handlers can prevent the events default action
18
19    // private properties, event handlers can effect these through the provided methods
20    protected $_default = true;     // whether or not to carry out the default action associated with the event
21    protected $_continue = true;    // whether or not to continue propagating the event to other handlers
22
23    /**
24     * event constructor
25     *
26     * @param string $name
27     * @param mixed $data
28     */
29    public function __construct($name, &$data)
30    {
31
32        $this->name = $name;
33        $this->data =& $data;
34
35    }
36
37    /**
38     * @return string
39     */
40    public function __toString()
41    {
42        return $this->name;
43    }
44
45    /**
46     * advise functions
47     *
48     * advise all registered handlers of this event
49     *
50     * if these methods are used by functions outside of this object, they must
51     * properly handle correct processing of any default action and issue an
52     * advise_after() signal. e.g.
53     *    $evt = new dokuwiki\Plugin\Doku_Event(name, data);
54     *    if ($evt->advise_before(canPreventDefault) {
55     *      // default action code block
56     *    }
57     *    $evt->advise_after();
58     *    unset($evt);
59     *
60     * @param bool $enablePreventDefault
61     * @return bool results of processing the event, usually $this->_default
62     */
63    public function advise_before($enablePreventDefault = true)
64    {
65        global $EVENT_HANDLER;
66
67        $this->canPreventDefault = $enablePreventDefault;
68        $EVENT_HANDLER->process_event($this, 'BEFORE');
69
70        return (!$enablePreventDefault || $this->_default);
71    }
72
73    public function advise_after()
74    {
75        global $EVENT_HANDLER;
76
77        $this->_continue = true;
78        $EVENT_HANDLER->process_event($this, 'AFTER');
79    }
80
81    /**
82     * trigger
83     *
84     * - advise all registered (<event>_BEFORE) handlers that this event is about to take place
85     * - carry out the default action using $this->data based on $enablePrevent and
86     *   $this->_default, all of which may have been modified by the event handlers.
87     * - advise all registered (<event>_AFTER) handlers that the event has taken place
88     *
89     * @param null|callable $action
90     * @param bool $enablePrevent
91     * @return  mixed $event->results
92     *          the value set by any <event>_before or <event> handlers if the default action is prevented
93     *          or the results of the default action (as modified by <event>_after handlers)
94     *          or NULL no action took place and no handler modified the value
95     */
96    public function trigger($action = null, $enablePrevent = true)
97    {
98
99        if (!is_callable($action)) {
100            $enablePrevent = false;
101            if (!is_null($action)) {
102                trigger_error(
103                    'The default action of ' . $this .
104                    ' is not null but also not callable. Maybe the method is not public?',
105                    E_USER_WARNING
106                );
107            }
108        }
109
110        if ($this->advise_before($enablePrevent) && is_callable($action)) {
111            if (is_array($action)) {
112                list($obj, $method) = $action;
113                $this->result = $obj->$method($this->data);
114            } else {
115                $this->result = $action($this->data);
116            }
117        }
118
119        $this->advise_after();
120
121        return $this->result;
122    }
123
124    /**
125     * stopPropagation
126     *
127     * stop any further processing of the event by event handlers
128     * this function does not prevent the default action taking place
129     */
130    public function stopPropagation()
131    {
132        $this->_continue = false;
133    }
134
135    /**
136     * may the event propagate to the next handler?
137     *
138     * @return bool
139     */
140    public function mayPropagate()
141    {
142        return $this->_continue;
143    }
144
145    /**
146     * preventDefault
147     *
148     * prevent the default action taking place
149     */
150    public function preventDefault()
151    {
152        $this->_default = false;
153    }
154
155    /**
156     * should the default action be executed?
157     *
158     * @return bool
159     */
160    public function mayRunDefault()
161    {
162        return $this->_default;
163    }
164}
165