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