2e9c99a0b6cc252b0ba605fc25c75535a50fa0d5
[moodle.git] / message / classes / helper.php
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU 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 // Moodle 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 General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
17 /**
18  * Contains helper class for the message area.
19  *
20  * @package    core_message
21  * @copyright  2016 Mark Nelson <markn@moodle.com>
22  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  */
25 namespace core_message;
27 defined('MOODLE_INTERNAL') || die();
29 /**
30  * Helper class for the message area.
31  *
32  * @copyright  2016 Mark Nelson <markn@moodle.com>
33  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
34  */
35 class helper {
37     /**
38      * Helper function to retrieve the messages between two users
39      *
40      * TODO: This function should be removed once the new group messaging UI is in place and the old messaging UI is removed.
41      * For now we are not removing/deprecating this function for backwards compatibility with messaging UI.
42      * Followup: MDL-63915
43      *
44      * @param int $userid the current user
45      * @param int $otheruserid the other user
46      * @param int $timedeleted the time the message was deleted
47      * @param int $limitfrom
48      * @param int $limitnum
49      * @param string $sort
50      * @param int $timefrom the time from the message being sent
51      * @param int $timeto the time up until the message being sent
52      * @return array of messages
53      */
54     public static function get_messages($userid, $otheruserid, $timedeleted = 0, $limitfrom = 0, $limitnum = 0,
55                                         $sort = 'timecreated ASC', $timefrom = 0, $timeto = 0) {
56         global $DB;
58         $hash = self::get_conversation_hash([$userid, $otheruserid]);
60         $sql = "SELECT m.id, m.useridfrom, m.subject, m.fullmessage, m.fullmessagehtml,
61                        m.fullmessageformat, m.smallmessage, m.timecreated, muaread.timecreated AS timeread
62                   FROM {message_conversations} mc
63             INNER JOIN {messages} m
64                     ON m.conversationid = mc.id
65              LEFT JOIN {message_user_actions} muaread
66                     ON (muaread.messageid = m.id
67                    AND muaread.userid = :userid1
68                    AND muaread.action = :readaction)";
69         $params = ['userid1' => $userid, 'readaction' => api::MESSAGE_ACTION_READ, 'convhash' => $hash];
71         if (empty($timedeleted)) {
72             $sql .= " LEFT JOIN {message_user_actions} mua
73                              ON (mua.messageid = m.id
74                             AND mua.userid = :userid2
75                             AND mua.action = :deleteaction
76                             AND mua.timecreated is NOT NULL)";
77         } else {
78             $sql .= " INNER JOIN {message_user_actions} mua
79                               ON (mua.messageid = m.id
80                              AND mua.userid = :userid2
81                              AND mua.action = :deleteaction
82                              AND mua.timecreated = :timedeleted)";
83             $params['timedeleted'] = $timedeleted;
84         }
86         $params['userid2'] = $userid;
87         $params['deleteaction'] = api::MESSAGE_ACTION_DELETED;
89         $sql .= " WHERE mc.convhash = :convhash";
91         if (!empty($timefrom)) {
92             $sql .= " AND m.timecreated >= :timefrom";
93             $params['timefrom'] = $timefrom;
94         }
96         if (!empty($timeto)) {
97             $sql .= " AND m.timecreated <= :timeto";
98             $params['timeto'] = $timeto;
99         }
101         if (empty($timedeleted)) {
102             $sql .= " AND mua.id is NULL";
103         }
105         $sql .= " ORDER BY m.$sort";
107         $messages = $DB->get_records_sql($sql, $params, $limitfrom, $limitnum);
108         foreach ($messages as &$message) {
109             $message->useridto = ($message->useridfrom == $userid) ? $otheruserid : $userid;
110         }
112         return $messages;
113     }
115     /**
116      * Helper function to retrieve conversation messages.
117      *
118      * @param  int $userid The current user.
119      * @param  int $convid The conversation identifier.
120      * @param  int $timedeleted The time the message was deleted
121      * @param  int $limitfrom Return a subset of records, starting at this point (optional).
122      * @param  int $limitnum Return a subset comprising this many records in total (optional, required if $limitfrom is set).
123      * @param  string $sort The column name to order by including optionally direction.
124      * @param  int $timefrom The time from the message being sent.
125      * @param  int $timeto The time up until the message being sent.
126      * @return array of messages
127      */
128     public static function get_conversation_messages(int $userid, int $convid, int $timedeleted = 0, int $limitfrom = 0,
129                                                      int $limitnum = 0, string $sort = 'timecreated ASC', int $timefrom = 0,
130                                                      int $timeto = 0) : array {
131         global $DB;
133         $sql = "SELECT m.id, m.useridfrom, m.subject, m.fullmessage, m.fullmessagehtml,
134                        m.fullmessageformat, m.smallmessage, m.timecreated, muaread.timecreated AS timeread
135                   FROM {message_conversations} mc
136             INNER JOIN {messages} m
137                     ON m.conversationid = mc.id
138              LEFT JOIN {message_user_actions} muaread
139                     ON (muaread.messageid = m.id
140                    AND muaread.userid = :userid1
141                    AND muaread.action = :readaction)";
142         $params = ['userid1' => $userid, 'readaction' => api::MESSAGE_ACTION_READ, 'convid' => $convid];
144         if (empty($timedeleted)) {
145             $sql .= " LEFT JOIN {message_user_actions} mua
146                              ON (mua.messageid = m.id
147                             AND mua.userid = :userid2
148                             AND mua.action = :deleteaction
149                             AND mua.timecreated is NOT NULL)";
150         } else {
151             $sql .= " INNER JOIN {message_user_actions} mua
152                               ON (mua.messageid = m.id
153                              AND mua.userid = :userid2
154                              AND mua.action = :deleteaction
155                              AND mua.timecreated = :timedeleted)";
156             $params['timedeleted'] = $timedeleted;
157         }
159         $params['userid2'] = $userid;
160         $params['deleteaction'] = api::MESSAGE_ACTION_DELETED;
162         $sql .= " WHERE mc.id = :convid";
164         if (!empty($timefrom)) {
165             $sql .= " AND m.timecreated >= :timefrom";
166             $params['timefrom'] = $timefrom;
167         }
169         if (!empty($timeto)) {
170             $sql .= " AND m.timecreated <= :timeto";
171             $params['timeto'] = $timeto;
172         }
174         if (empty($timedeleted)) {
175             $sql .= " AND mua.id is NULL";
176         }
178         $sql .= " ORDER BY m.$sort";
180         $messages = $DB->get_records_sql($sql, $params, $limitfrom, $limitnum);
182         return $messages;
183     }
185     /**
186      * Helper function to return a conversation messages with the involved members (only the ones
187      * who have sent any of these messages).
188      *
189      * @param int $userid The current userid.
190      * @param int $convid The conversation id.
191      * @param array $messages The formated array messages.
192      * @return array A conversation array with the messages and the involved members.
193      */
194     public static function format_conversation_messages(int $userid, int $convid, array $messages) : array {
195         global $USER;
197         // Create the conversation array.
198         $conversation = array(
199             'id' => $convid,
200         );
202         // Store the messages.
203         $arrmessages = array();
205         foreach ($messages as $message) {
206             // Store the message information.
207             $msg = new \stdClass();
208             $msg->id = $message->id;
209             $msg->useridfrom = $message->useridfrom;
210             $msg->text = message_format_message_text($message);
211             $msg->timecreated = $message->timecreated;
212             $arrmessages[] = $msg;
213         }
214         // Add the messages to the conversation.
215         $conversation['messages'] = $arrmessages;
217         // Get the users who have sent any of the $messages.
218         $memberids = array_unique(array_map(function($message) {
219             return $message->useridfrom;
220         }, $messages));
222         if (!empty($memberids)) {
223             // Get members information.
224             $conversation['members'] = self::get_member_info($userid, $memberids);
225         } else {
226             $conversation['members'] = array();
227         }
229         return $conversation;
230     }
232     /**
233      * Helper function to return an array of messages.
234      *
235      * TODO: This function should be removed once the new group messaging UI is in place and the old messaging UI is removed.
236      * For now we are not removing/deprecating this function for backwards compatibility with messaging UI.
237      * Followup: MDL-63915
238      *
239      * @param int $userid
240      * @param array $messages
241      * @return array
242      */
243     public static function create_messages($userid, $messages) {
244         // Store the messages.
245         $arrmessages = array();
247         // We always view messages from oldest to newest, ensure we have it in that order.
248         $lastmessage = end($messages);
249         $firstmessage = reset($messages);
250         if ($lastmessage->timecreated < $firstmessage->timecreated) {
251             $messages = array_reverse($messages);
252         }
254         // Keeps track of the last day, month and year combo we were viewing.
255         $day = '';
256         $month = '';
257         $year = '';
258         foreach ($messages as $message) {
259             // Check if we are now viewing a different block period.
260             $displayblocktime = false;
261             $date = usergetdate($message->timecreated);
262             if ($day != $date['mday'] || $month != $date['month'] || $year != $date['year']) {
263                 $day = $date['mday'];
264                 $month = $date['month'];
265                 $year = $date['year'];
266                 $displayblocktime = true;
267             }
268             // Store the message to pass to the renderable.
269             $msg = new \stdClass();
270             $msg->id = $message->id;
271             $msg->text = message_format_message_text($message);
272             $msg->currentuserid = $userid;
273             $msg->useridfrom = $message->useridfrom;
274             $msg->useridto = $message->useridto;
275             $msg->displayblocktime = $displayblocktime;
276             $msg->timecreated = $message->timecreated;
277             $msg->timeread = $message->timeread;
278             $arrmessages[] = $msg;
279         }
281         return $arrmessages;
282     }
284     /**
285      * Helper function for creating a contact object.
286      *
287      * @param \stdClass $contact
288      * @param string $prefix
289      * @return \stdClass
290      */
291     public static function create_contact($contact, $prefix = '') {
292         global $PAGE;
294         // Create the data we are going to pass to the renderable.
295         $userfields = \user_picture::unalias($contact, array('lastaccess'), $prefix . 'id', $prefix);
296         $data = new \stdClass();
297         $data->userid = $userfields->id;
298         $data->useridfrom = null;
299         $data->fullname = fullname($userfields);
300         // Get the user picture data.
301         $userpicture = new \user_picture($userfields);
302         $userpicture->size = 1; // Size f1.
303         $data->profileimageurl = $userpicture->get_url($PAGE)->out(false);
304         $userpicture->size = 0; // Size f2.
305         $data->profileimageurlsmall = $userpicture->get_url($PAGE)->out(false);
306         // Store the message if we have it.
307         $data->ismessaging = false;
308         $data->lastmessage = null;
309         $data->lastmessagedate = null;
310         $data->messageid = null;
311         if (isset($contact->smallmessage)) {
312             $data->ismessaging = true;
313             // Strip the HTML tags from the message for displaying in the contact area.
314             $data->lastmessage = clean_param($contact->smallmessage, PARAM_NOTAGS);
315             $data->lastmessagedate = $contact->timecreated;
316             $data->useridfrom = $contact->useridfrom;
317             if (isset($contact->messageid)) {
318                 $data->messageid = $contact->messageid;
319             }
320         }
321         $data->isonline = null;
322         $user = \core_user::get_user($data->userid);
323         if (self::show_online_status($user)) {
324             $data->isonline = self::is_online($userfields->lastaccess);
325         }
326         $data->isblocked = isset($contact->blocked) ? (bool) $contact->blocked : false;
327         $data->isread = isset($contact->isread) ? (bool) $contact->isread : false;
328         $data->unreadcount = isset($contact->unreadcount) ? $contact->unreadcount : null;
329         $data->conversationid = $contact->conversationid ?? null;
331         return $data;
332     }
334     /**
335      * Helper function for checking if we should show the user's online status.
336      *
337      * @param \stdClass $user
338      * @return boolean
339      */
340     public static function show_online_status($user) {
341         global $CFG;
343         require_once($CFG->dirroot . '/user/lib.php');
345         if ($lastaccess = user_get_user_details($user, null, array('lastaccess'))) {
346             if (isset($lastaccess['lastaccess'])) {
347                 return true;
348             }
349         }
351         return false;
352     }
354     /**
355      * Helper function for checking the time meets the 'online' condition.
356      *
357      * @param int $lastaccess
358      * @return boolean
359      */
360     public static function is_online($lastaccess) {
361         global $CFG;
363         // Variable to check if we consider this user online or not.
364         $timetoshowusers = 300; // Seconds default.
365         if (isset($CFG->block_online_users_timetosee)) {
366             $timetoshowusers = $CFG->block_online_users_timetosee * 60;
367         }
368         $time = time() - $timetoshowusers;
370         return $lastaccess >= $time;
371     }
373     /**
374      * Get providers preferences.
375      *
376      * @param array $providers
377      * @param int $userid
378      * @return \stdClass
379      */
380     public static function get_providers_preferences($providers, $userid) {
381         $preferences = new \stdClass();
383         // Get providers preferences.
384         foreach ($providers as $provider) {
385             foreach (array('loggedin', 'loggedoff') as $state) {
386                 $linepref = get_user_preferences('message_provider_' . $provider->component . '_' . $provider->name
387                     . '_' . $state, '', $userid);
388                 if ($linepref == '') {
389                     continue;
390                 }
391                 $lineprefarray = explode(',', $linepref);
392                 $preferences->{$provider->component.'_'.$provider->name.'_'.$state} = array();
393                 foreach ($lineprefarray as $pref) {
394                     $preferences->{$provider->component.'_'.$provider->name.'_'.$state}[$pref] = 1;
395                 }
396             }
397         }
399         return $preferences;
400     }
402     /**
403      * Requires the JS libraries for the toggle contact button.
404      *
405      * @return void
406      */
407     public static function togglecontact_requirejs() {
408         global $PAGE;
410         static $done = false;
411         if ($done) {
412             return;
413         }
415         $PAGE->requires->js_call_amd('core_message/toggle_contact_button', 'enhance', array('#toggle-contact-button'));
416         $done = true;
417     }
419     /**
420      * Returns the attributes to place on a contact button.
421      *
422      * @param object $user User object.
423      * @param bool $iscontact
424      * @return array
425      */
426     public static function togglecontact_link_params($user, $iscontact = false) {
427         $params = array(
428             'data-userid' => $user->id,
429             'data-is-contact' => $iscontact,
430             'id' => 'toggle-contact-button',
431             'role' => 'button',
432             'class' => 'ajax-contact-button',
433         );
435         return $params;
436     }
438     /**
439      * Returns the conversation hash between users for easy look-ups in the DB.
440      *
441      * @param array $userids
442      * @return string
443      */
444     public static function get_conversation_hash(array $userids) {
445         sort($userids);
447         return sha1(implode('-', $userids));
448     }
450     /**
451      * Returns the cache key for the time created value of the last message of this conversation.
452      *
453      * @param int $convid The conversation identifier.
454      * @return string The key.
455      */
456     public static function get_last_message_time_created_cache_key(int $convid) {
457         return $convid;
458     }
460     /**
461      * Checks if legacy messages exist for a given user.
462      *
463      * @param int $userid
464      * @return bool
465      */
466     public static function legacy_messages_exist($userid) {
467         global $DB;
469         $sql = "SELECT id
470                   FROM {message} m
471                  WHERE useridfrom = ?
472                     OR useridto = ?";
473         $messageexists = $DB->record_exists_sql($sql, [$userid, $userid]);
475         $sql = "SELECT id
476                   FROM {message_read} m
477                  WHERE useridfrom = ?
478                     OR useridto = ?";
479         $messagereadexists = $DB->record_exists_sql($sql, [$userid, $userid]);
481         return $messageexists || $messagereadexists;
482     }
484     /**
485      * Returns conversation member info for the supplied users, relative to the supplied referenceuserid.
486      *
487      * This is the basic structure used when returning members, and includes information about the relationship between each member
488      * and the referenceuser, such as a whether the referenceuser has marked the member as a contact, or has blocked them.
489      *
490      * @param int $referenceuserid the id of the user which check contact and blocked status.
491      * @param array $userids
492      * @param bool $includecontactrequests Do we want to include contact requests with this data?
493      * @param bool $includeprivacyinfo Do we want to include whether the user can message another, and if the user
494      *             requires a contact.
495      * @return array the array of objects containing member info, indexed by userid.
496      * @throws \coding_exception
497      * @throws \dml_exception
498      */
499     public static function get_member_info(int $referenceuserid, array $userids, bool $includecontactrequests = false,
500                                            bool $includeprivacyinfo = false) : array {
501         global $DB, $PAGE;
503         // Prevent exception being thrown when array is empty.
504         if (empty($userids)) {
505             return [];
506         }
508         list($useridsql, $usersparams) = $DB->get_in_or_equal($userids);
509         $userfields = \user_picture::fields('u', array('lastaccess'));
510         $userssql = "SELECT $userfields, u.deleted, mc.id AS contactid, mub.id AS blockedid
511                        FROM {user} u
512                   LEFT JOIN {message_contacts} mc
513                          ON ((mc.userid = ? AND mc.contactid = u.id) OR (mc.userid = u.id AND mc.contactid = ?))
514                   LEFT JOIN {message_users_blocked} mub
515                          ON (mub.userid = ? AND mub.blockeduserid = u.id)
516                       WHERE u.id $useridsql";
517         $usersparams = array_merge([$referenceuserid, $referenceuserid, $referenceuserid], $usersparams);
518         $otherusers = $DB->get_records_sql($userssql, $usersparams);
520         $members = [];
521         foreach ($otherusers as $member) {
522             // Set basic data.
523             $data = new \stdClass();
524             $data->id = $member->id;
525             $data->fullname = fullname($member);
527             // Set the user picture data.
528             $userpicture = new \user_picture($member);
529             $userpicture->size = 1; // Size f1.
530             $data->profileimageurl = $userpicture->get_url($PAGE)->out(false);
531             $userpicture->size = 0; // Size f2.
532             $data->profileimageurlsmall = $userpicture->get_url($PAGE)->out(false);
534             // Set online status indicators.
535             $data->isonline = false;
536             $data->showonlinestatus = false;
537             if (!$member->deleted) {
538                 $data->isonline = self::show_online_status($member) ? self::is_online($member->lastaccess) : null;
539                 $data->showonlinestatus = is_null($data->isonline) ? false : true;
540             }
542             // Set contact and blocked status indicators.
543             $data->iscontact = ($member->contactid) ? true : false;
544             $data->isblocked = ($member->blockedid) ? true : false;
546             $data->isdeleted = ($member->deleted) ? true : false;
548             $data->requirescontact = null;
549             $data->canmessage = null;
550             if ($includeprivacyinfo) {
551                 $privacysetting = api::get_user_privacy_messaging_preference($member->id);
552                 $data->requirescontact = $privacysetting == api::MESSAGE_PRIVACY_ONLYCONTACTS;
554                 $recipient = new \stdClass();
555                 $recipient->id = $member->id;
557                 $sender = new \stdClass();
558                 $sender->id = $referenceuserid;
560                 $data->canmessage = api::can_post_message($recipient, $sender);
561             }
563             // Populate the contact requests, even if we don't need them.
564             $data->contactrequests = [];
566             $members[$data->id] = $data;
567         }
569         // Check if we want to include contact requests as well.
570         if (!empty($members) && $includecontactrequests) {
571             list($useridsql, $usersparams) = $DB->get_in_or_equal($userids);
573             $wheresql = "(userid $useridsql AND requesteduserid = ?) OR (userid = ? AND requesteduserid $useridsql)";
574             $params = array_merge($usersparams, [$referenceuserid, $referenceuserid], $usersparams);
575             if ($contactrequests = $DB->get_records_select('message_contact_requests', $wheresql, $params,
576                     'timecreated ASC, id ASC')) {
577                 foreach ($contactrequests as $contactrequest) {
578                     if (isset($members[$contactrequest->userid])) {
579                         $members[$contactrequest->userid]->contactrequests[] = $contactrequest;
580                     }
581                     if (isset($members[$contactrequest->requesteduserid])) {
582                         $members[$contactrequest->requesteduserid]->contactrequests[] = $contactrequest;
583                     }
584                 }
585             }
586         }
588         return $members;
589     }
591     /**
592      * Backwards compatibility formatter, transforming the new output of get_conversations() into the old format.
593      *
594      * @param array $conversations the array of conversations, which must come from get_conversations().
595      * @return array the array of conversations, formatted in the legacy style.
596      */
597     public static function get_conversations_legacy_formatter(array $conversations) : array {
598         // Transform new data format back into the old format, just for BC during the deprecation life cycle.
599         $tmp = [];
600         foreach ($conversations as $id => $conv) {
601             // Only individual conversations were supported in legacy messaging.
602             if ($conv->type != \core_message\api::MESSAGE_CONVERSATION_TYPE_INDIVIDUAL) {
603                 continue;
604             }
605             $data = new \stdClass();
606             // The logic for the 'other user' is as follows:
607             // If a conversation is of type 'individual', the other user is always the member who is not the current user.
608             // If the conversation is of type 'group', the other user is always the sender of the most recent message.
609             // The get_conversations method already follows this logic, so we just need the first member.
610             $otheruser = reset($conv->members);
611             $data->userid = $otheruser->id;
612             $data->useridfrom = $conv->messages[0]->useridfrom ?? null;
613             $data->fullname = $conv->members[$otheruser->id]->fullname;
614             $data->profileimageurl = $conv->members[$otheruser->id]->profileimageurl;
615             $data->profileimageurlsmall = $conv->members[$otheruser->id]->profileimageurlsmall;
616             $data->ismessaging = isset($conv->messages[0]->text) ? true : false;
617             $data->lastmessage = $conv->messages[0]->text ? clean_param($conv->messages[0]->text, PARAM_NOTAGS) : null;
618             $data->lastmessagedate = $conv->messages[0]->timecreated ?? null;
619             $data->messageid = $conv->messages[0]->id ?? null;
620             $data->isonline = $conv->members[$otheruser->id]->isonline ?? null;
621             $data->isblocked = $conv->members[$otheruser->id]->isblocked ?? null;
622             $data->isread = $conv->isread;
623             $data->unreadcount = $conv->unreadcount;
624             $tmp[$data->userid] = $data;
625         }
626         return $tmp;
627     }