MDL-63549 core_message: deprecate data_for_messagearea_conversations

diff --git a/lib/db/services.php b/lib/db/services.php
index a9dcdd3..be6c06c 100644 (file)
--- a/lib/db/services.php
+++ b/lib/db/services.php
@@ -981,7 +981,8 @@ $functions = array(
         'classname' => 'core_message_external',
         'methodname' => 'data_for_messagearea_conversations',
         'classpath' => 'message/externallib.php',
-        'description' => 'Retrieve the template data for the conversation list',
+        'description' => '** DEPRECATED ** Please do not call this function any more.
+                          Retrieve the template data for the conversation list',
         'type' => 'read',
         'ajax' => true,
         'services' => array(MOODLE_OFFICIAL_MOBILE_SERVICE),

diff --git a/message/classes/helper.php b/message/classes/helper.php
index a1ce9eb..67dcf87 100644 (file)
--- a/message/classes/helper.php
+++ b/message/classes/helper.php
@@ -529,4 +529,37 @@ class helper {
         }
         return $members;
     }
+
+    /**
+     * Backwards compatibility formatter, transforming the new output of get_conversations() into the old format.
+     *
+     * @param array $conversations the array of conversations, which must come from get_conversations().
+     * @return array the array of conversations, formatted in the legacy style.
+     */
+    public static function get_conversations_legacy_formatter(array $conversations) : array {
+        // Transform new data format back into the old format, just for BC during the deprecation life cycle.
+        $tmp = [];
+        foreach ($conversations as $id => $conv) {
+            $data = new \stdClass();
+            // The logic for the 'other user' is as follows:
+            // If a conversation is of type 'individual', the other user is always the member who is not the current user.
+            // If the conversation is of type 'group', the other user is always the sender of the most recent message.
+            // The get_conversations method already follows this logic, so we just need the first member.
+            $otheruser = reset($conv->members);
+            $data->userid = $otheruser->id;
+            $data->useridfrom = $conv->messages[0]->useridfrom ?? null;
+            $data->fullname = $conv->members[$otheruser->id]->fullname;
+            $data->profileimageurl = $conv->members[$otheruser->id]->profileimageurl;
+            $data->profileimageurlsmall = $conv->members[$otheruser->id]->profileimageurlsmall;
+            $data->ismessaging = isset($conv->messages[0]->text) ? true : false;
+            $data->lastmessage = $conv->messages[0]->text ?? null;
+            $data->messageid = $conv->messages[0]->id ?? null;
+            $data->isonline = $conv->members[$otheruser->id]->isonline ?? null;
+            $data->isblocked = $conv->members[$otheruser->id]->isblocked ?? null;
+            $data->isread = $conv->isread;
+            $data->unreadcount = $conv->unreadcount;
+            $tmp[$data->userid] = $data;
+        }
+        return $tmp;
+    }
 }

diff --git a/message/externallib.php b/message/externallib.php
index ec7fa2c..0d71f3f 100644 (file)
--- a/message/externallib.php
+++ b/message/externallib.php
@@ -1273,6 +1273,7 @@ class core_message_external extends external_api {
     /**
      * The messagearea conversations parameters.
      *
+     * @deprecated since 3.6
      * @return external_function_parameters
      * @since 3.2
      */
@@ -1289,6 +1290,13 @@ class core_message_external extends external_api {
     /**
      * Get messagearea conversations.
      *
+     * NOTE FOR FINAL DEPRECATION:
+     * When removing this method, please also consider removal of get_conversations_legacy_formatter()
+     * from the \core_message\helper class. This helper method was used solely to format the new get_conversations() return data
+     * into the old format used here, and in message/index.php. If we no longer need either of these, then that method can be
+     * removed.
+     *
+     * @deprecated since 3.6
      * @param int $userid The id of the user who we are viewing conversations for
      * @param int $limitfrom
      * @param int $limitnum
@@ -1319,6 +1327,10 @@ class core_message_external extends external_api {
         }
 
         $conversations = \core_message\api::get_conversations($userid, $limitfrom, $limitnum);
+
+        // Format the conversations in the legacy style, as the get_conversations method has since been changed.
+        $conversations = \core_message\helper::get_conversations_legacy_formatter($conversations);
+
         $conversations = new \core_message\output\messagearea\contacts(null, $conversations);
 
         $renderer = $PAGE->get_renderer('core_message');
@@ -1328,6 +1340,7 @@ class core_message_external extends external_api {
     /**
      * The messagearea conversations return structure.
      *
+     * @deprecated since 3.6
      * @return external_single_structure
      * @since 3.2
      */
@@ -1341,6 +1354,15 @@ class core_message_external extends external_api {
         );
     }
 
+    /**
+     * Marking the method as deprecated.
+     *
+     * @return bool
+     */
+    public static function data_for_messagearea_conversations_is_deprecated() {
+        return true;
+    }
+
     /**
      * The messagearea contacts return parameters.
      *

diff --git a/message/index.php b/message/index.php
index 45cf605..9d30f34 100644 (file)
--- a/message/index.php
+++ b/message/index.php
@@ -106,6 +106,9 @@ if ($contactsfirst) {
     $conversations = \core_message\api::get_contacts($user1->id, 0, 20);
 } else {
     $conversations = \core_message\api::get_conversations($user1->id, 0, 20);
+
+    // Format the conversations in the legacy style, as the get_conversations method has since been changed.
+    $conversations = \core_message\helper::get_conversations_legacy_formatter($conversations);
 }
 $messages = [];
 if (!$user2realuser) {

diff --git a/message/upgrade.txt b/message/upgrade.txt
index a74dc18..5eaf792 100644 (file)
--- a/message/upgrade.txt
+++ b/message/upgrade.txt
@@ -44,6 +44,8 @@ information provided here is intended especially for developers.
   - core_message_external::delete_conversation(), please use core_message_external::delete_conversations_by_id() instead.
   - core_message_external::core_message_mark_all_messages_as_read(), please use
     core_message_external::core_message_mark_all_conversation_messages_as_read() instead.
+  - core_message_external::data_for_messagearea_conversations(), please use core_message_external::get_conversations()
+    instead
 * The following function has been added for getting the privacy messaging preference:
   - get_user_privacy_messaging_preference()