diff options
| -rw-r--r-- | lib/event.php | 113 |
1 files changed, 113 insertions, 0 deletions
diff --git a/lib/event.php b/lib/event.php new file mode 100644 index 000000000..f5406d07a --- /dev/null +++ b/lib/event.php @@ -0,0 +1,113 @@ +<?php +/** + * Laconica, the distributed open-source microblogging tool + * + * utilities for defining and running event handlers + * + * PHP version 5 + * + * LICENCE: This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU Affero General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Affero General Public License for more details. + * + * You should have received a copy of the GNU Affero General Public License + * along with this program. If not, see <http://www.gnu.org/licenses/>. + * + * @category Event + * @package Laconica + * @author Evan Prodromou <evan@controlyourself.ca> + * @copyright 2008 Control Yourself, Inc. + * @license http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License version 3.0 + * @link http://laconi.ca/ + */ + +if (!defined('LACONICA')) { + exit(1); +} + +/** + * Class for events + * + * This "class" two static functions for managing events in the Laconica code. + * + * @category Event + * @package Laconica + * @author Evan Prodromou <evan@controlyourself.ca> + * @license http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License version 3.0 + * @link http://laconi.ca/ + * + * @todo Define a system for using Event instances + */ + +class Event { + + /* Global array of hooks, mapping eventname => array of callables */ + + protected static $_handlers = array(); + + /** + * Add an event handler + * + * To run some code at a particular point in Laconica processing. + * Named events include receiving an XMPP message, adding a new notice, + * or showing part of an HTML page. + * + * The arguments to the handler vary by the event. Handlers can return + * two possible values: false means that the event has been replaced by + * the handler completely, and no default processing should be done. + * Non-false means successful handling, and that the default processing + * should succeed. (Note that this only makes sense for some events.) + * + * Handlers can also abort processing by throwing an exception; these will + * be caught by the closest code and displayed as errors. + * + * @param string $name Name of the event + * @param callable $handler Code to run + * + * @return void + */ + + public static function addHandler($name, $handler) { + if (array_key_exists($name, Event::$_handlers)) { + Event::$_handlers[$name][] = $handler; + } else { + Event::$_handlers[$name] = array($handler); + } + } + + /** + * Handle an event + * + * Events are any point in the code that we want to expose for admins + * or third-party developers to use. + * + * We pass in an array of arguments (including references, for stuff + * that can be changed), and each assigned handler gets run with those + * arguments. Exceptions can be thrown to indicate an error. + * + * @param string $name Name of the event that's happening + * @param array $args Arguments for handlers + * + * @return boolean flag saying whether to continue processing, based + * on results of handlers. + */ + + public static function handle($name, $args) { + $result = null; + if (array_key_exists($name, Event::$_handlers)) { + foreach (Event::$_handlers[$name] as $handler) { + $result = call_user_func_array($handler, $args); + if ($result === false) { + break; + } + } + } + return ($result === false); + } +} |