summaryrefslogtreecommitdiff
path: root/lib/event.php
diff options
context:
space:
mode:
Diffstat (limited to 'lib/event.php')
-rw-r--r--lib/event.php113
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);
+ }
+}