3 * StatusNet, the distributed open-source microblogging tool
5 * utilities for defining and running event handlers
9 * LICENCE: This program is free software: you can redistribute it and/or modify
10 * it under the terms of the GNU Affero General Public License as published by
11 * the Free Software Foundation, either version 3 of the License, or
12 * (at your option) any later version.
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU Affero General Public License for more details.
19 * You should have received a copy of the GNU Affero General Public License
20 * along with this program. If not, see <http://www.gnu.org/licenses/>.
24 * @author Evan Prodromou <evan@status.net>
25 * @copyright 2008 StatusNet, Inc.
26 * @license http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License version 3.0
27 * @link http://status.net/
30 if (!defined('STATUSNET') && !defined('LACONICA')) {
37 * This "class" two static functions for managing events in the StatusNet code.
41 * @author Evan Prodromou <evan@status.net>
42 * @license http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License version 3.0
43 * @link http://status.net/
45 * @todo Define a system for using Event instances
50 /* Global array of hooks, mapping eventname => array of callables */
52 protected static $_handlers = array();
55 * Add an event handler
57 * To run some code at a particular point in StatusNet processing.
58 * Named events include receiving an XMPP message, adding a new notice,
59 * or showing part of an HTML page.
61 * The arguments to the handler vary by the event. Handlers can return
62 * two possible values: false means that the event has been replaced by
63 * the handler completely, and no default processing should be done.
64 * Non-false means successful handling, and that the default processing
65 * should succeed. (Note that this only makes sense for some events.)
67 * Handlers can also abort processing by throwing an exception; these will
68 * be caught by the closest code and displayed as errors.
70 * @param string $name Name of the event
71 * @param callable $handler Code to run
76 public static function addHandler($name, $handler) {
77 if (array_key_exists($name, Event::$_handlers)) {
78 Event::$_handlers[$name][] = $handler;
80 Event::$_handlers[$name] = array($handler);
87 * Events are any point in the code that we want to expose for admins
88 * or third-party developers to use.
90 * We pass in an array of arguments (including references, for stuff
91 * that can be changed), and each assigned handler gets run with those
92 * arguments. Exceptions can be thrown to indicate an error.
94 * @param string $name Name of the event that's happening
95 * @param array $args Arguments for handlers
97 * @return boolean flag saying whether to continue processing, based
98 * on results of handlers.
101 public static function handle($name, array $args=array()) {
103 if (array_key_exists($name, Event::$_handlers)) {
104 foreach (Event::$_handlers[$name] as $handler) {
105 $result = call_user_func_array($handler, $args);
106 if ($result === false) {
111 return ($result !== false);
115 * Check to see if an event handler exists
117 * Look to see if there's any handler for a given event, or narrow
118 * by providing the name of a specific plugin class.
120 * @param string $name Name of the event to look for
121 * @param string $plugin Optional name of the plugin class to look for
123 * @return boolean flag saying whether such a handler exists
127 public static function hasHandler($name, $plugin=null) {
128 if (array_key_exists($name, Event::$_handlers)) {
129 if (isset($plugin)) {
130 foreach (Event::$_handlers[$name] as $handler) {
131 if (get_class($handler[0]) == $plugin) {
142 public static function getHandlers($name)
144 return Event::$_handlers[$name];
148 * Disables any and all handlers that have been set up so far;
149 * use only if you know it's safe to reinitialize all plugins.
151 public static function clearHandlers() {
152 Event::$_handlers = array();