lib/event.php

   1 <?php
   2 // This file is part of GNU social - https://www.gnu.org/software/social
   3 //
   4 // GNU social is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU Affero General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // GNU social is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU Affero General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU Affero General Public License
  15 // along with GNU social.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 defined('GNUSOCIAL') || die();
  18
  19 /**
  20  * Class for events
  21  *
  22  * This "class" two static functions for managing events in the StatusNet code.
  23  *
  24  * @category Event
  25  * @package  GNU social
  26  * @author   Evan Prodromou <evan@status.net>
  27  * @copyright 2010-2019 Free Software Foundation, Inc http://www.fsf.org
  28  * @license   https://www.gnu.org/licenses/agpl.html GNU AGPL v3 or later
  29  *
  30  * @todo     Define a system for using Event instances
  31  */
  32 class Event {
  33
  34     /* Global array of hooks, mapping eventname => array of callables */
  35
  36     protected static $_handlers = array();
  37
  38     /**
  39      * Add an event handler
  40      *
  41      * To run some code at a particular point in StatusNet processing.
  42      * Named events include receiving an XMPP message, adding a new notice,
  43      * or showing part of an HTML page.
  44      *
  45      * The arguments to the handler vary by the event. Handlers can return
  46      * two possible values: false means that the event has been replaced by
  47      * the handler completely, and no default processing should be done.
  48      * Non-false means successful handling, and that the default processing
  49      * should succeed. (Note that this only makes sense for some events.)
  50      *
  51      * Handlers can also abort processing by throwing an exception; these will
  52      * be caught by the closest code and displayed as errors.
  53      *
  54      * @param string   $name    Name of the event
  55      * @param callable $handler Code to run
  56      *
  57      * @return void
  58      */
  59
  60     public static function addHandler($name, $handler) {
  61         if (array_key_exists($name, Event::$_handlers)) {
  62             Event::$_handlers[$name][] = $handler;
  63         } else {
  64             Event::$_handlers[$name] = array($handler);
  65         }
  66     }
  67
  68     /**
  69      * Handle an event
  70      *
  71      * Events are any point in the code that we want to expose for admins
  72      * or third-party developers to use.
  73      *
  74      * We pass in an array of arguments (including references, for stuff
  75      * that can be changed), and each assigned handler gets run with those
  76      * arguments. Exceptions can be thrown to indicate an error.
  77      *
  78      * @param string $name Name of the event that's happening
  79      * @param array  $args Arguments for handlers
  80      *
  81      * @return boolean flag saying whether to continue processing, based
  82      *                 on results of handlers.
  83      */
  84
  85     public static function handle($name, array $args=array()) {
  86         $result = null;
  87         if (array_key_exists($name, Event::$_handlers)) {
  88             foreach (Event::$_handlers[$name] as $handler) {
  89                 $result = call_user_func_array($handler, $args);
  90                 if ($result === false) {
  91                     break;
  92                 }
  93             }
  94         }
  95         return ($result !== false);
  96     }
  97
  98     /**
  99      * Check to see if an event handler exists
 100      *
 101      * Look to see if there's any handler for a given event, or narrow
 102      * by providing the name of a specific plugin class.
 103      *
 104      * @param string $name Name of the event to look for
 105      * @param string $plugin Optional name of the plugin class to look for
 106      *
 107      * @return boolean flag saying whether such a handler exists
 108      *
 109      */
 110
 111     public static function hasHandler($name, $plugin=null) {
 112         if (array_key_exists($name, Event::$_handlers)) {
 113             if (isset($plugin)) {
 114                 foreach (Event::$_handlers[$name] as $handler) {
 115                     if (get_class($handler[0]) == $plugin) {
 116                         return true;
 117                     }
 118                 }
 119             } else {
 120                 return true;
 121             }
 122         }
 123         return false;
 124     }
 125
 126     public static function getHandlers($name)
 127     {
 128         return Event::$_handlers[$name];
 129     }
 130
 131     /**
 132      * Disables any and all handlers that have been set up so far;
 133      * use only if you know it's safe to reinitialize all plugins.
 134      */
 135     public static function clearHandlers() {
 136         Event::$_handlers = array();
 137     }
 138 }