event.php 4.6 KB

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