From d05fe335b89421857922ea81a433556617bc21b5 Mon Sep 17 00:00:00 2001
From: Dmitriy Simushev <simushevds@ossg.ru>
Date: Mon, 20 Oct 2014 10:12:55 +0000
Subject: [PATCH] Describe all "users" app related events in Events class

---
 .../classes/Mibew/EventDispatcher/Events.php  | 77 +++++++++++++++++++
 .../Mibew/RequestProcessor/UsersProcessor.php | 44 +++--------
 2 files changed, 88 insertions(+), 33 deletions(-)

diff --git a/src/mibew/libs/classes/Mibew/EventDispatcher/Events.php b/src/mibew/libs/classes/Mibew/EventDispatcher/Events.php
index 713f710a..5745811c 100644
--- a/src/mibew/libs/classes/Mibew/EventDispatcher/Events.php
+++ b/src/mibew/libs/classes/Mibew/EventDispatcher/Events.php
@@ -164,6 +164,83 @@ final class Events
      */
     const RESOURCE_NOT_FOUND = 'resourceNotFound';
 
+    /**
+     * Threads list is ready to be sent to client.
+     *
+     * This event is triggered before the threads list is sent to the "users"
+     * client side application. It provide an ability to alter the list. A
+     * plugin can attach some fields to each thread or completeley replace the
+     * whole list. An associative array with the following items is passed to
+     * the event handlers:
+     *   - "threads": array of threads data arrays.
+     */
+    const USERS_UPDATE_THREADS_ALTER = 'usersUpdateThreadsAlter';
+
+    /**
+     * Load custom on site visitors list.
+     *
+     * This event is triggered before the list of on site visitors is loaded for
+     * sending to the "users" client side application. It provide an ability for
+     * plugins to load, sort and limit visitors list. An associative array with
+     * the following items is passed to the event handlers:
+     *   - "visitors": array of visitors data arrays. Each visitor array must
+     *     contain at least the following keys: "id", "userName", "userAgent",
+     *     "userIp", "remote", "firstTime", "lastTime", "invitations",
+     *     "chats", "invitationInfo". If there are no visitors an empty array
+     *     should be used.
+     *
+     * If the "visitors" item was not set by a plugin the default system loader
+     * will be used.
+     */
+    const USERS_UPDATE_VISITORS_LOAD = 'usersUpdateVisitorsLoad';
+
+    /**
+     * On site visitors list is ready to be sent to client.
+     *
+     * This event is triggered before the on site visitors list is sent to the
+     * "users" client application. It provide an ability to alter the list.
+     * A plugin can attach some fields to each visitor or completeley replace
+     * the whole list. An associative array with the following items is passed
+     * to the event handlers:
+     *   - "visitors": array of visitors data arrays.
+     */
+    const USERS_UPDATE_VISITORS_ALTER = 'usersUpdateVisitorsAlter';
+
+    /**
+     * A function was called at client side "users" application.
+     *
+     * This event is triggered when an API a function is called at client side
+     * in the "users" application, but the system is not aware of this function.
+     *
+     * Plugins can implement custom API functions by attaching handlers to the
+     * event. If a plugin wants to return some results, it should use "results"
+     * element of the event arguments array (see below).
+     *
+     * An associative array with the following items is passed to the event
+     * handlers:
+     *   - "function": string, name of the function that was called.
+     *   - "arguments": associative array of arguments that was passed to the
+     *     function.
+     *   - "results": array, list of function results.
+     *
+     * Here is an example of the event handler:
+     * <code>
+     * public function callHandler(&$function)
+     * {
+     *     // Check that the function we want to implement is called.
+     *     if ($function['function'] == 'microtime') {
+     *         // Check some function's arguments.
+     *         $as_float = empty($function['arguments']['as_float'])
+     *             ? false
+     *             : $function['arguments']['as_float'];
+     *         // Invoke the function and return the results.
+     *         $function['results']['time'] = microtime($as_float);
+     *     }
+     * }
+     * </code>
+     */
+    const USERS_FUNCTION_CALL = 'usersFunctionCall';
+
     /**
      * Visitor is created.
      *
diff --git a/src/mibew/libs/classes/Mibew/RequestProcessor/UsersProcessor.php b/src/mibew/libs/classes/Mibew/RequestProcessor/UsersProcessor.php
index ddb5e15c..11a0b31b 100644
--- a/src/mibew/libs/classes/Mibew/RequestProcessor/UsersProcessor.php
+++ b/src/mibew/libs/classes/Mibew/RequestProcessor/UsersProcessor.php
@@ -24,24 +24,14 @@ use Mibew\Authentication\AuthenticationManagerAwareInterface;
 use Mibew\Authentication\AuthenticationManagerInterface;
 use Mibew\Database;
 use Mibew\EventDispatcher\EventDispatcher;
+use Mibew\EventDispatcher\Events;
 use Mibew\Settings;
 use Mibew\Thread;
 use Mibew\API\API as MibewAPI;
 use Mibew\RequestProcessor\Exception\UsersProcessorException;
 
 /**
- * Incapsulates awaiting users list api related functions.
- *
- * Events triggered by the class (see description of the RequestProcessor class
- * for details):
- *  - usersRequestReceived
- *  - usersReceiveRequestError
- *  - usersCallError
- *  - usersFunctionCall
- *
- * Also triggers follow events (see description of apiUpdateVisitors method):
- *  - usersUpdateVisitorsLoad
- *  - usersUpdateVisitorsAlter
+ * Incapsulates awaiting users list API related functions.
  */
 class UsersProcessor extends ClientSideProcessor implements AuthenticationManagerAwareInterface
 {
@@ -181,11 +171,8 @@ class UsersProcessor extends ClientSideProcessor implements AuthenticationManage
     /**
      * Return updated threads list. API function
      *
-     * Triggers the following events:
-     *  1. 'usersUpdateThreadsAlter': provide the ability to alter threads
-     *     list. Associative array is passed to event lister. It has the
-     *     following keys:
-     *      - 'threads': array of threads arrays.
+     * Triggers
+     * {@link \Mibew\EventDispatcher\Events::USERS_UPDATE_THREADS_ALTER} event.
      *
      * @param array $args Associative array of arguments. It must contains the
      *   following keys:
@@ -356,7 +343,7 @@ class UsersProcessor extends ClientSideProcessor implements AuthenticationManage
             'threads' => $threads,
         );
         $dispatcher = EventDispatcher::getInstance();
-        $dispatcher->triggerEvent('usersUpdateThreadsAlter', $arguments);
+        $dispatcher->triggerEvent(Events::USERS_UPDATE_THREADS_ALTER, $arguments);
 
         // Send results back to the client. "array_values" function should be
         // used to avoid problems with JSON conversion. If there will be gaps in
@@ -371,19 +358,10 @@ class UsersProcessor extends ClientSideProcessor implements AuthenticationManage
     /**
      * Return updated visitors list. API function.
      *
-     * Triggers following events:
-     *  1. 'usersUpdateVisitorsLoad': provide the ability to plugins to load,
-     *     sort and limiting visitors list. Associative array pass to event
-     *     lister have following keys:
-     *      - 'visitors': array of visitors arrays. Each visitor array must
-     *        contain at least following keys: 'id', 'userName', 'userAgent',
-     *        'userIp', 'remote', 'firstTime', 'lastTime', 'invitations',
-     *        'chats', 'invitationInfo'. If there are no visitors an empty array
-     *        should be used.
-     *
-     *  2. 'usersUpdateVisitorsAlter': provide the ability to alter visitors
-     *     list. Associative array pass to event lister have following keys:
-     *      - 'visitors': array of visitors arrays.
+     * Triggers
+     * {@link \Mibew\EventDispatcher\Events::USERS_UPDATE_VISITORS_LOAD} and
+     * {@link \Mibew\EventDispatcher\Events::USERS_UPDATE_VISITORS_ALTER}
+     * events.
      *
      * @param array $args Associative array of arguments. It must contains the
      *   following keys:
@@ -410,7 +388,7 @@ class UsersProcessor extends ClientSideProcessor implements AuthenticationManage
         $arguments = array(
             'visitors' => false
         );
-        $dispatcher->triggerEvent('usersUpdateVisitorsLoad', $arguments);
+        $dispatcher->triggerEvent(Events::USERS_UPDATE_VISITORS_LOAD, $arguments);
 
         // Check if visiors list loaded by plugins
         if (!is_array($arguments['visitors'])) {
@@ -502,7 +480,7 @@ class UsersProcessor extends ClientSideProcessor implements AuthenticationManage
         $arguments = array(
             'visitors' => $visitors,
         );
-        $dispatcher->triggerEvent('usersUpdateVisitorsAlter', $arguments);
+        $dispatcher->triggerEvent(Events::USERS_UPDATE_VISITORS_ALTER, $arguments);
 
         // Send results back to the client. "array_values" function should be
         // used to avoid problems with JSON conversion. If there will be gaps in