first commit

communication/provider/customlink/classes/communication_feature.php

@@ -0,0 +1,181 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_customlink;
+
+use core_communication\processor;
+
+/**
+ * class communication_feature to handle custom link specific actions.
+ *
+ * @package   communication_customlink
+ * @copyright 2023 Michael Hawkins <michaelh@moodle.com>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class communication_feature implements
+    \core_communication\communication_provider,
+    \core_communication\form_provider,
+    \core_communication\room_chat_provider {
+    /** @var string The database table storing custom link specific data */
+    protected const CUSTOMLINK_TABLE = 'communication_customlink';
+
+    /** @var \cache_application $cache The application cache for this provider. */
+    protected \cache_application $cache;
+
+    /**
+     * Load the communication provider for the communication API.
+     *
+     * @param processor $communication The communication processor object.
+     * @return communication_feature The communication provider object.
+     */
+    public static function load_for_instance(processor $communication): self {
+        return new self($communication);
+    }
+
+    /**
+     * Constructor for communication provider.
+     *
+     * @param processor $communication The communication processor object.
+     */
+    private function __construct(
+        private \core_communication\processor $communication,
+    ) {
+        $this->cache = \cache::make('communication_customlink', 'customlink');
+    }
+
+    /**
+     * Create room - room existence managed externally, always return true.
+     *
+     * @return boolean
+     */
+    public function create_chat_room(): bool {
+        return true;
+    }
+
+    /**
+     * Update room - room existence managed externally, always return true.
+     *
+     * @return boolean
+     */
+    public function update_chat_room(): bool {
+        return true;
+    }
+
+    /**
+     * Delete room - room existence managed externally, always return true.
+     *
+     * @return boolean
+     */
+    public function delete_chat_room(): bool {
+        return true;
+    }
+
+    /**
+     * Fetch the URL for this custom link provider.
+     *
+     * @return string|null The custom URL, or null if not found.
+     */
+    public function get_chat_room_url(): ?string {
+        global $DB;
+
+        $commid = $this->communication->get_id();
+        $cachekey = "link_url_{$commid}";
+
+        // Attempt to fetch the room URL from the cache.
+        if ($url = $this->cache->get($cachekey)) {
+            return $url;
+        }
+
+        // If not found in the cache, fetch the URL from the database.
+        $url = $DB->get_field(
+            self::CUSTOMLINK_TABLE,
+            'url',
+            ['commid' => $commid],
+        );
+
+        // Cache the URL.
+        $this->cache->set($cachekey, $url);
+
+        return $url;
+    }
+
+    public function save_form_data(\stdClass $instance): void {
+        if (empty($instance->customlinkurl)) {
+            return;
+        }
+
+        global $DB;
+
+        $commid = $this->communication->get_id();
+        $cachekey = "link_url_{$commid}";
+
+        $newrecord = new \stdClass();
+        $newrecord->url = $instance->customlinkurl;
+
+        $existingrecord = $DB->get_record(
+            self::CUSTOMLINK_TABLE,
+            ['commid' => $commid],
+            'id, url'
+        );
+
+        if (!$existingrecord) {
+            // Create the record if it does not exist.
+            $newrecord->commid = $commid;
+            $DB->insert_record(self::CUSTOMLINK_TABLE, $newrecord);
+        } else if ($instance->customlinkurl !== $existingrecord->url) {
+            // Update record if the URL has changed.
+            $newrecord->id = $existingrecord->id;
+            $DB->update_record(self::CUSTOMLINK_TABLE, $newrecord);
+        } else {
+            // No change made.
+            return;
+        }
+
+        // Cache the new URL.
+        $this->cache->set($cachekey, $newrecord->url);
+    }
+
+    public function set_form_data(\stdClass $instance): void {
+        if (!empty($instance->id) && !empty($this->communication->get_id())) {
+            $instance->customlinkurl = $this->get_chat_room_url();
+        }
+    }
+
+    public static function set_form_definition(\MoodleQuickForm $mform): void {
+        // Custom link description for the communication provider.
+        $mform->insertElementBefore($mform->createElement(
+            'text',
+            'customlinkurl',
+            get_string('customlinkurl', 'communication_customlink'),
+            'maxlength="255" size="40"'
+        ), 'addcommunicationoptionshere');
+        $mform->addHelpButton('customlinkurl', 'customlinkurl', 'communication_customlink');
+        $mform->setType('customlinkurl', PARAM_URL);
+        $mform->addRule('customlinkurl', get_string('required'), 'required', null, 'client');
+        $mform->addRule('customlinkurl', get_string('maximumchars', '', 255), 'maxlength', 255);
+        $mform->insertElementBefore($mform->createElement(
+            'static',
+            'customlinkurlinfo',
+            '',
+            get_string('customlinkurlinfo', 'communication_customlink'),
+            'addcommunicationoptionshere'
+        ), 'addcommunicationoptionshere');
+    }
+
+    public static function is_configured(): bool {
+        return true;
+    }
+}

communication/provider/customlink/classes/privacy/provider.php

@@ -0,0 +1,38 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_customlink\privacy;
+
+use core_privacy\local\metadata\null_provider;
+
+/**
+ * Privacy Subsystem for communication_customlink implementing null_provider.
+ *
+ * @package    communication_customlink
+ * @copyright  2023 Michael Hawkins <michaelh@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class provider implements null_provider {
+    /**
+     * Get the language string identifier with the component's language
+     * file to explain why this plugin stores no data.
+     *
+     * @return  string
+     */
+    public static function get_reason(): string {
+        return 'privacy:metadata';
+    }
+}

communication/provider/customlink/db/caches.php

@@ -0,0 +1,35 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * Defined caches used internally by the provider.
+ *
+ * @package   communication_customlink
+ * @copyright 2023 Michael Hawkins <michaelh@moodle.com>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+defined('MOODLE_INTERNAL') || die();
+
+$definitions = [
+    'customlink' => [
+        'mode' => cache_store::MODE_APPLICATION,
+        'simplekeys' => true,
+        'simpledata' => true,
+    ],
+];

communication/provider/customlink/db/install.xml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<XMLDB PATH="communication/provider/customlink/db" VERSION="20230826" COMMENT="Stores the link associated with a custom link communication instance."
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="../../../../lib/xmldb/xmldb.xsd"
+>
+  <TABLES>
+    <TABLE NAME="communication_customlink" COMMENT="Stores the link associated with a custom link communication instance.">
+      <FIELDS>
+        <FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="true"/>
+        <FIELD NAME="commid" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" COMMENT="ID of the communication record"/>
+        <FIELD NAME="url" TYPE="char" LENGTH="255" NOTNULL="false" SEQUENCE="false" COMMENT="URL being linked to by the provider"/>
+      </FIELDS>
+      <KEYS>
+        <KEY NAME="primary" TYPE="primary" FIELDS="id"/>
+        <KEY NAME="fk_commid" TYPE="foreign" FIELDS="commid" REFTABLE="communication" REFFIELDS="id" COMMENT="Foreign key for communication reference"/>
+      </KEYS>
+    </TABLE>
+  </TABLES>
+</XMLDB>

communication/provider/customlink/lang/en/communication_customlink.php

@@ -0,0 +1,30 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * Strings for component communication_customlink, language 'en'.
+ *
+ * @package    communication_customlink
+ * @copyright  2023 Michael Hawkins <michaelh@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+$string['cachedef_customlink'] = 'Custom link data';
+$string['customlinkurl'] = 'Custom link URL';
+$string['customlinkurl_help'] = 'Provide a link to an existing room from any communication service you would like to make available to participants - such as Microsoft Teams, Slack or Matrix.';
+$string['customlinkurlinfo'] = 'The URL of an existing room already set up for this course.';
+$string['pluginname'] = 'Custom link';
+$string['privacy:metadata'] = 'Custom link communication plugin does not store any personal data.';

communication/provider/customlink/tests/behat/custom_link.feature

@@ -0,0 +1,86 @@
+@communication @communication_customlink @javascript
+Feature: Communication custom link
+  In order to facilitate easy access to an existing communication platform
+  As a teacher
+  I need to be able to make a custom communication link available in my course
+
+  Background:
+    Given the following "users" exist:
+      | username | firstname | lastname | email                |
+      | teacher1 | Teacher   | 1        | teacher1@example.com |
+      | student1 | Student   | 1        | student1@example.com |
+    And the following "courses" exist:
+      | fullname  | shortname |
+      | Course 1  | C1        |
+    And the following "course enrolments" exist:
+      | user     | course | role           |
+      | teacher1 | C1     | editingteacher |
+      | student1 | C1     | student        |
+    And the following config values are set as admin:
+      | enablecommunicationsubsystem | 1 |
+
+  Scenario: As a teacher I can configure a custom communication provider for my course
+    Given I am on the "Course 1" "Course" page logged in as "teacher1"
+    And "Chat to course participants" "button" should not be visible
+    When I navigate to "Communication" in current page administration
+    And the "Provider" select box should contain "Custom link"
+    And I should not see "Custom link URL"
+    And I select "Custom link" from the "Provider" singleselect
+    And I should see "Custom link URL"
+    And I set the following fields to these values:
+      | communication_customlinkroomname | Test URL                                                                                   |
+      | customlinkurl                    | #wwwroot#/communication/provider/customlink/tests/behat/fixtures/custom_link_test_page.php |
+    And I press "Save changes"
+    Then "Chat to course participants" "button" should be visible
+    And I click on "Chat to course participants" "button"
+    # Check the link hits the expected destination.
+    And I switch to a second window
+    And I should see "Example messaging service - teacher1" in the "region-main" "region"
+    And I close all opened windows
+    # Ensure any communication subsystem tasks have no impact on availability.
+    And I run all adhoc tasks
+    And I am on the "Course 1" course page
+    And "Chat to course participants" "button" should be visible
+    And I click on "Chat to course participants" "button"
+    And I switch to a second window
+    And I should see "Example messaging service - teacher1" in the "region-main" "region"
+    And I close all opened windows
+    And I log out
+    # Confirm student also has access to the custom link.
+    And I am on the "Course 1" "Course" page logged in as "student1"
+    And "Chat to course participants" "button" should be visible
+    And I click on "Chat to course participants" "button"
+    And I switch to a second window
+    And I should see "Example messaging service - student1" in the "region-main" "region"
+
+  Scenario: As a teacher I can disable and re-enable a custom communication provider for my course
+    Given I am on the "Course 1" "Course" page logged in as "teacher1"
+    And "Chat to course participants" "button" should not be visible
+    When I navigate to "Communication" in current page administration
+    And I select "Custom link" from the "Provider" singleselect
+    And I set the following fields to these values:
+      | communication_customlinkroomname | Test URL                                                                                   |
+      | customlinkurl                    | #wwwroot#/communication/provider/customlink/tests/behat/fixtures/custom_link_test_page.php |
+    And I press "Save changes"
+    And "Chat to course participants" "button" should be visible
+    And I run all adhoc tasks
+    And I navigate to "Communication" in current page administration
+    And I select "None" from the "Provider" singleselect
+    And I press "Save changes"
+    And "Chat to course participants" "button" should not be visible
+    And I run all adhoc tasks
+    And I am on the "Course 1" course page
+    And "Chat to course participants" "button" should not be visible
+    And I navigate to "Communication" in current page administration
+    And I select "Custom link" from the "Provider" singleselect
+    And I set the following fields to these values:
+      | communication_customlinkroomname | Test URL                                                                                   |
+      | customlinkurl                    | #wwwroot#/communication/provider/customlink/tests/behat/fixtures/custom_link_test_page.php |
+    And I press "Save changes"
+    And "Chat to course participants" "button" should be visible
+    And I run all adhoc tasks
+    And I am on the "Course 1" course page
+    And "Chat to course participants" "button" should be visible
+    And I click on "Chat to course participants" "button"
+    And I switch to a second window
+    And I should see "Example messaging service - teacher1" in the "region-main" "region"

communication/provider/customlink/tests/behat/fixtures/custom_link_test_page.php

@@ -0,0 +1,40 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * A page which can be used to represent a messaging service while testing the custom link communication provider.
+ *
+ * The current Moodle user's username is listed in the heading to make it easier to confirm the page has been
+ * opened by the expected user.
+ *
+ * @package    communication_customlink
+ * @copyright  2023 Michael Hawkins <michaelh@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+require_once(__DIR__ . '/../../../../../../config.php');
+
+defined('BEHAT_SITE_RUNNING') || die();
+
+global $OUTPUT, $PAGE, $USER;
+
+$PAGE->set_url('/communication/provider/customlink/tests/behat/fixtures/custom_link_test_page.php');
+require_login();
+$PAGE->set_context(core\context\system::instance());
+
+echo $OUTPUT->header();
+echo "<h2>Example messaging service - {$USER->username}</h2>";
+echo "<p>Imagine this is a wonderful messaging service being accessed directly from a link in Moodle!</p>";
+echo $OUTPUT->footer();

communication/provider/customlink/tests/communication_feature_test.php

@@ -0,0 +1,144 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_customlink;
+
+use core_communication\processor;
+use core_communication\communication_test_helper_trait;
+
+defined('MOODLE_INTERNAL') || die();
+
+require_once(__DIR__ . '/../../../tests/communication_test_helper_trait.php');
+
+/**
+ * Class communication_feature_test to test the custom link features implemented using the core interfaces.
+ *
+ * @package    communication_customlink
+ * @category   test
+ * @copyright  2023 Michael Hawkins <michaelh@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @coversDefaultClass \communication_customlink\communication_feature
+ */
+class communication_feature_test extends \advanced_testcase {
+    use communication_test_helper_trait;
+
+    public function setUp(): void {
+        parent::setUp();
+        $this->resetAfterTest();
+        $this->setup_communication_configs();
+    }
+
+    /**
+     * Test create, update and delete chat room.
+     *
+     * @covers ::load_for_instance
+     */
+    public function test_load_for_instance(): void {
+        $communicationprocessor = $this->get_test_communication_processor();
+
+        $instance = communication_feature::load_for_instance($communicationprocessor);
+        $this->assertInstanceOf('communication_customlink\communication_feature', $instance);
+    }
+
+    /**
+     * Test create, update and delete chat room.
+     *
+     * @covers ::create_chat_room
+     * @covers ::update_chat_room
+     * @covers ::delete_chat_room
+     */
+    public function test_create_update_delete_chat_room(): void {
+        $communicationprocessor = $this->get_test_communication_processor();
+
+        // Create, update and delete room should always return true because this provider contains
+        // a link to a room, but does not manage the existence of the room.
+        $createroomresult = $communicationprocessor->get_room_provider()->create_chat_room();
+        $updateroomresult = $communicationprocessor->get_room_provider()->update_chat_room();
+        $deleteroomresult = $communicationprocessor->get_room_provider()->delete_chat_room();
+        $this->assertTrue($createroomresult);
+        $this->assertTrue($updateroomresult);
+        $this->assertTrue($deleteroomresult);
+    }
+
+    /**
+     * Test save form data with provider's custom field and fetching with get_chat_room_url().
+     *
+     * @covers ::save_form_data
+     * @covers ::get_chat_room_url
+     */
+    public function test_save_form_data(): void {
+        $communicationprocessor = $this->get_test_communication_processor();
+        $customlinkurl = 'https://moodle.org/message/index.php';
+        $formdatainstance = (object) ['customlinkurl' => $customlinkurl];
+
+        // Test the custom link URL is saved and can be retrieved as expected.
+        $communicationprocessor->get_form_provider()->save_form_data($formdatainstance);
+        $fetchedurl = $communicationprocessor->get_room_provider()->get_chat_room_url();
+        $this->assertEquals($customlinkurl, $fetchedurl);
+
+        // Test with empty customlinkurl.
+        $customlinkurlempty = '';
+        $formdatainstance = (object) ['customlinkurl' => $customlinkurlempty];
+        $communicationprocessor->get_form_provider()->save_form_data($formdatainstance);
+        $fetchedurl = $communicationprocessor->get_room_provider()->get_chat_room_url();
+        // It should not update the url to an empty one.
+        $this->assertEquals($customlinkurl, $fetchedurl);
+
+        // Test with null customlinkurl.
+        $customlinkurlempty = null;
+        $formdatainstance = (object) ['customlinkurl' => $customlinkurlempty];
+        $communicationprocessor->get_form_provider()->save_form_data($formdatainstance);
+        $fetchedurl = $communicationprocessor->get_room_provider()->get_chat_room_url();
+        // It should not update the url to a null one.
+        $this->assertEquals($customlinkurl, $fetchedurl);
+    }
+
+    /**
+     * Create a test custom link communication processor object.
+     *
+     * @return processor
+     */
+    protected function get_test_communication_processor(): processor {
+        $course = $this->getDataGenerator()->create_course();
+        $instanceid = $course->id;
+        $context = \core\context\system::instance();
+        $component = 'core_course';
+        $instancetype = 'coursecommunication';
+        $selectedcommunication = 'communication_customlink';
+        $communicationroomname = 'communicationroom';
+
+        $communicationprocessor = processor::create_instance(
+            $context,
+            $selectedcommunication,
+            $instanceid,
+            $component,
+            $instancetype,
+            $communicationroomname,
+        );
+
+        return $communicationprocessor;
+    }
+
+    /**
+     * Test if the selected provider is configured.
+     *
+     * @covers ::is_configured
+     */
+    public function test_is_configured(): void {
+        $communicationprocessor = $this->get_test_communication_processor();
+        $this->assertTrue($communicationprocessor->get_form_provider()->is_configured());
+    }
+}

communication/provider/customlink/version.php

@@ -0,0 +1,30 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * Version information for communication_customlink.
+ *
+ * @package    communication_customlink
+ * @copyright  2023 Michael Hawkins <michaelh@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+defined('MOODLE_INTERNAL') || die();
+
+$plugin->component = 'communication_customlink';
+$plugin->version = 2024042200;
+$plugin->requires = 2024041600;
+$plugin->maturity = MATURITY_ALPHA;

communication/provider/matrix/classes/communication_feature.php

@@ -0,0 +1,792 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix;
+
+use communication_matrix\local\spec\features\matrix\{
+    create_room_v3 as create_room_feature,
+    get_room_members_v3 as get_room_members_feature,
+    remove_member_from_room_v3 as remove_member_from_room_feature,
+    update_room_avatar_v3 as update_room_avatar_feature,
+    update_room_name_v3 as update_room_name_feature,
+    update_room_topic_v3 as update_room_topic_feature,
+    upload_content_v3 as upload_content_feature,
+    media_create_v1 as media_create_feature,
+};
+use communication_matrix\local\spec\features\synapse\{
+    create_user_v2 as create_user_feature,
+    get_room_info_v1 as get_room_info_feature,
+    get_user_info_v2 as get_user_info_feature,
+    invite_member_to_room_v1 as invite_member_to_room_feature,
+};
+use core_communication\processor;
+use stdClass;
+use GuzzleHttp\Psr7\Response;
+
+/**
+ * class communication_feature to handle matrix specific actions.
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Safat Shahin <safat.shahin@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class communication_feature implements
+    \core_communication\communication_provider,
+    \core_communication\form_provider,
+    \core_communication\room_chat_provider,
+    \core_communication\room_user_provider,
+    \core_communication\synchronise_provider,
+    \core_communication\user_provider {
+    /** @var ?matrix_room $room The matrix room object to update room information */
+    private ?matrix_room $room = null;
+
+    /** @var string|null The URI of the home server */
+    protected ?string $homeserverurl = null;
+
+    /** @var string The URI of the Matrix web client */
+    protected string $webclienturl;
+
+    /** @var \communication_matrix\local\spec\v1p1|null The Matrix API processor */
+    protected ?matrix_client $matrixapi;
+
+    /**
+     * Load the communication provider for the communication api.
+     *
+     * @param processor $communication The communication processor object
+     * @return communication_feature The communication provider object
+     */
+    public static function load_for_instance(processor $communication): self {
+        return new self($communication);
+    }
+
+    /**
+     * Reload the room information.
+     * This may be necessary after a room has been created or updated via the adhoc task.
+     * This is primarily intended for use in unit testing, but may have real world cases too.
+     */
+    public function reload(): void {
+        $this->room = null;
+        $this->processor = processor::load_by_id($this->processor->get_id());
+    }
+
+    /**
+     * Constructor for communication provider to initialize necessary objects for api cals etc..
+     *
+     * @param processor $processor The communication processor object
+     */
+    private function __construct(
+        private \core_communication\processor $processor,
+    ) {
+        $this->homeserverurl = get_config('communication_matrix', 'matrixhomeserverurl');
+        $this->webclienturl = get_config('communication_matrix', 'matrixelementurl');
+
+        if ($processor::is_provider_available('communication_matrix')) {
+            // Generate the API instance.
+            $this->matrixapi = matrix_client::instance(
+                serverurl: $this->homeserverurl,
+                accesstoken: get_config('communication_matrix', 'matrixaccesstoken'),
+            );
+        }
+    }
+
+    /**
+     * Check whether the room configuration has been created yet.
+     *
+     * @return bool
+     */
+    protected function room_exists(): bool {
+        return (bool) $this->get_room_configuration();
+    }
+
+    /**
+     * Whether the room exists on the remote server.
+     * This does not involve a remote call, but checks whether Moodle is aware of the room id.
+     * @return bool
+     */
+    protected function remote_room_exists(): bool {
+        $room = $this->get_room_configuration();
+
+        return $room && ($room->get_room_id() !== null);
+    }
+
+    /**
+     * Get the stored room configuration.
+     * @return null|matrix_room
+     */
+    public function get_room_configuration(): ?matrix_room {
+        $this->room = matrix_room::load_by_processor_id($this->processor->get_id());
+        return $this->room;
+    }
+
+    /**
+     * Return the current room id.
+     *
+     * @return string|null
+     */
+    public function get_room_id(): ?string {
+        return $this->get_room_configuration()?->get_room_id();
+    }
+
+    /**
+     * Create members.
+     *
+     * @param array $userids The Moodle user ids to create
+     */
+    public function create_members(array $userids): void {
+        $addedmembers = [];
+
+        // This API requiures the create_user feature.
+        $this->matrixapi->require_feature(create_user_feature::class);
+
+        foreach ($userids as $userid) {
+            $user = \core_user::get_user($userid);
+            $userfullname = fullname($user);
+
+            // Proceed if we have a user's full name and email to work with.
+            if (!empty($user->email) && !empty($userfullname)) {
+                $qualifiedmuid = matrix_user_manager::get_formatted_matrix_userid($user->username);
+
+                // First create user in matrix.
+                $response = $this->matrixapi->create_user(
+                    userid: $qualifiedmuid,
+                    displayname: $userfullname,
+                    threepids: [(object) [
+                        'medium' => 'email',
+                        'address' => $user->email,
+                    ], ],
+                    externalids: [],
+                );
+                $body = json_decode($response->getBody());
+
+                if (!empty($matrixuserid = $body->name)) {
+                    // Then create matrix user id in moodle.
+                    matrix_user_manager::set_matrix_userid_in_moodle($userid, $qualifiedmuid);
+                    if ($this->add_registered_matrix_user_to_room($matrixuserid)) {
+                        $addedmembers[] = $userid;
+                    }
+                }
+            }
+        }
+
+        // Set the power level of the users.
+        if (!empty($addedmembers) && $this->is_power_levels_update_required($addedmembers)) {
+            $this->set_matrix_power_levels();
+        }
+
+        // Mark then users as synced for the added members.
+        $this->processor->mark_users_as_synced($addedmembers);
+    }
+
+    public function update_room_membership(array $userids): void {
+
+        // Filter out any users that are not room members yet.
+        $response = $this->matrixapi->get_room_members(
+            roomid: $this->get_room_id(),
+        );
+        $body = self::get_body($response);
+
+        if (isset($body->joined)) {
+            foreach ($userids as $key => $userid) {
+                $matrixuserid = matrix_user_manager::get_matrixid_from_moodle(
+                    userid: $userid,
+                );
+                if (!array_key_exists($matrixuserid, (array) $body->joined)) {
+                    unset($userids[$key]);
+                }
+            }
+        }
+
+        $this->set_matrix_power_levels();
+        // Mark the users as synced for the updated members.
+        $this->processor->mark_users_as_synced($userids);
+    }
+
+    /**
+     * Add members to a room.
+     *
+     * @param array $userids The user ids to add
+     */
+    public function add_members_to_room(array $userids): void {
+        $unregisteredmembers = [];
+        $addedmembers = [];
+
+        foreach ($userids as $userid) {
+            $matrixuserid = matrix_user_manager::get_matrixid_from_moodle($userid);
+
+            if ($matrixuserid && $this->check_user_exists($matrixuserid)) {
+                if ($this->add_registered_matrix_user_to_room($matrixuserid)) {
+                    $addedmembers[] = $userid;
+                }
+            } else {
+                $unregisteredmembers[] = $userid;
+            }
+        }
+
+        // Set the power level of the users.
+        if (!empty($addedmembers) && $this->is_power_levels_update_required($addedmembers)) {
+            $this->set_matrix_power_levels();
+        }
+
+        // Mark then users as synced for the added members.
+        $this->processor->mark_users_as_synced($addedmembers);
+
+        // Create Matrix users.
+        if (count($unregisteredmembers) > 0) {
+            $this->create_members($unregisteredmembers);
+        }
+    }
+
+    /**
+     * Adds the registered matrix user id to room.
+     *
+     * @param string $matrixuserid Registered matrix user id
+     */
+    private function add_registered_matrix_user_to_room(string $matrixuserid): bool {
+        // Require the invite_member_to_room API feature.
+        $this->matrixapi->require_feature(invite_member_to_room_feature::class);
+
+        if (!$this->check_room_membership($matrixuserid)) {
+            $response = $this->matrixapi->invite_member_to_room(
+                roomid: $this->get_room_id(),
+                userid: $matrixuserid,
+            );
+
+            $body = self::get_body($response);
+            if (empty($body->room_id)) {
+                return false;
+            }
+
+            if ($body->room_id !== $this->get_room_id()) {
+                return false;
+            }
+
+            return true;
+        }
+        return false;
+    }
+
+    /**
+     * Remove members from a room.
+     *
+     * @param array $userids The Moodle user ids to remove
+     */
+    public function remove_members_from_room(array $userids): void {
+        // This API requiures the remove_members_from_room feature.
+        $this->matrixapi->require_feature(remove_member_from_room_feature::class);
+
+        if ($this->get_room_id() === null) {
+            return;
+        }
+
+        // Remove the power level for the user first.
+        $this->set_matrix_power_levels($userids);
+
+        $membersremoved = [];
+
+        $currentpowerlevels = $this->get_current_powerlevel_data();
+        $currentuserpowerlevels = (array) $currentpowerlevels->users ?? [];
+
+        foreach ($userids as $userid) {
+            // Check user is member of room first.
+            $matrixuserid = matrix_user_manager::get_matrixid_from_moodle($userid);
+
+            if (!$matrixuserid) {
+                // Unable to find a matrix userid for this user.
+                continue;
+            }
+
+            if (array_key_exists($matrixuserid, $currentuserpowerlevels)) {
+                if ($currentuserpowerlevels[$matrixuserid] >= matrix_constants::POWER_LEVEL_MAXIMUM) {
+                    // Skip removing the user if they are an admin.
+                    continue;
+                }
+            }
+
+            if (
+                $this->check_user_exists($matrixuserid) &&
+                $this->check_room_membership($matrixuserid)
+            ) {
+                $this->matrixapi->remove_member_from_room(
+                    roomid: $this->get_room_id(),
+                    userid: $matrixuserid,
+                );
+
+                $membersremoved[] = $userid;
+            }
+        }
+
+        $this->processor->delete_instance_user_mapping($membersremoved);
+    }
+
+    /**
+     * Check if a user exists in Matrix.
+     * Use if user existence is needed before doing something else.
+     *
+     * @param string $matrixuserid The Matrix user id to check
+     * @return bool
+     */
+    public function check_user_exists(string $matrixuserid): bool {
+        // This API requires the get_user_info feature.
+        $this->matrixapi->require_feature(get_user_info_feature::class);
+
+        $response = $this->matrixapi->get_user_info(
+            userid: $matrixuserid,
+        );
+        $body = self::get_body($response);
+
+        return isset($body->name);
+    }
+
+    /**
+     * Check if a user is a member of a room.
+     * Use if membership confirmation is needed before doing something else.
+     *
+     * @param string $matrixuserid The Matrix user id to check
+     * @return bool
+     */
+    public function check_room_membership(string $matrixuserid): bool {
+        // This API requires the get_room_members feature.
+        $this->matrixapi->require_feature(get_room_members_feature::class);
+
+        $response = $this->matrixapi->get_room_members(
+            roomid: $this->get_room_id(),
+        );
+        $body = self::get_body($response);
+
+        // Check user id is in the returned room member ids.
+        return isset($body->joined) && array_key_exists($matrixuserid, (array) $body->joined);
+    }
+
+    /**
+     * Create a room based on the data in the communication instance.
+     *
+     * @return bool
+     */
+    public function create_chat_room(): bool {
+        if ($this->remote_room_exists()) {
+            // A room already exists. Update it instead.
+            return $this->update_chat_room();
+        }
+
+        // This method requires the create_room API feature.
+        $this->matrixapi->require_feature(create_room_feature::class);
+
+        $room = $this->get_room_configuration();
+
+        $response = $this->matrixapi->create_room(
+            name: $this->processor->get_room_name(),
+            visibility: 'private',
+            preset: 'private_chat',
+            initialstate: [],
+            options: [
+                'topic' => $room->get_topic(),
+            ],
+        );
+
+        $response = self::get_body($response);
+
+        if (empty($response->room_id)) {
+            throw new \moodle_exception(
+                'Unable to determine ID of matrix room',
+            );
+        }
+
+        // Update our record of the matrix room_id.
+        $room->update_room_record(
+            roomid: $response->room_id,
+        );
+
+        // Update the room avatar.
+        $this->update_room_avatar();
+        return true;
+    }
+
+    public function update_chat_room(): bool {
+        if (!$this->remote_room_exists()) {
+            // No room exists. Create it instead.
+            return $this->create_chat_room();
+        }
+
+        $this->matrixapi->require_features([
+            get_room_info_feature::class,
+            update_room_name_feature::class,
+            update_room_topic_feature::class,
+        ]);
+
+        // Get room data.
+        $response = $this->matrixapi->get_room_info(
+            roomid: $this->get_room_id(),
+        );
+        $remoteroomdata = self::get_body($response);
+
+        // Update the room name when it's updated from the form.
+        if ($remoteroomdata->name !== $this->processor->get_room_name()) {
+            $this->matrixapi->update_room_name(
+                roomid: $this->get_room_id(),
+                name: $this->processor->get_room_name(),
+            );
+        }
+
+        // Update the room topic if set.
+        $localroomdata = $this->get_room_configuration();
+        if ($remoteroomdata->topic !== $localroomdata->get_topic()) {
+            $this->matrixapi->update_room_topic(
+                roomid: $localroomdata->get_room_id(),
+                topic: $localroomdata->get_topic(),
+            );
+        }
+
+        // Update room avatar.
+        $this->update_room_avatar();
+
+        return true;
+    }
+
+    public function delete_chat_room(): bool {
+        $this->get_room_configuration()->delete_room_record();
+        $this->room = null;
+
+        return true;
+    }
+
+    /**
+     * Update the room avatar when an instance image is added or updated.
+     */
+    public function update_room_avatar(): void {
+        // Both of the following features of the remote API are required.
+        $this->matrixapi->require_features([
+            upload_content_feature::class,
+            update_room_avatar_feature::class,
+        ]);
+
+        // Check if we have an avatar that needs to be synced.
+        if ($this->processor->is_avatar_synced()) {
+            return;
+        }
+
+        $instanceimage = $this->processor->get_avatar();
+        $contenturi = null;
+
+        if ($this->matrixapi->implements_feature(media_create_feature::class)) {
+            // From version 1.7 we can fetch a mxc URI and use it before uploading the content.
+            if ($instanceimage) {
+                $response = $this->matrixapi->media_create();
+                $contenturi = self::get_body($response)->content_uri;
+
+                // Now update the room avatar.
+                $response = $this->matrixapi->update_room_avatar(
+                    roomid: $this->get_room_id(),
+                    avatarurl: $contenturi,
+                );
+
+                // And finally upload the content.
+                $this->matrixapi->upload_content($instanceimage);
+            } else {
+                $response = $this->matrixapi->update_room_avatar(
+                    roomid: $this->get_room_id(),
+                    avatarurl: null,
+                );
+            }
+        } else {
+            // Prior to v1.7 the only way to upload content was to upload the content, which returns a mxc URI to use.
+
+            if ($instanceimage) {
+                // First upload the content.
+                $response = $this->matrixapi->upload_content($instanceimage);
+                $body = self::get_body($response);
+                $contenturi = $body->content_uri;
+            }
+
+            // Now update the room avatar.
+            $response = $this->matrixapi->update_room_avatar(
+                roomid: $this->get_room_id(),
+                avatarurl: $contenturi,
+            );
+        }
+
+        // Indicate the avatar has been synced if it was successfully set with Matrix.
+        if ($response->getReasonPhrase() === 'OK') {
+            $this->processor->set_avatar_synced_flag(true);
+        }
+    }
+
+    public function get_chat_room_url(): ?string {
+        if (!$this->get_room_id()) {
+            // We don't have a room id for this record.
+            return null;
+        }
+
+        return sprintf(
+            "%s#/room/%s",
+            $this->webclienturl,
+            $this->get_room_id(),
+        );
+    }
+
+    public function save_form_data(\stdClass $instance): void {
+        $matrixroomtopic = $instance->matrixroomtopic ?? null;
+        $room = $this->get_room_configuration();
+
+        if ($room) {
+            $room->update_room_record(
+                topic: $matrixroomtopic,
+            );
+        } else {
+            $this->room = matrix_room::create_room_record(
+                processorid: $this->processor->get_id(),
+                topic: $matrixroomtopic,
+            );
+        }
+    }
+
+    public function set_form_data(\stdClass $instance): void {
+        if (!empty($instance->id) && !empty($this->processor->get_id())) {
+            if ($this->room_exists()) {
+                $instance->matrixroomtopic = $this->get_room_configuration()->get_topic();
+            }
+        }
+    }
+
+    public static function set_form_definition(\MoodleQuickForm $mform): void {
+        // Room description for the communication provider.
+        $mform->insertElementBefore($mform->createElement(
+            'text',
+            'matrixroomtopic',
+            get_string('matrixroomtopic', 'communication_matrix'),
+            'maxlength="255" size="20"'
+        ), 'addcommunicationoptionshere');
+        $mform->addHelpButton('matrixroomtopic', 'matrixroomtopic', 'communication_matrix');
+        $mform->setType('matrixroomtopic', PARAM_TEXT);
+    }
+
+    /**
+     * Get the body of a response as a stdClass.
+     *
+     * @param Response $response
+     * @return stdClass
+     */
+    public static function get_body(Response $response): stdClass {
+        $body = $response->getBody();
+
+        return json_decode($body, false, 512, JSON_THROW_ON_ERROR);
+    }
+
+    /**
+     * Set the matrix power level with the room.
+     *
+     * Users with a non-moodle power level are not typically removed unless specified in the $forceremoval param.
+     * Matrix Admin users are never removed.
+     *
+     * @param array $forceremoval The users to force removal from the room, even if they have a custom power level
+     */
+    private function set_matrix_power_levels(
+        array $forceremoval = [],
+    ): void {
+        // Get the current power levels.
+        $currentpowerlevels = $this->get_current_powerlevel_data();
+        $currentuserpowerlevels = (array) $currentpowerlevels->users ?? [];
+
+        // Get all the current users who need to be in the room.
+        $userlist = $this->processor->get_all_userids_for_instance();
+
+        // Translate the user ids to matrix user ids.
+        $userlist = array_combine(
+            array_map(
+                fn ($userid) => matrix_user_manager::get_matrixid_from_moodle($userid),
+                $userlist,
+            ),
+            $userlist,
+        );
+
+        // Determine the power levels, and filter out anyone with the default level.
+        $newuserpowerlevels = array_filter(
+            array_map(
+                fn($userid) => $this->get_user_allowed_power_level($userid),
+                $userlist,
+            ),
+            fn($level) => $level !== matrix_constants::POWER_LEVEL_DEFAULT,
+        );
+
+        // Keep current room admins, and users which don't use our MODERATOR power level without changing them.
+        $staticusers = $this->get_users_with_custom_power_level($currentuserpowerlevels);
+        foreach ($staticusers as $userid => $level) {
+            $newuserpowerlevels[$userid] = $level;
+        }
+
+        if (!empty($forceremoval)) {
+            // Remove the users from the power levels if they are not admins.
+            foreach ($forceremoval as $userid) {
+                $muid = matrix_user_manager::get_matrixid_from_moodle($userid);
+                if (isset($newuserpowerlevels[$muid]) && $newuserpowerlevels[$muid] < matrix_constants::POWER_LEVEL_MAXIMUM) {
+                    unset($newuserpowerlevels[$muid]);
+                }
+            }
+        }
+
+        if (!$this->power_levels_changed($currentuserpowerlevels, $newuserpowerlevels)) {
+            // No changes to make.
+            return;
+        }
+
+        // Update the power levels for the room.
+        $this->matrixapi->update_room_power_levels(
+            roomid: $this->get_room_id(),
+            users: $newuserpowerlevels,
+        );
+    }
+
+    /**
+     * Filter the list of users provided to remove those with a moodle-related power level.
+     *
+     * @param array $users
+     * @return array
+     */
+    private function get_users_with_custom_power_level(array $users): array {
+        return array_filter(
+            $users,
+            function ($level): bool {
+                switch ($level) {
+                    case matrix_constants::POWER_LEVEL_DEFAULT:
+                    case matrix_constants::POWER_LEVEL_MOODLE_SITE_ADMIN:
+                    case matrix_constants::POWER_LEVEL_MOODLE_MODERATOR:
+                        return false;
+                    default:
+                        return true;
+                }
+            },
+        );
+    }
+
+    /**
+     * Check whether power levels have changed compared with the proposed power levels.
+     *
+     * @param array $currentuserpowerlevels The current power levels
+     * @param array $newuserpowerlevels The new power levels proposed
+     * @return bool Whether there is any change to be made
+     */
+    private function power_levels_changed(
+        array $currentuserpowerlevels,
+        array $newuserpowerlevels,
+    ): bool {
+        if (count($newuserpowerlevels) !== count($currentuserpowerlevels)) {
+            // Different number of keys - there must be a difference then.
+            return true;
+        }
+
+        // Sort the power levels.
+        ksort($newuserpowerlevels, SORT_NUMERIC);
+
+        // Get the current power levels.
+        ksort($currentuserpowerlevels);
+
+        $diff = array_merge(
+            array_diff_assoc(
+                $newuserpowerlevels,
+                $currentuserpowerlevels,
+            ),
+            array_diff_assoc(
+                $currentuserpowerlevels,
+                $newuserpowerlevels,
+            ),
+        );
+
+        return count($diff) > 0;
+    }
+
+    /**
+     * Get the current power level for the room.
+     *
+     * @return stdClass
+     */
+    private function get_current_powerlevel_data(): \stdClass {
+        $roomid = $this->get_room_id();
+        $response = $this->matrixapi->get_room_power_levels(
+            roomid: $roomid,
+        );
+        if ($response->getStatusCode() !== 200) {
+            throw new \moodle_exception(
+                'Unable to get power levels for room',
+            );
+        }
+
+        return $this->get_body($response);
+    }
+
+    /**
+     * Determine if a power level update is required.
+     * Matrix will always set a user to the default power level of 0 when a power level update is made.
+     * That is, unless we specify another level. As long as one person's level is greater than the default,
+     * we will need to set the power levels of all users greater than the default.
+     *
+     * @param array $userids The users to evaluate
+     * @return boolean Returns true if an update is required
+     */
+    private function is_power_levels_update_required(array $userids): bool {
+        // Is the user's power level greater than the default?
+        foreach ($userids as $userid) {
+            if ($this->get_user_allowed_power_level($userid) > matrix_constants::POWER_LEVEL_DEFAULT) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Get the allowed power level for the user id according to perms/site admin or default.
+     *
+     * @param int $userid
+     * @return int
+     */
+    public function get_user_allowed_power_level(int $userid): int {
+        $powerlevel = matrix_constants::POWER_LEVEL_DEFAULT;
+
+        if (has_capability('communication/matrix:moderator', $this->processor->get_context(), $userid)) {
+            $powerlevel = matrix_constants::POWER_LEVEL_MOODLE_MODERATOR;
+        }
+
+        // If site admin, override all caps.
+        if (is_siteadmin($userid)) {
+            $powerlevel = matrix_constants::POWER_LEVEL_MOODLE_SITE_ADMIN;
+        }
+
+        return $powerlevel;
+    }
+
+    /*
+     * Check if matrix settings are configured
+     *
+     * @return boolean
+     */
+    public static function is_configured(): bool {
+        // Matrix communication settings.
+        $matrixhomeserverurl = get_config('communication_matrix', 'matrixhomeserverurl');
+        $matrixaccesstoken = get_config('communication_matrix', 'matrixaccesstoken');
+        $matrixelementurl = get_config('communication_matrix', 'matrixelementurl');
+
+        if (
+            !empty($matrixhomeserverurl) &&
+            !empty($matrixaccesstoken) &&
+            (PHPUNIT_TEST || defined('BEHAT_SITE_RUNNING') || !empty($matrixelementurl))
+        ) {
+            return true;
+        }
+        return false;
+    }
+
+    public function synchronise_room_members(): void {
+        $this->set_matrix_power_levels();
+    }
+}

communication/provider/matrix/classes/local/command.php

@@ -0,0 +1,189 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix\local;
+
+use communication_matrix\matrix_client;
+use GuzzleHttp\Psr7\Request;
+use OutOfRangeException;
+
+/**
+ * A command to be sent to the Matrix server.
+ *
+ * This class is a wrapper around the PSR-7 Request Interface implementation provided by Guzzle.
+ *
+ * It takes a set of common parameters and configurations and turns them into a Request that can be called against a live server.
+ *
+ * @package    communication_matrix
+ * @copyright  Andrew Nicols <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class command extends Request {
+    /** @var array $command The raw command data */
+    /** @var array|null $params The parameters passed into the command */
+    /** @var bool $sendasjson Whether to send params as JSON */
+    /** @var bool $requireauthorization Whether authorization is required for this request */
+    /** @var bool $ignorehttperrors Whether to ignore HTTP Errors */
+    /** @var array $query Any query parameters to set on the URL */
+
+    /** @var array|null Any parameters not used in the URI which are to be passed to the server via body or query params */
+    protected array $remainingparams = [];
+
+    /**
+     * Create a new Command.
+     *
+     * @param matrix_client $client The URL for this method
+     * @param string $method (GET|POST|PUT|DELETE)
+     * @param string $endpoint The URL
+     * @param array $params Any parameters to pass
+     * @param array $query Any query parameters to set on the URL
+     * @param bool $ignorehttperrors Whether to ignore HTTP Errors
+     * @param bool $requireauthorization Whether authorization is required for this request
+     * @param bool $sendasjson Whether to send params as JSON
+     */
+    public function __construct(
+        protected matrix_client $client,
+        string $method,
+        string $endpoint,
+        protected array $params = [],
+        protected array $query = [],
+        protected bool $ignorehttperrors = false,
+        protected bool $requireauthorization = true,
+        protected bool $sendasjson = true,
+    ) {
+        foreach ($params as $name => $value) {
+            if ($name[0] === ':') {
+                if (preg_match("/{$name}\\b/", $endpoint) !== 1) {
+                    throw new OutOfRangeException("Parameter not found in URL '{$name}'");
+                }
+
+                $endpoint = preg_replace("/{$name}\\b/", urlencode($value), $endpoint);
+                unset($params[$name]);
+            }
+        }
+
+        // Store the modified params.
+        $this->remainingparams = $params;
+
+        if (str_contains($endpoint, '/:')) {
+            throw new OutOfRangeException("URL contains untranslated parameters '{$endpoint}'");
+        }
+
+        // Process the required headers.
+        $headers = [
+            'Content-Type' => 'application/json',
+        ];
+
+        if ($this->require_authorization()) {
+            $headers['Authorization'] = 'Bearer ' . $this->client->get_token();
+        }
+
+        // Construct the final request.
+        parent::__construct(
+            $method,
+            $this->get_url($endpoint),
+            $headers,
+        );
+    }
+
+    /**
+     * Get the URL of the endpoint on the server.
+     *
+     * @param string $endpoint
+     * @return string
+     */
+    protected function get_url(string $endpoint): string {
+        return sprintf(
+            "%s/%s",
+            $this->client->get_server_url(),
+            $endpoint,
+        );
+    }
+
+    /**
+     * Get all parameters, including those set in the URL.
+     *
+     * @return array
+     */
+    public function get_all_params(): array {
+        return $this->params;
+    }
+
+    /**
+     * Get the parameters provided to the command which are not used in the URL.
+     *
+     * These are typically passed to the server as query or body parameters instead.
+     *
+     * @return array
+     */
+    public function get_remaining_params(): array {
+        return $this->remainingparams;
+    }
+
+    /**
+     * Get the Guzzle options to pass into the request.
+     *
+     * @return array
+     */
+    public function get_options(): array {
+        $options = [];
+
+        if (count($this->query)) {
+            $options['query'] = $this->query;
+        }
+
+        if ($this->should_send_params_as_json()) {
+            $options['json'] = $this->get_remaining_params();
+        }
+
+        if ($this->should_ignore_http_errors()) {
+            $options['http_errors'] = false;
+        }
+
+        return $options;
+    }
+
+    /**
+     * Whether authorization is required.
+     *
+     * Based on the 'authorization' attribute set in a raw command.
+     *
+     * @return bool
+     */
+    public function require_authorization(): bool {
+        return $this->requireauthorization;
+    }
+
+    /**
+     * Whether to ignore http errors on the response.
+     *
+     * Based on the 'ignore_http_errors' attribute set in a raw command.
+     *
+     * @return bool
+     */
+    public function should_ignore_http_errors(): bool {
+        return $this->ignorehttperrors;
+    }
+
+    /**
+     * Whether to send remaining parameters as JSON.
+     *
+     * @return bool
+     */
+    public function should_send_params_as_json(): bool {
+        return $this->sendasjson;
+    }
+}

communication/provider/matrix/classes/local/spec/features/matrix/create_room_v3.php

@@ -0,0 +1,78 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix\local\spec\features\matrix;
+
+use communication_matrix\local\command;
+use GuzzleHttp\Psr7\Response;
+
+/**
+ * Matrix API feature for room creation.
+ *
+ * https://spec.matrix.org/v1.1/client-server-api/#post_matrixclientv3createroom
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @codeCoverageIgnore
+ * This code does not warrant being tested. Testing offers no discernible benefit given its usage is tested.
+ */
+trait create_room_v3 {
+    /**
+     * Create a new room.
+     *
+     * @param string $name The room name
+     * @param null|string $visibility The room visibility
+     * @param null|string $preset The preset to use
+     * @param null|array $initialstate Initial state variables
+     * @param array $options Any additional options
+     * @return Response
+     */
+    public function create_room(
+        string $name,
+        ?string $visibility = null,
+        ?string $preset = null,
+        ?array $initialstate = null,
+        array $options = [],
+    ): Response {
+        $params = [
+            'name' => $name,
+        ];
+
+        if ($visibility !== null) {
+            $params['visibility'] = $visibility;
+        }
+
+        if ($preset !== null) {
+            $params['preset'] = $preset;
+        }
+
+        if ($initialstate !== null) {
+            $params['initial_state'] = $initialstate;
+        }
+
+        if (array_key_exists('topic', $options)) {
+            $params['topic'] = $options['topic'] ?? '';
+        }
+
+        return $this->execute(new command(
+            $this,
+            method: 'POST',
+            endpoint: '_matrix/client/v3/createRoom',
+            params: $params,
+        ));
+    }
+}

communication/provider/matrix/classes/local/spec/features/matrix/get_room_members_v3.php

@@ -0,0 +1,52 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix\local\spec\features\matrix;
+
+use communication_matrix\local\command;
+use GuzzleHttp\Psr7\Response;
+
+/**
+ * Matrix API feature to fetch a list of room members.
+ *
+ * https://spec.matrix.org/v1.1/client-server-api/#get_matrixclientv3roomsroomidjoined_members
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @codeCoverageIgnore
+ * This code does not warrant being tested. Testing offers no discernible benefit given its usage is tested.
+ */
+trait get_room_members_v3 {
+    /**
+     * Get a list of room members.
+     *
+     * @param string $roomid The room ID
+     * @return Response
+     */
+    public function get_room_members(string $roomid): Response {
+        $params = [
+            ':roomid' => $roomid,
+        ];
+
+        return $this->execute(new command(
+            $this,
+            method: 'GET',
+            endpoint: '_matrix/client/v3/rooms/:roomid/joined_members',
+            params: $params,
+        ));
+    }
+}

communication/provider/matrix/classes/local/spec/features/matrix/get_room_power_levels_v3.php

@@ -0,0 +1,53 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix\local\spec\features\matrix;
+
+use communication_matrix\local\command;
+use GuzzleHttp\Psr7\Response;
+
+/**
+ * Matrix API feature to fetch room power levels.
+ *
+ * https://spec.matrix.org/v1.1/client-server-api/#mroompower_levels
+ *
+ * @package    communication_matrix
+ * @copyright  2024 David Woloszyn <david.woloszyn@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @codeCoverageIgnore
+ * This code does not warrant being tested. Testing offers no discernible benefit given its usage is tested.
+ */
+trait get_room_power_levels_v3 {
+    /**
+     * Get a list of room members and their power levels.
+     *
+     * @param string $roomid The room ID
+     * @return Response
+     */
+    public function get_room_power_levels(string $roomid): Response {
+
+        $params = [
+            ':roomid' => $roomid,
+        ];
+
+        return $this->execute(new command(
+            $this,
+            method: 'GET',
+            endpoint: '_matrix/client/r0/rooms/:roomid/state/m.room.power_levels',
+            params: $params,
+        ));
+    }
+}

communication/provider/matrix/classes/local/spec/features/matrix/get_room_powerlevels_from_sync_v3.php

@@ -0,0 +1,91 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix\local\spec\features\matrix;
+
+use communication_matrix\local\command;
+use GuzzleHttp\Psr7\Response;
+
+/**
+ * Matrix API feature to fetch room power levels using the sync API.
+ *
+ * https://spec.matrix.org/v1.1/client-server-api/#get_matrixclientv3sync
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @codeCoverageIgnore
+ * This code does not warrant being tested. Testing offers no discernible benefit given its usage is tested.
+ */
+trait get_room_powerlevels_from_sync_v3 {
+    /**
+     * Get a list of room members.
+     *
+     * @param string $roomid The room ID
+     * @return Response
+     */
+    public function get_room_power_levels_from_sync(string $roomid): Response {
+        // Filter the event data according to the API:
+        // https://spec.matrix.org/v1.1/client-server-api/#filtering
+        // We have to filter out all of the object data that we do not want,
+        // and set a filter to only fetch the one room that we do want.
+        $filter = (object) [
+            "account_data" => (object) [
+                // We don't want any account info for this call.
+                "not_types" => ['*'],
+            ],
+            "event_fields" => [
+                // We only care about type, and content. Not sender.
+                "type",
+                "content",
+            ],
+            "event_format" => "client",
+            "presence" => (object) [
+                // We don't need any presence data.
+                "not_types" => ['*'],
+            ],
+            "room" => (object) [
+                // We only want state information for power levels, not timeline and ephemeral data.
+                "rooms" => [
+                    $roomid,
+                ],
+                "state" => (object) [
+                    "types" => [
+                        "m.room.power_levels",
+                    ],
+                ],
+                "ephemeral" => (object) [
+                    "not_types" => ['*'],
+                ],
+                "timeline" => (object) [
+                    "not_types" => ['*'],
+                ],
+            ],
+        ];
+
+        $query = [
+            'filter' => json_encode($filter),
+        ];
+
+        return $this->execute(new command(
+            $this,
+            method: 'GET',
+            endpoint: '_matrix/client/v3/sync',
+            query: $query,
+            sendasjson: false,
+        ));
+    }
+}

communication/provider/matrix/classes/local/spec/features/matrix/media_create_v1.php

@@ -0,0 +1,46 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix\local\spec\features\matrix;
+
+use communication_matrix\local\command;
+use GuzzleHttp\Psr7\Response;
+
+/**
+ * Matrix API feature to create an mxc Media URI.
+ *
+ * https://spec.matrix.org/v1.1/client-server-api/#post_matrixmediav3upload
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @codeCoverageIgnore
+ * This code does not warrant being tested. Testing offers no discernible benefit given its usage is tested.
+ */
+trait media_create_v1 {
+    /**
+     * Create a media URI.
+     *
+     * @return Response
+     */
+    public function media_create(): Response {
+        return $this->execute(new command(
+            $this,
+            method: 'POST',
+            endpoint: '_matrix/media/v1/create',
+        ));
+    }
+}

communication/provider/matrix/classes/local/spec/features/matrix/remove_member_from_room_v3.php

@@ -0,0 +1,57 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix\local\spec\features\matrix;
+
+use communication_matrix\local\command;
+use GuzzleHttp\Psr7\Response;
+
+/**
+ * Matrix API feature to remove a member from a room.
+ *
+ * https://spec.matrix.org/v1.1/client-server-api/#post_matrixclientv3roomsroomidkick
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @codeCoverageIgnore
+ * This code does not warrant being tested. Testing offers no discernible benefit given its usage is tested.
+ */
+trait remove_member_from_room_v3 {
+    /**
+     * Remove a member from a room.
+     *
+     * @param string $roomid The roomid to remove from
+     * @param string $userid The member to remove
+     * @return Response
+     */
+    public function remove_member_from_room(
+        string $roomid,
+        string $userid,
+    ): Response {
+        $params = [
+            ':roomid' => $roomid,
+            'user_id' => $userid,
+        ];
+
+        return $this->execute(new command(
+            $this,
+            method: 'POST',
+            endpoint: '_matrix/client/v3/rooms/:roomid/kick',
+            params: $params,
+        ));
+    }
+}

communication/provider/matrix/classes/local/spec/features/matrix/update_room_avatar_v3.php

@@ -0,0 +1,58 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix\local\spec\features\matrix;
+
+use communication_matrix\local\command;
+use GuzzleHttp\Psr7\Response;
+
+/**
+ * Matrix API feature to update a room avatar.
+ *
+ * https://spec.matrix.org/v1.1/client-server-api/#put_matrixclientv3roomsroomidstateeventtypestatekey
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @codeCoverageIgnore
+ * This code does not warrant being tested. Testing offers no discernible benefit given its usage is tested.
+ */
+trait update_room_avatar_v3 {
+    /**
+     * Set the avatar for a room to the specified URL.
+     *
+     * @param string $roomid The roomid to set for
+     * @param null|string $avatarurl The mxc URL to use
+     * @return Response
+     */
+    public function update_room_avatar(
+        string $roomid,
+        ?string $avatarurl,
+    ): Response {
+        $params = [
+            ':roomid' => $roomid,
+            'url' => $avatarurl,
+        ];
+
+        return $this->execute(new command(
+            $this,
+            method: 'PUT',
+            endpoint: '_matrix/client/v3/rooms/:roomid/state/m.room.avatar',
+            ignorehttperrors: true,
+            params: $params,
+        ));
+    }
+}

communication/provider/matrix/classes/local/spec/features/matrix/update_room_name_v3.php

@@ -0,0 +1,54 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix\local\spec\features\matrix;
+
+use communication_matrix\local\command;
+use GuzzleHttp\Psr7\Response;
+
+/**
+ * Matrix API feature to update a room name.
+ *
+ * https://spec.matrix.org/v1.1/client-server-api/#put_matrixclientv3roomsroomidstateeventtypestatekey
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @codeCoverageIgnore
+ * This code does not warrant being tested. Testing offers no discernible benefit given its usage is tested.
+ */
+trait update_room_name_v3 {
+    /**
+     * Set the name for a room.
+     *
+     * @param string $roomid
+     * @param string $name
+     * @return Response
+     */
+    public function update_room_name(string $roomid, string $name): Response {
+        $params = [
+            ':roomid' => $roomid,
+            'name' => $name,
+        ];
+
+        return $this->execute(new command(
+            $this,
+            method: 'PUT',
+            endpoint: '_matrix/client/v3/rooms/:roomid/state/m.room.name',
+            params: $params,
+        ));
+    }
+}

communication/provider/matrix/classes/local/spec/features/matrix/update_room_power_levels_v3.php

@@ -0,0 +1,77 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix\local\spec\features\matrix;
+
+use communication_matrix\local\command;
+use communication_matrix\matrix_constants;
+use GuzzleHttp\Psr7\Response;
+
+/**
+ * Matrix API feature to update a room power levels.
+ *
+ * Matrix rooms have a concept of power levels, which are used to determine what actions a user can perform in a room.
+ *
+ * https://spec.matrix.org/v1.1/client-server-api/#mroompower_levels
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Safat Shahin <safat.shahin@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @codeCoverageIgnore
+ * This code does not warrant being tested. Testing offers no discernible benefit given its usage is tested.
+ */
+trait update_room_power_levels_v3 {
+    /**
+     * Set the avatar for a room to the specified URL.
+     *
+     * @param string $roomid The roomid to set for
+     * @param array $users The users to set power levels for
+     * @param int $ban The level required to ban a user
+     * @param int $invite The level required to invite a user
+     * @param int $kick The level required to kick a user
+     * @param array $notifications The level required to send notifications
+     * @param int $redact The level required to redact events
+     * @return Response
+     */
+    public function update_room_power_levels(
+        string $roomid,
+        array $users,
+        int $ban = matrix_constants::POWER_LEVEL_MAXIMUM,
+        int $invite = matrix_constants::POWER_LEVEL_MODERATOR,
+        int $kick = matrix_constants::POWER_LEVEL_MODERATOR,
+        array $notifications = [
+            'room' => matrix_constants::POWER_LEVEL_MODERATOR,
+        ],
+        int $redact = matrix_constants::POWER_LEVEL_MODERATOR,
+    ): Response {
+        $params = [
+            ':roomid' => $roomid,
+            'ban' => $ban,
+            'invite' => $invite,
+            'kick' => $kick,
+            'notifications' => $notifications,
+            'redact' => $redact,
+            'users' => $users,
+        ];
+
+        return $this->execute(new command(
+            $this,
+            method: 'PUT',
+            endpoint: '_matrix/client/v3/rooms/:roomid/state/m.room.power_levels',
+            params: $params,
+        ));
+    }
+}

communication/provider/matrix/classes/local/spec/features/matrix/update_room_topic_v3.php

@@ -0,0 +1,54 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix\local\spec\features\matrix;
+
+use communication_matrix\local\command;
+use GuzzleHttp\Psr7\Response;
+
+/**
+ * Matrix API feature to update a room topic.
+ *
+ * https://spec.matrix.org/v1.1/client-server-api/#put_matrixclientv3roomsroomidstateeventtypestatekey
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @codeCoverageIgnore
+ * This code does not warrant being tested. Testing offers no discernible benefit given its usage is tested.
+ */
+trait update_room_topic_v3 {
+    /**
+     * Set the topic for a room.
+     *
+     * @param string $roomid
+     * @param string $topic
+     * @return Response
+     */
+    public function update_room_topic(string $roomid, string $topic): Response {
+        $params = [
+            ':roomid' => $roomid,
+            'topic' => $topic,
+        ];
+
+        return $this->execute(new command(
+            $this,
+            method: 'PUT',
+            endpoint: '_matrix/client/v3/rooms/:roomid/state/m.room.topic',
+            params: $params,
+        ));
+    }
+}

communication/provider/matrix/classes/local/spec/features/matrix/upload_content_v3.php

@@ -0,0 +1,83 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix\local\spec\features\matrix;
+
+use communication_matrix\local\command;
+use GuzzleHttp\Psr7\Response;
+use GuzzleHttp\Psr7\Utils;
+
+/**
+ * Matrix API feature to upload content.
+ *
+ * https://spec.matrix.org/v1.1/client-server-api/#post_matrixmediav3upload
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @codeCoverageIgnore
+ * This code does not warrant being tested. Testing offers no discernible benefit given its usage is tested.
+ */
+trait upload_content_v3 {
+    /**
+     * Upload the content in the matrix/synapse server.
+     *
+     * @param null|\stored_file $content The content to be uploaded
+     * @param null|string $mediaid The mediaid to associate a file with. Supported for v1.7 API an above only.
+     * @return Response
+     */
+    public function upload_content(
+        ?\stored_file $content,
+        ?string $mediaid = null,
+    ): Response {
+        $query = [];
+        if ($content) {
+            $query['filename'] = $content->get_filename();
+        }
+
+        if ($mediaid !== null) {
+            // Specification of the mediaid requires version 1.7 or above of the upload API.
+            // See https://spec.matrix.org/v1.7/client-server-api/#put_matrixmediav3uploadservernamemediaid.
+            $this->requires_version('1.7');
+            $command = new command(
+                $this,
+                method: 'PUT',
+                endpoint: '_matrix/media/v3/upload/:mediaid',
+                sendasjson: false,
+                query: $query,
+                params: [
+                    ':mediaid' => $mediaid,
+                ],
+            );
+        } else {
+            $command = new command(
+                $this,
+                method: 'POST',
+                endpoint: '_matrix/media/v3/upload',
+                sendasjson: false,
+                query: $query,
+            );
+        }
+
+        if ($content) {
+            // Add the content-type, and header.
+            $command = $command->withHeader('Content-Type', $content->get_mimetype());
+            $command = $command->withBody(Utils::streamFor($content->get_content()));
+        }
+
+        return $this->execute($command);
+    }
+}

communication/provider/matrix/classes/local/spec/features/synapse/create_user_v2.php

@@ -0,0 +1,65 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix\local\spec\features\synapse;
+
+use communication_matrix\local\command;
+use GuzzleHttp\Psr7\Response;
+
+/**
+ * Synapse API feature for creating a user.
+ *
+ * https://matrix-org.github.io/synapse/latest/admin_api/user_admin_api.html#create-or-modify-account
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @codeCoverageIgnore
+ * This code does not warrant being tested. Testing offers no discernible benefit given its usage is tested.
+ */
+trait create_user_v2 {
+    /**
+     * Create a new user.
+     *
+     * @param string $userid The Matrix user id.
+     * @param string $displayname The visible name of the user
+     * @param array $threepids The third-party identifiers of the user.
+     * @param null|array $externalids
+     */
+    public function create_user(
+        string $userid,
+        string $displayname,
+        array $threepids,
+        ?array $externalids = null,
+    ): Response {
+        $params = [
+            ':userid' => $userid,
+            'displayname' => $displayname,
+            'threepids' => $threepids,
+        ];
+
+        if ($externalids !== null) {
+            $params['externalids'] = $externalids;
+        }
+
+        return $this->execute(new command(
+            $this,
+            method: 'PUT',
+            endpoint: '_synapse/admin/v2/users/:userid',
+            params: $params,
+        ));
+    }
+}

communication/provider/matrix/classes/local/spec/features/synapse/get_room_info_v1.php

@@ -0,0 +1,50 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix\local\spec\features\synapse;
+
+use communication_matrix\local\command;
+use GuzzleHttp\Psr7\Response;
+
+/**
+ * Synapse API feature for fetching room info.
+ *
+ * https://matrix-org.github.io/synapse/latest/admin_api/rooms.html#room-details-api
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @codeCoverageIgnore
+ * This code does not warrant being tested. Testing offers no discernible benefit given its usage is tested.
+ */
+trait get_room_info_v1 {
+    /**
+     * Get room info.
+     *
+     * @param string $roomid
+     * @return Response
+     */
+    public function get_room_info(string $roomid): Response {
+        return $this->execute(new command(
+            $this,
+            method: 'GET',
+            endpoint: '_synapse/admin/v1/rooms/:roomid',
+            params: [
+                ':roomid' => $roomid,
+            ],
+        ));
+    }
+}

communication/provider/matrix/classes/local/spec/features/synapse/get_user_info_v2.php

@@ -0,0 +1,51 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix\local\spec\features\synapse;
+
+use communication_matrix\local\command;
+use GuzzleHttp\Psr7\Response;
+
+/**
+ * Synapse API feature for fetching info about a user.
+ *
+ * https://matrix-org.github.io/synapse/latest/admin_api/user_admin_api.html#query-user-account
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @codeCoverageIgnore
+ * This code does not warrant being tested. Testing offers no discernible benefit given its usage is tested.
+ */
+trait get_user_info_v2 {
+    /**
+     * Get user info.
+     *
+     * @param string $userid
+     * @return Response
+     */
+    public function get_user_info(string $userid): Response {
+        return $this->execute(new command(
+            $this,
+            method: 'GET',
+            endpoint: '_synapse/admin/v2/users/:userid',
+            ignorehttperrors: true,
+            params: [
+                ':userid' => $userid,
+            ],
+        ));
+    }
+}

communication/provider/matrix/classes/local/spec/features/synapse/invite_member_to_room_v1.php

@@ -0,0 +1,56 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix\local\spec\features\synapse;
+
+use communication_matrix\local\command;
+use GuzzleHttp\Psr7\Response;
+
+/**
+ * Synapse API feature to invite a user into a room.
+ *
+ * https://matrix-org.github.io/synapse/latest/admin_api/room_membership.html#edit-room-membership-api
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @codeCoverageIgnore
+ * This code does not warrant being tested. Testing offers no discernible benefit given its usage is tested.
+ */
+trait invite_member_to_room_v1 {
+    /**
+     * Join a user to a room.
+     *
+     * Note: This joins the user, and does not invite them.
+     *
+     * @param string $roomid
+     * @param string $userid
+     * @return Response
+     */
+    public function invite_member_to_room(string $roomid, string $userid): Response {
+        $params = [
+            ':roomid' => $roomid,
+            'user_id' => $userid,
+        ];
+
+        return $this->execute(new command(
+            $this,
+            method: 'POST',
+            endpoint: '_synapse/admin/v1/join/:roomid',
+            params: $params,
+        ));
+    }
+}

communication/provider/matrix/classes/local/spec/v1p1.php

@@ -0,0 +1,48 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix\local\spec;
+
+/**
+ * Matrix API to support version v1.1 of the Matrix specification.
+ *
+ * https://spec.matrix.org/v1.1/client-server-api/
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class v1p1 extends \communication_matrix\matrix_client {
+    // Use the standard matrix API for these features.
+    use features\matrix\create_room_v3;
+    use features\matrix\get_room_members_v3;
+    use features\matrix\remove_member_from_room_v3;
+    use features\matrix\update_room_avatar_v3;
+    use features\matrix\update_room_name_v3;
+    use features\matrix\update_room_topic_v3;
+    use features\matrix\upload_content_v3;
+    use features\matrix\update_room_power_levels_v3;
+    use features\matrix\get_room_powerlevels_from_sync_v3;
+    use features\matrix\get_room_power_levels_v3;
+
+    // We use the Synapse API here because it can invite users to a room without requiring them to accept the invite.
+    use features\synapse\invite_member_to_room_v1;
+
+    // User information and creation is a server-specific feature.
+    use features\synapse\get_user_info_v2;
+    use features\synapse\create_user_v2;
+    use features\synapse\get_room_info_v1;
+}

communication/provider/matrix/classes/local/spec/v1p2.php

@@ -0,0 +1,30 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix\local\spec;
+
+/**
+ * Matrix API to support version v1.2 of the Matrix specification.
+ *
+ * https://spec.matrix.org/v1.2/client-server-api/
+ * https://spec.matrix.org/v1.2/changelog/#api-changes
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class v1p2 extends v1p1 {
+}

communication/provider/matrix/classes/local/spec/v1p3.php

@@ -0,0 +1,30 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix\local\spec;
+
+/**
+ * Matrix API to support version v1.3 of the Matrix specification.
+ *
+ * https://spec.matrix.org/v1.3/client-server-api/
+ * https://spec.matrix.org/v1.3/changelog/#api-changes
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class v1p3 extends v1p2 {
+}

communication/provider/matrix/classes/local/spec/v1p4.php

@@ -0,0 +1,30 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix\local\spec;
+
+/**
+ * Matrix API to support version v1.4 of the Matrix specification.
+ *
+ * https://spec.matrix.org/v1.4/client-server-api/
+ * https://spec.matrix.org/v1.4/changelog/#api-changes
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class v1p4 extends v1p3 {
+}

communication/provider/matrix/classes/local/spec/v1p5.php

@@ -0,0 +1,30 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix\local\spec;
+
+/**
+ * Matrix API to support version v1.5 of the Matrix specification.
+ *
+ * https://spec.matrix.org/v1.5/client-server-api/
+ * https://spec.matrix.org/v1.5/changelog/#api-changes
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class v1p5 extends v1p4 {
+}

communication/provider/matrix/classes/local/spec/v1p6.php

@@ -0,0 +1,30 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix\local\spec;
+
+/**
+ * Matrix API to support version v1.6 of the Matrix specification.
+ *
+ * https://spec.matrix.org/v1.6/client-server-api/
+ * https://spec.matrix.org/v1.6/changelog/#api-changes
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class v1p6 extends v1p5 {
+}

communication/provider/matrix/classes/local/spec/v1p7.php

@@ -0,0 +1,34 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix\local\spec;
+
+/**
+ * Matrix API to support version v1.7 of the Matrix specification.
+ *
+ * https://spec.matrix.org/v1.7/client-server-api/
+ * https://spec.matrix.org/v1.7/changelog/#api-changes
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class v1p7 extends v1p6 {
+    // Note: A new Content Upload API was introduced.
+    // See details in the spec:
+    // https://github.com/matrix-org/matrix-spec-proposals/pull/2246.
+    use features\matrix\media_create_v1;
+}

communication/provider/matrix/classes/matrix_client.php

@@ -0,0 +1,348 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix;
+
+use communication_matrix\local\command;
+use core\http_client;
+use DirectoryIterator;
+use Exception;
+use GuzzleHttp\Psr7\Response;
+
+/**
+ * The abstract class for a versioned API client for Matrix.
+ *
+ * Matrix uses a versioned API, and a handshake occurs between the Client (Moodle) and server, to determine the APIs available.
+ *
+ * This client represents a version-less API client.
+ * Versions are implemented by combining the various features into a versionedclass.
+ * See v1p1 for example.
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+abstract class matrix_client {
+    /** @var string $serverurl The URL of the home server */
+    /** @var string $accesstoken The access token of the matrix server */
+
+    /** @var http_client|null The client to use */
+    protected static http_client|null $client = null;
+
+    /**
+     * Matrix events constructor to get the room id and refresh token usage if required.
+     *
+     * @param string $serverurl The URL of the API server
+     * @param string $accesstoken The admin access token
+     */
+    protected function __construct(
+        protected string $serverurl,
+        protected string $accesstoken,
+    ) {
+    }
+
+    /**
+     * Return the versioned instance of the API.
+     *
+     * @param string $serverurl The URL of the API server
+     * @param string $accesstoken The admin access token to use
+     * @return matrix_client|null
+     */
+    public static function instance(
+        string $serverurl,
+        string $accesstoken,
+    ): ?matrix_client {
+        // Fetch the list of supported API versions.
+        $clientversions = self::get_supported_versions();
+
+        // Fetch the supported versions from the server.
+        $serversupports = self::query_server_supports($serverurl);
+        if ($serversupports === null) {
+            // Unable to fetch the server versions.
+            return null;
+        }
+        $serverversions = $serversupports->versions;
+
+        // Calculate the intersections and sort to determine the highest combined version.
+        $versions = array_intersect($clientversions, $serverversions);
+        if (count($versions) === 0) {
+            // No versions in common.
+            throw new \moodle_exception('No supported Matrix API versions found.');
+        }
+        asort($versions);
+        $version = array_key_last($versions);
+
+        $classname = \communication_matrix\local\spec::class . '\\' . $version;
+
+        return new $classname(
+            $serverurl,
+            $accesstoken,
+        );
+    }
+
+    /**
+     * Determine if the API supports a feature.
+     *
+     * If an Array is provided, this will return true if any of the specified features is implemented.
+     *
+     * @param string[]|string $feature The feature to check. This is in the form of a namespaced class.
+     * @return bool
+     */
+    public function implements_feature(array|string $feature): bool {
+        if (is_array($feature)) {
+            foreach ($feature as $thisfeature) {
+                if ($this->implements_feature($thisfeature)) {
+                    return true;
+                }
+            }
+
+            // None of the features are implemented in this API version.
+            return false;
+        }
+
+        return in_array($feature, $this->get_supported_features());
+    }
+
+    /**
+     * Get a list of the features supported by this client.
+     *
+     * @return string[]
+     */
+    public function get_supported_features(): array {
+        $features = [];
+        $class = static::class;
+        do {
+            $features = array_merge($features, class_uses($class));
+            $class = get_parent_class($class);
+        } while ($class);
+
+        return $features;
+    }
+
+    /**
+     * Require that the API supports a feature.
+     *
+     * If an Array is provided, this is treated as a require any of the features.
+     *
+     * @param string[]|string $feature The feature to test
+     * @throws \moodle_exception
+     */
+    public function require_feature(array|string $feature): void {
+        if (!$this->implements_feature($feature)) {
+            if (is_array($feature)) {
+                $features = implode(', ', $feature);
+                throw new \moodle_exception(
+                    "None of the possible feature are implemented in this Matrix Client: '{$features}'"
+                );
+            }
+            throw new \moodle_exception("The requested feature is not implemented in this Matrix Client: '{$feature}'");
+        }
+    }
+
+    /**
+     * Require that the API supports a list of features.
+     *
+     * All features specified will be required.
+     *
+     * If an array is provided as one of the features, any of the items in the nested array will be required.
+     *
+     * @param string[]|array[] $features The list of features required
+     *
+     * Here is an example usage:
+     * <code>
+     * $matrixapi->require_features([
+     *
+     *     \communication_matrix\local\spec\features\create_room::class,
+     *     [
+     *         \communication_matrix\local\spec\features\get_room_info_v1::class,
+     *         \communication_matrix\local\spec\features\get_room_info_v2::class,
+     *     ]
+     * ])
+     * </code>
+     */
+    public function require_features(array $features): void {
+        array_walk($features, [$this, 'require_feature']);
+    }
+
+    /**
+     * Get the URL of the server.
+     *
+     * @return string
+     */
+    public function get_server_url(): string {
+        return $this->serverurl;
+    }
+
+    /**
+     * Query the supported versions, and any unstable features, from the server.
+     *
+     * Servers must implement the client versions API described here:
+     * - https://spec.matrix.org/latest/client-server-api/#get_matrixclientversions
+     *
+     * @param string $serverurl The server base
+     * @return null|\stdClass The list of supported versions and a list of enabled unstable features
+     */
+    protected static function query_server_supports(string $serverurl): ?\stdClass {
+        // Attempt to return from the cache first.
+        $cache = \cache::make('communication_matrix', 'serverversions');
+        $serverkey = sha1($serverurl);
+        if ($cache->get($serverkey)) {
+            return $cache->get($serverkey);
+        }
+
+        // Not in the cache - fetch and store in the cache.
+        try {
+            $client = static::get_http_client();
+            $response = $client->get("{$serverurl}/_matrix/client/versions");
+
+            $supportsdata = json_decode(
+                json: $response->getBody(),
+                associative: false,
+                flags: JSON_THROW_ON_ERROR,
+            );
+
+            $cache->set($serverkey, $supportsdata);
+            return $supportsdata;
+        } catch (\GuzzleHttp\Exception\TransferException $e) {
+            return null;
+        }
+    }
+
+    /**
+     * Get the list of supported versions based on the available classes.
+     *
+     * @return array
+     */
+    public static function get_supported_versions(): array {
+        $versions = [];
+        $iterator = new DirectoryIterator(__DIR__ . '/local/spec');
+        foreach ($iterator as $fileinfo) {
+            if ($fileinfo->isDir()) {
+                continue;
+            }
+
+            // Get the classname from the filename.
+            $classname = substr($fileinfo->getFilename(), 0, -4);
+
+            if (!preg_match('/^v\d+p\d+$/', $classname)) {
+                // @codeCoverageIgnoreStart
+                // This file does not fit the format v[MAJOR]p[MINOR]].
+                continue;
+                // @codeCoverageIgnoreEnd
+            }
+
+            $versions[$classname] = "v" . self::get_version_from_classname($classname);
+        }
+
+        return $versions;
+    }
+
+    /**
+     * Get the current token in use.
+     *
+     * @return string
+     */
+    public function get_token(): string {
+        return $this->accesstoken;
+    }
+
+    /**
+     * Helper to fetch the HTTP Client for the instance.
+     *
+     * @return \core\http_client
+     */
+    protected function get_client(): \core\http_client {
+        return static::get_http_client();
+    }
+
+    /**
+     * Helper to fetch the HTTP Client.
+     *
+     * @return \core\http_client
+     */
+    protected static function get_http_client(): \core\http_client {
+        if (static::$client !== null) {
+            return static::$client;
+        }
+        // @codeCoverageIgnoreStart
+        return new http_client();
+        // @codeCoverageIgnoreEnd
+    }
+
+    /**
+     * Execute the specified command.
+     *
+     * @param command $command
+     * @return Response
+     */
+    protected function execute(
+        command $command,
+    ): Response {
+        $client = $this->get_client();
+        return $client->send(
+            $command,
+            $command->get_options(),
+        );
+    }
+
+    /**
+     * Get the API version of the current instance.
+     *
+     * @return string
+     */
+    public function get_version(): string {
+        $reflect = new \ReflectionClass(static::class);
+        $classname = $reflect->getShortName();
+        return self::get_version_from_classname($classname);
+    }
+
+    /**
+     * Normalise an API version from a classname.
+     *
+     * @param string $classname The short classname, omitting any namespace or file extension
+     * @return string The normalised version
+     */
+    protected static function get_version_from_classname(string $classname): string {
+        $classname = str_replace('v', '', $classname);
+        $classname = str_replace('p', '.', $classname);
+        return $classname;
+    }
+
+    /**
+     * Check if the API version is at least the specified version.
+     *
+     * @param string $minversion The minimum API version required
+     * @return bool
+     */
+    public function meets_version(string $minversion): bool {
+        $thisversion = $this->get_version();
+        return version_compare($thisversion, $minversion) >= 0;
+    }
+
+    /**
+     * Assert that the API version is at least the specified version.
+     *
+     * @param string $minversion The minimum API version required
+     * @throws Exception
+     */
+    public function requires_version(string $minversion): void {
+        if ($this->meets_version($minversion)) {
+            return;
+        }
+
+        throw new \moodle_exception("Matrix API version {$minversion} or higher is required for this command.");
+    }
+}

communication/provider/matrix/classes/matrix_constants.php

@@ -0,0 +1,51 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix;
+
+/**
+ * class matrix_constants to have one location to store all constants related to matrix.
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Safat Shahin <safat.shahin@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class matrix_constants {
+    /**
+     * User default power level for matrix.
+     */
+    public const POWER_LEVEL_DEFAULT = 0;
+
+    /**
+     * User moderator power level for matrix.
+     */
+    public const POWER_LEVEL_MODERATOR = 50;
+
+    /**
+     * User moderator power level for matrix.
+     */
+    public const POWER_LEVEL_MOODLE_MODERATOR = 51;
+
+    /**
+     * User power level for matrix associated to moodle site admins. It is a custom power level for site admins.
+     */
+    public const POWER_LEVEL_MOODLE_SITE_ADMIN = 90;
+
+    /**
+     * User maximum power level for matrix. This is only associated to the token user to allow god mode actions.
+     */
+    public const POWER_LEVEL_MAXIMUM = 100;
+}

communication/provider/matrix/classes/matrix_room.php

@@ -0,0 +1,146 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix;
+
+use stdClass;
+
+/**
+ * Class to manage the updates to the room information in db.
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Safat Shahin <safat.shahin@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class matrix_room {
+    private const TABLE = 'matrix_room';
+
+    /** @var \stdClass|null $record The matrix room record from db */
+
+    /**
+     * Load the matrix room record for the supplied processor.
+     * @param int $processorid
+     * @return null|self
+     */
+    public static function load_by_processor_id(
+        int $processorid,
+    ): ?self {
+        global $DB;
+
+        $record = $DB->get_record(self::TABLE, ['commid' => $processorid]);
+
+        if (!$record) {
+            return null;
+        }
+        return new self($record);
+    }
+
+    /**
+     * Matrix rooms constructor to load the matrix room information from matrix_room table.
+     *
+     * @param stdClass $record
+     */
+    private function __construct(
+        private stdClass $record,
+    ) {
+    }
+
+    /**
+     * Create matrix room data.
+     *
+     * @param int $processorid The id of the communication record
+     * @param string|null $topic The topic of the room for matrix
+     * @param string|null $roomid The id of the room from matrix
+     * @return self
+     */
+    public static function create_room_record(
+        int $processorid,
+        ?string $topic,
+        ?string $roomid = null,
+    ): self {
+        global $DB;
+
+        $roomrecord = (object) [
+            'commid' => $processorid,
+            'roomid' => $roomid,
+            'topic' => $topic,
+        ];
+        $roomrecord->id = $DB->insert_record(self::TABLE, $roomrecord);
+
+        return self::load_by_processor_id($processorid);
+    }
+
+    /**
+     * Update matrix room data.
+     *
+     * @param string|null $roomid The id of the room from matrix
+     * @param string|null $topic The topic of the room for matrix
+     */
+    public function update_room_record(
+        ?string $roomid = null,
+        ?string $topic = null,
+    ): void {
+        global $DB;
+
+        if ($roomid !== null) {
+            $this->record->roomid = $roomid;
+        }
+
+        if ($topic !== null) {
+            $this->record->topic = $topic;
+        }
+
+        $DB->update_record(self::TABLE, $this->record);
+    }
+
+    /**
+     * Delete matrix room data.
+     */
+    public function delete_room_record(): void {
+        global $DB;
+
+        $DB->delete_records(self::TABLE, ['commid' => $this->record->commid]);
+
+        unset($this->record);
+    }
+
+    /**
+     * Get the processor id.
+     *
+     * @return int
+     */
+    public function get_processor_id(): int {
+        return $this->record->commid;
+    }
+
+    /**
+     * Get the matrix room id.
+     *
+     * @return string|null
+     */
+    public function get_room_id(): ?string {
+        return $this->record->roomid;
+    }
+
+    /**
+     * Get the matrix room topic.
+     *
+     * @return string
+     */
+    public function get_topic(): string {
+        return $this->record->topic ?? '';
+    }
+}

communication/provider/matrix/classes/matrix_user_manager.php

@@ -0,0 +1,203 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix;
+
+/**
+ * class matrix_user_manager to handle specific actions.
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Stevani Andolo <stevani.andolo@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class matrix_user_manager {
+
+    /**
+     * Prefix for Matrix usernames when they are detected as numeric.
+     */
+    const MATRIX_USER_PREFIX = 'user';
+
+    /**
+     * Gets matrix user id from moodle.
+     *
+     * @param int $userid Moodle user id
+     * @return string|null
+     */
+    public static function get_matrixid_from_moodle(
+        int $userid,
+    ): ?string {
+        self::load_requirements();
+        $field = profile_user_record($userid);
+        $matrixprofilefield = get_config('communication_matrix', 'matrixuserid_field');
+
+        if ($matrixprofilefield === false) {
+            return null;
+        }
+
+        return $field->{$matrixprofilefield} ?? null;
+    }
+
+    /**
+     * Get a qualified matrix user id based on a Moodle username.
+     *
+     * @param string $username The moodle username to turn into a Matrix username
+     * @return string
+     */
+    public static function get_formatted_matrix_userid(
+        string $username,
+    ): string {
+        $username = preg_replace('/[@#$%^&*()+{}|<>?!,]/i', '.', $username);
+        $username = ltrim(rtrim($username, '.'), '.');
+
+        // Matrix/Synapse servers will not allow numeric usernames.
+        if (is_numeric($username)) {
+            $username = self::MATRIX_USER_PREFIX . $username;
+        }
+
+        $homeserver = self::get_formatted_matrix_home_server();
+
+        return "@{$username}:{$homeserver}";
+    }
+
+    /**
+     * Add user's Matrix user id.
+     *
+     * @param int $userid Moodle user id
+     * @param string $matrixuserid Matrix user id
+     */
+    public static function set_matrix_userid_in_moodle(
+        int $userid,
+        string $matrixuserid,
+    ): void {
+        $matrixprofilefield = self::get_profile_field_name();
+        $field = profile_get_custom_field_data_by_shortname($matrixprofilefield);
+
+        if ($field === null) {
+            return;
+        }
+        $userinfodata = (object) [
+            'id' => $userid,
+            'data' => $matrixuserid,
+            'fieldid' => $field->id,
+            "profile_field_{$matrixprofilefield}" => $matrixuserid,
+        ];
+        profile_save_data($userinfodata);
+    }
+
+    /**
+     * Sets home server for user matrix id
+     *
+     * @return string
+     */
+    public static function get_formatted_matrix_home_server(): string {
+        $homeserver = get_config('communication_matrix', 'matrixhomeserverurl');
+        if ($homeserver === false) {
+            throw new \moodle_exception('Unknown matrix homeserver url');
+        }
+
+        $homeserver = parse_url($homeserver)['host'];
+
+        if (str_starts_with($homeserver, 'www.')) {
+            $homeserver = str_replace('www.', '', $homeserver);
+        }
+
+        return $homeserver;
+    }
+
+    /**
+     * Insert "Communication" category and "matrixuserid" field.
+     *
+     * @return string
+     */
+    public static function create_matrix_user_profile_fields(): string {
+        global $CFG, $DB;
+
+        require_once($CFG->dirroot . '/user/profile/definelib.php');
+        require_once($CFG->dirroot . '/user/profile/field/text/define.class.php');
+
+        // Check if communication category exists.
+        $categoryname = get_string('communication', 'core_communication');
+        $category = $DB->count_records('user_info_category', ['name' => $categoryname]);
+
+        if ($category < 1) {
+            $data = new \stdClass();
+            $data->sortorder = $DB->count_records('user_info_category') + 1;
+            $data->name = $categoryname;
+            $data->id = $DB->insert_record('user_info_category', $data);
+
+            $createdcategory = $DB->get_record('user_info_category', ['id' => $data->id]);
+            $categoryid = $createdcategory->id;
+            \core\event\user_info_category_created::create_from_category($createdcategory)->trigger();
+        } else {
+            $category = $DB->get_record('user_info_category', ['name' => $categoryname]);
+            $categoryid = $category->id;
+        }
+
+        set_config('communication_category_field', $categoryname, 'core_communication');
+
+        // Check if matrixuserid exists in user_info_field table.
+        $matrixuserid = $DB->count_records('user_info_field', [
+            'shortname' => 'matrixuserid',
+            'categoryid' => $categoryid,
+        ]);
+
+        if ($matrixuserid < 1) {
+            $profileclass = new \profile_define_text();
+
+            $data = (object) [
+                'shortname' => 'matrixuserid',
+                'name' => get_string('matrixuserid', 'communication_matrix'),
+                'datatype' => 'text',
+                'categoryid' => $categoryid,
+                'forceunique' => 1,
+                'visible' => 0,
+                'locked' => 1,
+                'param1' => 30,
+                'param2' => 2048,
+            ];
+
+            $profileclass->define_save($data);
+            set_config('matrixuserid_field', 'matrixuserid', 'communication_matrix');
+            return 'matrixuserid';
+        }
+    }
+
+    /**
+     * Get the profile field name, creating the profiel field if it does not exist.
+     *
+     * @return string
+     */
+    protected static function get_profile_field_name(): string {
+        self::load_requirements();
+        $matrixprofilefield = get_config('communication_matrix', 'matrixuserid_field');
+        if ($matrixprofilefield === false) {
+            $matrixprofilefield = self::create_matrix_user_profile_fields();
+        }
+
+        return $matrixprofilefield;
+    }
+
+    /**
+     * Load requirements for profile field management.
+     *
+     * This is just a helper to keep loading legacy files isolated.
+     */
+    protected static function load_requirements(): void {
+        global $CFG;
+
+        require_once("{$CFG->dirroot}/user/profile/lib.php");
+    }
+}

communication/provider/matrix/classes/privacy/provider.php

@@ -0,0 +1,39 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix\privacy;
+
+use core_privacy\local\metadata\null_provider;
+
+/**
+ * Privacy Subsystem for communication_matrix implementing null_provider.
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Safat Shahin <safat.shahin@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @codeCoverageIgnore
+ */
+class provider implements null_provider {
+    /**
+     * Get the language string identifier with the component's language
+     * file to explain why this plugin stores no data.
+     *
+     * @return  string
+     */
+    public static function get_reason(): string {
+        return 'privacy:metadata';
+    }
+}

communication/provider/matrix/db/access.php

@@ -0,0 +1,39 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * Capability definitions for matrix communication.
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Safat Shahin <safat.shahin@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+defined('MOODLE_INTERNAL') || die();
+
+$capabilities = [
+
+    // Matrix moderator capability which aligns with the matrix moderator role or power level 50.
+    'communication/matrix:moderator' => [
+        'captype' => 'read',
+        'contextlevel' => CONTEXT_COURSE,
+        'archetypes' => [
+            'editingteacher' => CAP_ALLOW,
+            'manager' => CAP_ALLOW,
+            'teacher' => CAP_ALLOW,
+        ],
+    ],
+];

communication/provider/matrix/db/caches.php

@@ -0,0 +1,42 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * Cache definition for the Matrix Communication plugin.
+ *
+ * @package    communication_matrix
+ * @category   cache
+ * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+defined('MOODLE_INTERNAL') || die();
+
+$definitions = [
+    // Used to store processed lang files.
+    // The keys used are the revision, lang and component of the string file.
+    // The static acceleration size has been based upon student access of the site.
+    'serverversions' => [
+        'mode' => cache_store::MODE_APPLICATION,
+        'simplekeys' => true,
+        'simpledata' => true,
+        'staticacceleration' => true,
+        'staticaccelerationsize' => 1,
+        'canuselocalstore' => true,
+        // Cache for one day.
+        'ttl' => 60 * 60 * 24,
+    ],
+];

communication/provider/matrix/db/install.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<XMLDB PATH="communication/provider/matrix/db" VERSION="20230719" COMMENT="Stores the matrix room information associated with the communication instance."
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="../../../../lib/xmldb/xmldb.xsd"
+>
+  <TABLES>
+    <TABLE NAME="matrix_room" COMMENT="Stores the matrix room information associated with the communication instance.">
+      <FIELDS>
+        <FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="true"/>
+        <FIELD NAME="commid" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" COMMENT="ID of the communication record"/>
+        <FIELD NAME="roomid" TYPE="char" LENGTH="255" NOTNULL="false" SEQUENCE="false" COMMENT="ID of the matrix room instance"/>
+        <FIELD NAME="topic" TYPE="char" LENGTH="255" NOTNULL="false" SEQUENCE="false" COMMENT="Topic of the matrix room instance."/>
+      </FIELDS>
+      <KEYS>
+        <KEY NAME="primary" TYPE="primary" FIELDS="id"/>
+        <KEY NAME="fk_commid" TYPE="foreign" FIELDS="commid" REFTABLE="communication" REFFIELDS="id" COMMENT="Foreign key for communication reference"/>
+      </KEYS>
+    </TABLE>
+  </TABLES>
+</XMLDB>

communication/provider/matrix/db/upgrade.php

@@ -0,0 +1,61 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * Install steps for communication_matrix.
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Safat Shahin <safat.shahin@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Upgrade procedures for the matrix plugin.
+ *
+ * @return bool
+ */
+function xmldb_communication_matrix_upgrade($oldversion) {
+    global $DB;
+
+    $dbman = $DB->get_manager();
+    if ($oldversion < 2023060101) {
+        $table = new xmldb_table('matrix_rooms');
+        $field = new xmldb_field('topic', XMLDB_TYPE_CHAR, '255', null, false, false, null, 'roomid');
+
+        if (!$dbman->field_exists($table, $field)) {
+            $dbman->add_field($table, $field);
+        }
+
+        // Plugin savepoint reached.
+        upgrade_plugin_savepoint(true, 2023060101, 'communication', 'matrix');
+    }
+
+    if ($oldversion < 2023071900) {
+        $table = new xmldb_table('matrix_rooms');
+        $dbman->rename_table($table, 'matrix_room');
+
+        // Plugin savepoint reached.
+        upgrade_plugin_savepoint(true, 2023071900, 'communication', 'matrix');
+    }
+
+    // Automatically generated Moodle v4.3.0 release upgrade line.
+    // Put any upgrade step following this.
+
+    // Automatically generated Moodle v4.4.0 release upgrade line.
+    // Put any upgrade step following this.
+
+    return true;
+}

communication/provider/matrix/lang/en/communication_matrix.php

@@ -0,0 +1,40 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * Strings for component communication_matrix, language 'en'.
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Safat Shahin <safat.shahin@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+$string['cachedef_serverversions'] = 'Matrix server version information for running servers';
+$string['matrixuserid'] = 'Matrix user ID';
+$string['matrixhomeserverurl'] = 'Homeserver URL';
+$string['matrixhomeserverurl_desc'] = 'The URL of the Synapse homeserver to connect to, for user and room creation.';
+$string['matrixaccesstoken'] = 'Access token';
+$string['matrixaccesstoken_desc'] = 'Access token for the account which will perform actions on the homeserver.';
+$string['matrixelementurl'] = 'Element web URL';
+$string['matrixroomtopic'] = 'Room topic';
+$string['matrixroomtopic_help'] = 'A short description of what this room is for.';
+$string['matrix:moderator'] = 'Matrix moderator';
+$string['pluginname'] = 'Matrix';
+$string['privacy:metadata'] = 'The Matrix communication plugin does not store any personal data.';
+
+// Deprecated since Moodle 4.4.
+$string['matrixrefreshtoken'] = 'Refresh token';
+$string['matrixrefreshtoken_desc'] = 'Admin refresh token to be associated with the access token.';

communication/provider/matrix/lang/en/deprecated.txt

@@ -0,0 +1,2 @@
+matrixrefreshtoken,communication_matrix
+matrixrefreshtoken_desc,communication_matrix

communication/provider/matrix/settings.php

@@ -0,0 +1,41 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * Matrix communication plugin settings.
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Safat Shahin <safat.shahin@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+defined('MOODLE_INTERNAL') || die;
+
+if ($hassiteconfig) {
+    // Home server URL.
+    $name = new lang_string('matrixhomeserverurl', 'communication_matrix');
+    $desc = new lang_string('matrixhomeserverurl_desc', 'communication_matrix');
+    $settings->add(new admin_setting_configtext('communication_matrix/matrixhomeserverurl', $name, $desc, ''));
+
+    // Access token.
+    $name = new lang_string('matrixaccesstoken', 'communication_matrix');
+    $desc = new lang_string('matrixaccesstoken_desc', 'communication_matrix');
+    $settings->add(new admin_setting_configpasswordunmask('communication_matrix/matrixaccesstoken', $name, $desc, ''));
+
+    // Element web URL.
+    $name = new lang_string('matrixelementurl', 'communication_matrix');
+    $settings->add(new admin_setting_configtext('communication_matrix/matrixelementurl', $name, '', ''));
+}

communication/provider/matrix/tests/behat/behat_communication_matrix.php

@@ -0,0 +1,66 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+// phpcs:disable PSR1.Classes.ClassDeclaration.MissingNamespace
+
+use Behat\Behat\Hook\Scope\BeforeScenarioScope;
+use communication_matrix\matrix_test_helper_trait;
+use Moodle\BehatExtension\Exception\SkippedException;
+
+require_once(__DIR__ . '/../matrix_test_helper_trait.php');
+require_once(__DIR__ . '/../../../../../lib/behat/behat_base.php');
+require_once(__DIR__ . '/../../../../tests/communication_test_helper_trait.php');
+
+/**
+ * Class behat_communication_matrix for behat custom steps and configuration for matrix.
+ *
+ * @package    communication_matrix
+ * @category   test
+ * @copyright  2023 Safat Shahin <safat.shahin@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class behat_communication_matrix extends \behat_base {
+    use \core_communication\communication_test_helper_trait;
+    use matrix_test_helper_trait;
+
+    /**
+     * BeforeScenario hook to reset the mock server.
+     *
+     * @BeforeScenario @communication_matrix
+     *
+     * @param BeforeScenarioScope $scope
+     */
+    public function before_scenario(BeforeScenarioScope $scope) {
+        if (defined('TEST_COMMUNICATION_MATRIX_MOCK_SERVER')) {
+            $this->reset_mock();
+        }
+    }
+
+    /**
+     * Setup and configure and mock server for matrix.
+     *
+     * @Given /^a Matrix mock server is configured$/
+     */
+    public function initialize_mock_server(): void {
+        if (!defined('TEST_COMMUNICATION_MATRIX_MOCK_SERVER')) {
+            throw new SkippedException(
+                'The TEST_COMMUNICATION_MATRIX_MOCK_SERVER constant must be defined to run communication_matrix tests'
+            );
+        }
+        $this->setup_communication_configs();
+        $this->initialise_mock_configs();
+    }
+}

communication/provider/matrix/tests/behat/matrix_form_fields.feature

@@ -0,0 +1,34 @@
+@communication @communication_matrix
+Feature: Communication matrix form field
+  In order to create a new communication room in matrix
+  As a teacher
+  I can update the room the information from course
+
+  Background: Make sure the mock server is initialized and a course is created for teacher
+    Given the following "users" exist:
+      | username | firstname | lastname | email |
+      | teacher1 | Teacher | 1 | teacher1@example.com |
+    And the following "courses" exist:
+      | fullname    | shortname   | category |
+      | Test course | Test course | 0        |
+    And the following "course enrolments" exist:
+      | user     | course      | role    |
+      | teacher1 | Test course | editingteacher |
+
+  @javascript
+  Scenario: I can add room name and topic for matrix room
+    Given a Matrix mock server is configured
+    And I am on the "Test course" "Course" page logged in as "teacher1"
+    When I navigate to "Communication" in current page administration
+    And I set the following fields to these values:
+      | selectedcommunication | communication_matrix |
+    And I wait to be redirected
+    And I set the following fields to these values:
+      | communication_matrixroomname | Sampleroomname  |
+      | matrixroomtopic              | Sampleroomtopic |
+    And I should see "Room name"
+    And I should see "Room topic"
+    And I press "Save changes"
+    And I navigate to "Communication" in current page administration
+    Then the field "Room name" matches value "Sampleroomname"
+    And the field "Room topic" matches value "Sampleroomtopic"

communication/provider/matrix/tests/behat/matrix_room_banner.feature

@@ -0,0 +1,52 @@
+@communication @communication_matrix
+Feature: Display communication room status banner
+  Show a banner depending on the room status
+  As a teacher or admin
+
+  Background:
+    Given a Matrix mock server is configured
+    And the following "users" exist:
+      | username | firstname | lastname | email                |
+      | teacher1 | Teacher   | 1        | teacher1@example.com |
+      | student1 | Student   | 1        | student1@example.com |
+    And the following "courses" exist:
+      | fullname    | shortname   | category | selectedcommunication | communicationroomname |
+      | Test course | Test course | 0        | communication_matrix  | matrixroom            |
+    And the following "course enrolments" exist:
+      | user     | course      | role           |
+      | teacher1 | Test course | editingteacher |
+      | student1 | Test course | student        |
+
+  Scenario: I can see the room has been created and in a pending status
+    When I am on the "Test course" "Course" page logged in as "teacher1"
+    Then I should see "Your Matrix room will be ready soon." in the "page-content" "region"
+    When I am on the "Test course" "Course" page logged in as "student1"
+    # Not for students to see.
+    Then I should not see "Your Matrix room will be ready soon." in the "page-content" "region"
+
+  Scenario: I can see the room has been created and ready to access
+    When I run all adhoc tasks
+    And I am on the "Test course" "Course" page logged in as "teacher1"
+    Then I should see "Your Matrix room is ready." in the "page-content" "region"
+    # This is a one time message per user.
+    When I reload the page
+    Then I should not see "Your Matrix room is ready." in the "page-content" "region"
+    # Not for students to see.
+    When I am on the "Test course" "Course" page logged in as "student1"
+    Then I should not see "Your Matrix room is ready." in the "page-content" "region"
+
+  Scenario: Enabling or disabling the matrix plugin hides the banner accordingly
+    Given I am on the "Test course" "Course" page logged in as "teacher1"
+    Then I should see "Your Matrix room will be ready soon." in the "page-content" "region"
+    When I log in as "admin"
+    And I navigate to "Plugins > Communication > Manage communication providers" in site administration
+    And I should see "Matrix"
+    And I click on "Disable" "link" in the "Matrix" "table_row"
+    And I am on the "Test course" "Course" page logged in as "teacher1"
+    And I should not see "Your Matrix room will be ready soon." in the "page-content" "region"
+    And I log in as "admin"
+    And I navigate to "Plugins > Communication > Manage communication providers" in site administration
+    And I should see "Matrix"
+    And I click on "Enable" "link" in the "Matrix" "table_row"
+    And I am on the "Test course" "Course" page logged in as "teacher1"
+    Then I should see "Your Matrix room will be ready soon." in the "page-content" "region"

communication/provider/matrix/tests/communication_feature_test.php

@@ -0,0 +1,571 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix;
+
+use core\context;
+use core_communication\api;
+use core_communication\communication_test_helper_trait;
+use core_communication\processor;
+use stored_file;
+
+defined('MOODLE_INTERNAL') || die();
+
+require_once(__DIR__ . '/matrix_test_helper_trait.php');
+require_once(__DIR__ . '/../../../tests/communication_test_helper_trait.php');
+
+/**
+ * Class communication_feature_test to test the matrix features implemented using the core interfaces.
+ *
+ * @package    communication_matrix
+ * @category   test
+ * @copyright  2023 Safat Shahin <safat.shahin@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @covers \communication_matrix\communication_feature
+ * @coversDefaultClass \communication_matrix\communication_feature
+ */
+class communication_feature_test extends \advanced_testcase {
+    use matrix_test_helper_trait;
+    use communication_test_helper_trait;
+
+    public function setUp(): void {
+        parent::setUp();
+        $this->resetAfterTest();
+        $this->setup_communication_configs();
+        $this->initialise_mock_server();
+    }
+
+    /**
+     * Test create or update chat room.
+     *
+     * @covers ::create_chat_room
+     */
+    public function test_create_chat_room(): void {
+        // Set up the test data first.
+        $communication = \core_communication\api::load_by_instance(
+            context: \core\context\system::instance(),
+            component: 'communication_matrix',
+            instancetype: 'example',
+            instanceid: 1,
+            provider: 'communication_matrix',
+        );
+
+        $communication->create_and_configure_room(
+            communicationroomname: 'Room name',
+            instance: (object) [
+                'matrixroomtopic' => 'A fun topic',
+            ],
+        );
+
+        // phpcs:ignore moodle.Commenting.InlineComment.DocBlock
+        /** @var communication_feature */
+        $provider = $communication->get_room_provider();
+        $this->assertInstanceOf(
+            communication_feature::class,
+            $provider,
+        );
+
+        // Run the create_chat_room task.
+        $result = $provider->create_chat_room();
+        $this->assertTrue($result);
+
+        // Ensure that a room_id was set.
+        $this->assertNotEmpty($provider->get_room_id());
+
+        // Fetch the back office room data.
+        $remoteroom = $this->backoffice_get_room();
+
+        // The roomid set in the database must match the one set on the remote server.
+        $this->assertEquals(
+            $remoteroom->room_id,
+            $provider->get_room_id(),
+        );
+
+        // The name is a feature of the communication API itself.
+        $this->assertEquals(
+            'Room name',
+            $communication->get_room_name(),
+        );
+        $this->assertEquals(
+            $communication->get_room_name(),
+            $remoteroom->name,
+        );
+
+        // The topic is a Matrix feature.
+        $roomconfig = $provider->get_room_configuration();
+        $this->assertEquals(
+            'A fun topic',
+            $roomconfig->get_topic(),
+        );
+        $this->assertEquals(
+            $remoteroom->topic,
+            $roomconfig->get_topic(),
+        );
+
+        // The avatar features are checked in a separate test.
+    }
+
+    /**
+     * Test update of a chat room.
+     *
+     * @covers ::update_chat_room
+     */
+    public function test_update_chat_room(): void {
+        $communication = $this->create_room(
+            roomname: 'Our room name',
+            roomtopic: 'Our room topic',
+        );
+
+        // phpcs:ignore moodle.Commenting.InlineComment.DocBlock
+        /** @var communication_feature */
+        $provider = $communication->get_room_provider();
+        $this->assertInstanceOf(
+            communication_feature::class,
+            $provider,
+        );
+
+        // Update the room name.
+        // Note: We have to update the record via the API, and then call the provider update method.
+        // That's because the update is performed asynchronously.
+        $communication->update_room(
+            communicationroomname: 'Our updated room name',
+        );
+        $provider->reload();
+
+        // Now call the provider's update method.
+        $provider->update_chat_room();
+
+        // And assert that it was updated remotely.
+        $remoteroom = $this->backoffice_get_room();
+
+        $this->assertEquals(
+            'Our updated room name',
+            $communication->get_room_name(),
+        );
+        $this->assertEquals(
+            $communication->get_room_name(),
+            $remoteroom->name,
+        );
+        // The remote topic should not have changed.
+        $this->assertEquals(
+            'Our room topic',
+            $remoteroom->topic,
+        );
+
+        // Now update just the topic.
+        // First in the local API.
+        $communication->update_room(
+            instance: (object) [
+                'matrixroomtopic' => 'Our updated room topic',
+            ],
+        );
+
+        $provider->reload();
+
+        // Then call the provider's update method to actually perform the change.
+        $provider->update_chat_room();
+
+        // And assert that it was updated remotely.
+        $remoteroom = $this->backoffice_get_room();
+
+        $this->assertEquals(
+            'Our updated room topic',
+            $provider->get_room_configuration()->get_topic(),
+        );
+
+        // The remote topic should have been updated.
+        $this->assertEquals(
+            'Our updated room topic',
+            $remoteroom->topic,
+        );
+
+        // The name should not have changed.
+        $this->assertEquals(
+            'Our updated room name',
+            $communication->get_room_name(),
+        );
+    }
+
+    /**
+     * Test delete chat room.
+     *
+     * @covers ::delete_chat_room
+     */
+    public function test_delete_chat_room(): void {
+        $communication = $this->create_room();
+
+        $processor = $communication->get_processor();
+        $provider = $communication->get_room_provider();
+        $room = matrix_room::load_by_processor_id($processor->get_id());
+
+        // Run the delete method.
+        $this->assertTrue($provider->delete_chat_room());
+
+        // The record of the room should have been removed.
+        $this->assertNull(matrix_room::load_by_processor_id($processor->get_id()));
+
+        // But the room itself shoudl exist.
+        $matrixroomdata = $this->get_matrix_room_data($room->get_room_id());
+
+        $this->assertNotEmpty($matrixroomdata);
+        $this->assertEquals($processor->get_room_name(), $matrixroomdata->name);
+        $this->assertEquals($room->get_topic(), $matrixroomdata->topic);
+    }
+
+    /**
+     * Test update room avatar.
+     *
+     * @covers ::update_room_avatar
+     * @dataProvider avatar_provider
+     */
+    public function test_update_room_avatar(
+        ?string $before,
+        ?string $after,
+    ): void {
+        $this->setAdminUser();
+
+        // Create a new draft file.
+        $logo = $this->create_communication_file('moodle_logo.jpg', 'logo.jpg');
+        $circle = $this->create_communication_file('circle.png', 'circle.png');
+
+        if ($before === 'logo') {
+            $before = $logo;
+        } else if ($before === 'circle') {
+            $before = $circle;
+        }
+
+        if ($after === 'logo') {
+            $after = $logo;
+        } else if ($after === 'circle') {
+            $after = $circle;
+        }
+
+        $communication = $this->create_matrix_room(
+            component: 'communication_matrix',
+            itemtype: 'example_room',
+            itemid: 1,
+            roomname: 'Example room name',
+            roomavatar: $before,
+        );
+
+        // Confirm that the avatar was set remotely.
+        $remoteroom = $this->backoffice_get_room();
+
+        if ($before) {
+            $this->assertStringEndsWith($before->get_filename(), $remoteroom->avatar);
+            $avatarcontent = download_file_content($remoteroom->avatar);
+            $this->assertEquals($before->get_content(), $avatarcontent);
+        } else {
+            $this->assertEmpty($remoteroom->avatar);
+        }
+
+        // Reload the API instance as the information stored has changed.
+        $communication->reload();
+
+        // Update the avatar with the 'after' avatar.
+        $communication->update_room(
+            avatar: $after,
+        );
+        $this->run_all_adhoc_tasks();
+
+        // Confirm that the avatar was updated remotely.
+        $remoteroom = $this->backoffice_get_room();
+
+        if ($after) {
+            $this->assertStringEndsWith($after->get_filename(), $remoteroom->avatar);
+            $avatarcontent = download_file_content($remoteroom->avatar);
+            $this->assertEquals($after->get_content(), $avatarcontent);
+        } else {
+            $this->assertEmpty($remoteroom->avatar);
+        }
+    }
+
+    /**
+     * Tests for setting and updating the room avatar.
+     *
+     * @return array
+     */
+    public static function avatar_provider(): array {
+        return [
+            'Empty to avatar' => [
+                null,
+                'circle',
+            ],
+            'Avatar to empty' => [
+                'circle',
+                null,
+            ],
+            'Avatar to new avatar' => [
+                'circle',
+                'logo',
+            ],
+        ];
+    }
+
+    /**
+     * Test get chat room url.
+     *
+     * @covers ::get_chat_room_url
+     */
+    public function test_get_chat_room_url(): void {
+        $communication = $this->create_room();
+
+        $provider = $communication->get_room_provider();
+
+        $url = $provider->get_chat_room_url();
+        $this->assertNotNull($url);
+
+        // Fetch the room information from the server.
+        $remoteroom = $this->backoffice_get_room();
+
+        $this->assertStringEndsWith(
+            $remoteroom->room_id,
+            $url,
+        );
+    }
+
+    /**
+     * Test create members.
+     *
+     * @covers ::create_members
+     * @covers ::add_registered_matrix_user_to_room
+     */
+    public function test_create_members(): void {
+        $user = $this->getDataGenerator()->create_user();
+
+        $communication = $this->create_room(
+            members: [
+                $user->id,
+            ],
+        );
+
+        $remoteroom = $this->backoffice_get_room();
+        $this->assertCount(1, $remoteroom->members);
+        $member = reset($remoteroom->members);
+        $this->assertStringStartsWith("@{$user->username}", $member->userid);
+    }
+
+    /**
+     * Test add/remove members from room.
+     *
+     * @covers ::remove_members_from_room
+     * @covers ::add_members_to_room
+     * @covers ::add_registered_matrix_user_to_room
+     * @covers ::check_room_membership
+     * @covers ::set_matrix_power_levels
+     */
+    public function test_add_and_remove_members_from_room(): void {
+        $user = $this->getDataGenerator()->create_user();
+        $user2 = $this->getDataGenerator()->create_user();
+
+        $communication = $this->create_room();
+        $provider = $communication->get_room_user_provider();
+
+        $remoteroom = $this->backoffice_get_room();
+        $this->assertCount(0, $remoteroom->members);
+
+        // Add the members to the room.
+        $provider->add_members_to_room([$user->id, $user2->id]);
+
+        // Ensure that they have been created.
+        $remoteroom = $this->backoffice_get_room();
+        $this->assertCount(2, $remoteroom->members);
+
+        $userids = array_map(fn($member) => $member->userid, $remoteroom->members);
+        $userids = array_map(fn($userid) => substr($userid, 0, strpos($userid, ':')), $userids);
+        $this->assertContains("@{$user->username}", $userids);
+        $this->assertContains("@{$user2->username}", $userids);
+
+        // Remove member from matrix room.
+        $provider->remove_members_from_room([$user->id]);
+
+        // Ensure that they have been removed.
+        $remoteroom = $this->backoffice_get_room();
+        $members = (array) $remoteroom->members;
+        $this->assertCount(1, $members);
+        $userids = array_map(fn ($member) => $member->userid, $members);
+        $userids = array_map(fn ($userid) => substr($userid, 0, strpos($userid, ':')), $userids);
+        $this->assertNotContains("@{$user->username}", $userids);
+        $this->assertContains("@{$user2->username}", $userids);
+    }
+
+    /**
+     * Test update of room membership.
+     *
+     * @covers ::update_room_membership
+     * @covers ::set_matrix_power_levels
+     * @covers ::is_power_levels_update_required
+     * @covers ::get_user_allowed_power_level
+     */
+    public function test_update_room_membership(): void {
+        $this->resetAfterTest();
+
+        global $DB;
+
+        // Create a new room.
+        $course = $this->get_course('Sampleroom', 'none');
+        $coursecontext = \context_course::instance($course->id);
+        $user = $this->get_user();
+
+        $communication = $this->create_room(
+            component: 'core_course',
+            itemtype: 'coursecommunication',
+            itemid: $course->id,
+            roomname: 'sampleroom',
+            roomtopic: 'sampltopic',
+            roomavatar: null,
+            members: [$user->id],
+            context: $coursecontext,
+        );
+
+        $provider = $communication->get_room_user_provider();
+
+        // Add the members to the room.
+        $provider->add_members_to_room([$user->id]);
+
+        // Assign teacher role to the user.
+        $teacherrole = $DB->get_record('role', ['shortname' => 'teacher']);
+        $this->getDataGenerator()->enrol_user($user->id, $course->id);
+        role_assign($teacherrole->id, $user->id, $coursecontext->id);
+
+        // Test the tasks added as the role is a teacher.
+        $provider->update_room_membership([$user->id]);
+
+        $processor = \core_communication\processor::load_by_instance(
+            context: $coursecontext,
+            component: 'core_course',
+            instancetype: 'coursecommunication',
+            instanceid: $course->id,
+        );
+        $synceduser = $processor->get_instance_userids(
+            synced: true,
+        );
+        $synceduser = reset($synceduser);
+
+        // Test if the communication user record is synced.
+        $this->assertEquals($user->id, $synceduser);
+    }
+
+    /**
+     * Test the user power level allocation according to context.
+     *
+     * @covers ::get_user_allowed_power_level
+     */
+    public function test_get_user_allowed_power_level(): void {
+        $this->resetAfterTest();
+        global $DB;
+
+        // Create users.
+        $user1 = $this->getDataGenerator()->create_user();
+        $user2 = $this->getDataGenerator()->create_user();
+
+        $course = $this->get_course();
+        $coursecontext = \context_course::instance($course->id);
+        $teacherrole = $DB->get_record('role', ['shortname' => 'editingteacher']);
+        $studentrole = $DB->get_record('role', ['shortname' => 'student']);
+        $this->getDataGenerator()->enrol_user($user1->id, $course->id);
+        $this->getDataGenerator()->enrol_user($user2->id, $course->id);
+        // Assign roles.
+        role_assign($teacherrole->id, $user1->id, $coursecontext->id);
+        role_assign($studentrole->id, $user2->id, $coursecontext->id);
+
+        $communicationprocessor = processor::load_by_instance(
+            context: \core\context\course::instance($course->id),
+            component: 'core_course',
+            instancetype: 'coursecommunication',
+            instanceid: $course->id
+        );
+
+        // Test if the power level is set according to the context.
+        $this->assertEquals(
+            matrix_constants::POWER_LEVEL_MOODLE_MODERATOR,
+            $communicationprocessor->get_room_provider()->get_user_allowed_power_level($user1->id)
+        );
+        $this->assertEquals(
+            matrix_constants::POWER_LEVEL_DEFAULT,
+            $communicationprocessor->get_room_provider()->get_user_allowed_power_level($user2->id)
+        );
+    }
+
+    /**
+     * Helper to create a room.
+     *
+     * @param null|string $component
+     * @param null|string $itemtype
+     * @param null|int $itemid
+     * @param null|string $roomname
+     * @param null|string $roomtopic
+     * @param null|stored_file $roomavatar
+     * @param array $members
+     * @return api
+     */
+    protected function create_room(
+        ?string $component = 'communication_matrix',
+        ?string $itemtype = 'example',
+        ?int $itemid = 1,
+        ?string $roomname = null,
+        ?string $roomtopic = null,
+        ?\stored_file $roomavatar = null,
+        array $members = [],
+        ?context $context = null,
+    ): \core_communication\api {
+        // Create a new room.
+        $communication = \core_communication\api::load_by_instance(
+            context: $context ?? \core\context\system::instance(),
+            component: $component,
+            instancetype: $itemtype,
+            instanceid: $itemid,
+            provider: 'communication_matrix',
+        );
+
+        $communication->create_and_configure_room(
+            communicationroomname: $roomname ?? 'Room name',
+            avatar: $roomavatar,
+            instance: (object) [
+                'matrixroomtopic' => $roomtopic ?? 'A fun topic',
+            ],
+        );
+
+        $communication->add_members_to_room($members);
+
+        // Run the adhoc task.
+        $this->run_all_adhoc_tasks();
+
+        $communication->reload();
+        return $communication;
+    }
+
+    /**
+     * Test if the selected provider is configured.
+     *
+     * @covers ::is_configured
+     */
+    public function test_is_configured(): void {
+        $course = $this->get_course();
+        $communicationprocessor = processor::load_by_instance(
+            context: \core\context\course::instance($course->id),
+            component: 'core_course',
+            instancetype: 'coursecommunication',
+            instanceid: $course->id
+        );
+        $this->assertTrue($communicationprocessor->get_room_provider()->is_configured());
+
+        // Unset communication_matrix settings.
+        unset_config('matrixhomeserverurl', 'communication_matrix');
+        unset_config('matrixaccesstoken', 'communication_matrix');
+        $this->assertFalse($communicationprocessor->get_room_provider()->is_configured());
+    }
+}

communication/provider/matrix/tests/fixtures/mocked_matrix_client.php

@@ -0,0 +1,52 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix\tests\fixtures;
+
+use core\http_client;
+
+/**
+ * Tests for the api_base class.
+ *
+ * @package    communication_matrix
+ * @category   test
+ * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class mocked_matrix_client extends \communication_matrix\matrix_client {
+    /**
+     * Public variant of the constructor.
+     */
+    public function __construct() {
+        parent::__construct(...func_get_args());
+    }
+
+    /**
+     * Reset the test client.
+     */
+    public static function reset_client(): void {
+        self::$client = null;
+    }
+
+    /**
+     * Set the http_client to the client specified.
+     *
+     * @param http_client $client
+     */
+    public static function set_client(http_client $client): void {
+        self::$client = $client;
+    }
+}

communication/provider/matrix/tests/local/command_test.php

@@ -0,0 +1,411 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix\local;
+
+use GuzzleHttp\Handler\MockHandler;
+use GuzzleHttp\Psr7\Request;
+use GuzzleHttp\Psr7\Response;
+use ReflectionMethod;
+
+defined('MOODLE_INTERNAL') || die();
+require_once(dirname(__DIR__) . '/matrix_client_test_trait.php');
+
+/**
+ * Tests for the Matrix command class.
+ *
+ * @package    communication_matrix
+ * @category   test
+ * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @covers \communication_matrix\local\command
+ * @coversDefaultClass \communication_matrix\local\command
+ */
+class command_test extends \advanced_testcase {
+    use \communication_matrix\matrix_client_test_trait;
+
+    /**
+     * Test instantiation of a command when no method is provided.
+     */
+    public function test_standard_instantiation(): void {
+        $instance = $this->get_mocked_instance_for_version('v1.7');
+        $command = new command(
+            $instance,
+            method: 'PUT',
+            endpoint: 'example/endpoint',
+        );
+
+        // Check the standard functionality.
+        $this->assertEquals('/example/endpoint', $command->getUri()->getPath());
+        $this->assertEquals('PUT', $command->getMethod());
+        $this->assertArrayHasKey('Authorization', $command->getHeaders());
+    }
+
+    /**
+     * Test instantiation of a command when no method is provided.
+     */
+    public function test_instantiation_without_auth(): void {
+        $instance = $this->get_mocked_instance_for_version('v1.7');
+        $command = new command(
+            $instance,
+            method: 'PUT',
+            endpoint: 'example/endpoint',
+            requireauthorization: false,
+        );
+
+        // Check the standard functionality.
+        $this->assertEquals('/example/endpoint', $command->getUri()->getPath());
+        $this->assertEquals('PUT', $command->getMethod());
+        $this->assertArrayNotHasKey('Authorization', $command->getHeaders());
+    }
+
+    /**
+     * Test processing of command URL properties.
+     *
+     * @dataProvider url_parsing_provider
+     * @param string $url
+     * @param array $params
+     * @param string $expected
+     */
+    public function test_url_parsing(
+        string $url,
+        array $params,
+        string $expected,
+    ): void {
+        $instance = $this->get_mocked_instance_for_version('v1.7');
+
+        $command = new command(
+            $instance,
+            method: 'PUT',
+            endpoint: $url,
+            params: $params,
+        );
+
+        $this->assertEquals($expected, $command->getUri()->getPath());
+    }
+
+    /**
+     * Data provider for url parsing tests.
+     *
+     * @return array
+     */
+    public static function url_parsing_provider(): array {
+        return [
+            [
+                'example/:id/endpoint',
+                [':id' => '39492'],
+                '/example/39492/endpoint',
+            ],
+            [
+                'example/:id/endpoint/:id',
+                [':id' => '39492'],
+                '/example/39492/endpoint/39492',
+            ],
+            [
+                'example/:id/endpoint/:id/:name',
+                [
+                    ':id' => '39492',
+                    ':name' => 'matrix',
+                ],
+                '/example/39492/endpoint/39492/matrix',
+            ],
+        ];
+    }
+
+    /**
+     * Test processing of command URL properties with an array which contains untranslated parameters.
+     */
+    public function test_url_parsing_extra_properties(): void {
+        $instance = $this->get_mocked_instance_for_version('v1.7');
+        $this->expectException(\OutOfRangeException::class);
+        $this->expectExceptionMessage("URL contains untranslated parameters 'example/:id/endpoint'");
+
+        new command(
+            $instance,
+            method: 'PUT',
+            endpoint: 'example/:id/endpoint',
+        );
+    }
+
+    /**
+     * Test processing of command URL properties with an array which contains untranslated parameters.
+     */
+    public function test_url_parsing_unused_properites(): void {
+        $instance = $this->get_mocked_instance_for_version('v1.7');
+        $this->expectException(\OutOfRangeException::class);
+        $this->expectExceptionMessage("Parameter not found in URL ':id'");
+
+        new command(
+            $instance,
+            method: 'PUT',
+            endpoint: 'example/:ids/endpoint',
+            params: [
+                ':id' => 12345,
+            ],
+        );
+    }
+
+    /**
+     * Test the parameter fetching, processing, and parsing.
+     *
+     * @dataProvider parameter_and_option_provider
+     * @param string $endpoint
+     * @param array $params
+     * @param array $remainingparams
+     * @param array $allparams
+     * @param array $options
+     */
+    public function test_parameters(
+        string $endpoint,
+        array $params,
+        array $remainingparams,
+        array $allparams,
+        array $options,
+    ): void {
+        $instance = $this->get_mocked_instance_for_version('v1.7');
+
+        $command = new command(
+            $instance,
+            method: 'PUT',
+            endpoint: $endpoint,
+            params: $params,
+        );
+
+        $this->assertSame($remainingparams, $command->get_remaining_params());
+        $this->assertSame($allparams, $command->get_all_params());
+        $this->assertSame($options, $command->get_options());
+    }
+
+    /**
+     * Data provider for parameter tests.
+     *
+     * @return array
+     */
+    public static function parameter_and_option_provider(): array {
+        $command = [
+            'method' => 'PUT',
+            'endpoint' => 'example/:id/endpoint',
+        ];
+
+        return [
+            'no parameters' => [
+                'endpoint' => 'example/endpoint',
+                'params' => [],
+                'remainingparams' => [],
+                'allparams' => [],
+                'options' => [
+                    'json' => [],
+                ],
+            ],
+            'named params' => [
+                'endpoint' => 'example/:id/endpoint',
+                'params' => [
+                    ':id' => 12345,
+                ],
+                'remainingparams' => [],
+                'allparams' => [
+                    ':id' => 12345,
+                ],
+                'options' => [
+                    'json' => [],
+                ],
+            ],
+            'mixture of params' => [
+                'endpoint' => 'example/:id/endpoint',
+                'params' => [
+                    ':id' => 12345,
+                    'name' => 'matrix',
+                ],
+                'remainingparams' => [
+                    'name' => 'matrix',
+                ],
+                'allparams' => [
+                    ':id' => 12345,
+                    'name' => 'matrix',
+                ],
+                'options' => [
+                    'json' => [
+                        'name' => 'matrix',
+                    ],
+                ],
+            ],
+        ];
+    }
+
+    /**
+     * Test the query parameter handling.
+     *
+     * @dataProvider query_provider
+     * @param array $query
+     * @param string $expected
+     */
+    public function test_query_parameters(
+        array $query,
+        string $expected,
+    ): void {
+        // The query parameter is only added at the time we call send.
+        // That's because it can only be provided to Guzzle as an Option, not as part of the URL.
+        // Options can only be applied at time of transfer.
+        // Unfortuantely that leads to slightly less ideal testing that we'd like here.
+        $mock = new MockHandler();
+        $instance = $this->get_mocked_instance_for_version(
+            'v1.7',
+            mock: $mock,
+        );
+
+        $mock->append(function (Request $request) use ($expected): Response {
+            $this->assertSame(
+                $expected,
+                $request->getUri()->getQuery(),
+            );
+            return new Response();
+        });
+        $command = new command(
+            $instance,
+            method: 'PUT',
+            endpoint: 'example/endpoint',
+            query: $query,
+        );
+
+        $execute = new ReflectionMethod($instance, 'execute');
+        $execute->invoke($instance, $command);
+    }
+
+    /**
+     * Data provider for query parameter tests.
+     * @return array
+     */
+    public static function query_provider(): array {
+        return [
+            'no query' => [
+                'query' => [],
+                'expected' => '',
+            ],
+            'single query' => [
+                'query' => [
+                    'name' => 'matrix',
+                ],
+                'expected' => 'name=matrix',
+            ],
+            'multiple queries' => [
+                'query' => [
+                    'name' => 'matrix',
+                    'type' => 'room',
+                ],
+                'expected' => 'name=matrix&type=room',
+            ],
+        ];
+    }
+
+    /**
+     * Test the sendasjson constructor parameter.
+     *
+     * @dataProvider sendasjson_provider
+     * @param bool $sendasjson
+     * @param string $endpoint
+     * @param array $params
+     * @param array $remainingparams
+     * @param array $allparams
+     * @param array $expectedoptions
+     */
+    public function test_send_as_json(
+        bool $sendasjson,
+        string $endpoint,
+        array $params,
+        array $remainingparams,
+        array $allparams,
+        array $expectedoptions,
+    ): void {
+        $instance = $this->get_mocked_instance_for_version('v1.7');
+
+        $command = new command(
+            $instance,
+            method: 'PUT',
+            endpoint: $endpoint,
+            params: $params,
+            sendasjson: $sendasjson,
+        );
+
+        $this->assertSame($remainingparams, $command->get_remaining_params());
+        $this->assertSame($allparams, $command->get_all_params());
+        $this->assertSame($expectedoptions, $command->get_options());
+    }
+
+    /**
+     * Test the sendasjosn option to the command constructor.
+     *
+     * @return array
+     */
+    public static function sendasjson_provider(): array {
+        return [
+            'As JSON' => [
+                'sendasjon' => true,
+                'endpoint' => 'example/:id/endpoint',
+                'params' => [
+                    ':id' => 12345,
+                    'name' => 'matrix',
+                ],
+                'remainingparams' => [
+                    'name' => 'matrix',
+                ],
+                'allparams' => [
+                    ':id' => 12345,
+                    'name' => 'matrix',
+                ],
+                'expectedoptions' => [
+                    'json' => [
+                        'name' => 'matrix',
+                    ],
+                ],
+            ],
+            'Not as JSON' => [
+                'sendasjson' => false,
+                'endpoint' => 'example/:id/endpoint',
+                'params' => [
+                    ':id' => 12345,
+                    'name' => 'matrix',
+                ],
+                'remainingparams' => [
+                    'name' => 'matrix',
+                ],
+                'allparams' => [
+                    ':id' => 12345,
+                    'name' => 'matrix',
+                ],
+                'expectedoptions' => [
+                ],
+            ],
+        ];
+    }
+
+    /**
+     * Test the sendasjosn option to the command constructor.
+     */
+    public function test_ignorehttperrors(): void {
+        $instance = $this->get_mocked_instance_for_version('v1.7');
+
+        $command = new command(
+            $instance,
+            method: 'PUT',
+            endpoint: 'example/endpoint',
+            ignorehttperrors: true,
+        );
+
+        $options = $command->get_options();
+        $this->assertArrayHasKey('http_errors', $options);
+        $this->assertFalse($options['http_errors']);
+    }
+}

communication/provider/matrix/tests/matrix_client_test.php

@@ -0,0 +1,458 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix;
+
+use communication_matrix\local\command;
+use communication_matrix\local\spec\v1p7;
+use communication_matrix\local\spec\features;
+use communication_matrix\tests\fixtures\mocked_matrix_client;
+use core\http_client;
+use GuzzleHttp\Handler\MockHandler;
+use GuzzleHttp\HandlerStack;
+use GuzzleHttp\Middleware;
+use GuzzleHttp\Psr7\Response;
+use moodle_exception;
+
+defined('MOODLE_INTERNAL') || die();
+require_once(__DIR__ . '/matrix_client_test_trait.php');
+
+/**
+ * Tests for the matrix_client class.
+ *
+ * @package    communication_matrix
+ * @category   test
+ * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @covers \communication_matrix\matrix_client
+ * @coversDefaultClass \communication_matrix\matrix_client
+ */
+class matrix_client_test extends \advanced_testcase {
+    use matrix_client_test_trait;
+
+    /**
+     * Data provider for valid calls to ::instance.
+     * @return array
+     */
+    public static function instance_provider(): array {
+        $testcases = [
+            'Standard versions' => [
+                null,
+                v1p7::class,
+            ],
+        ];
+
+        // Remove a couple of versions.
+        $versions = self::get_current_versions();
+        array_pop($versions);
+        array_pop($versions);
+
+        $testcases['Older server'] = [
+            $versions,
+            array_key_last($versions),
+        ];
+
+        // Limited version compatibility, including newer than we support now.
+        $testcases['Newer versions with crossover'] = [
+            [
+                'v1.6',
+                'v1.7',
+                'v7.9',
+            ],
+            \communication_matrix\local\spec\v1p7::class,
+        ];
+
+        return $testcases;
+    }
+
+    /**
+     * Test that the instance method returns a valid instance for the given versions.
+     *
+     * @dataProvider instance_provider
+     * @param array|null $versions
+     * @param string $expectedversion
+     */
+    public function test_instance(
+        ?array $versions,
+        string $expectedversion,
+    ): void {
+        // Create a mock and queue two responses.
+
+        $mock = new MockHandler([
+            $this->get_mocked_version_response($versions),
+        ]);
+        $handlerstack = HandlerStack::create($mock);
+        $container = [];
+        $history = Middleware::history($container);
+        $handlerstack->push($history);
+        $client = new http_client(['handler' => $handlerstack]);
+        mocked_matrix_client::set_client($client);
+
+        $instance = mocked_matrix_client::instance(
+            'https://example.com',
+            'testtoken',
+        );
+
+        $this->assertInstanceOf(matrix_client::class, $instance);
+
+        // Only the version API has been called.
+        $this->assertCount(1, $container);
+        $request = reset($container);
+        $this->assertEquals('/_matrix/client/versions', $request['request']->getUri()->getPath());
+
+        // The client should be a v1p7 client as that is the highest compatible version.
+        $this->assertInstanceOf($expectedversion, $instance);
+    }
+
+    /**
+     * Test that the instance method returns a valid instance for the given versions.
+     */
+    public function test_instance_cached(): void {
+        $mock = new MockHandler([
+            $this->get_mocked_version_response(),
+            $this->get_mocked_version_response(),
+        ]);
+        $handlerstack = HandlerStack::create($mock);
+        $container = [];
+        $history = Middleware::history($container);
+        $handlerstack->push($history);
+        $client = new http_client(['handler' => $handlerstack]);
+        mocked_matrix_client::set_client($client);
+
+        $instance = mocked_matrix_client::instance('https://example.com', 'testtoken');
+
+        $this->assertInstanceOf(matrix_client::class, $instance);
+
+        // Only the version API has been called.
+        $this->assertCount(1, $container);
+
+        // Call the API again. It should not lead to additional fetches.
+        $instance = mocked_matrix_client::instance('https://example.com', 'testtoken');
+        $instance = mocked_matrix_client::instance('https://example.com', 'testtoken');
+        $this->assertCount(1, $container);
+
+        // But a different endpoint will.
+        $instance = mocked_matrix_client::instance('https://example.org', 'testtoken');
+        $this->assertCount(2, $container);
+    }
+
+    /**
+     * Test that the instance method throws an appropriate exception if no support is found.
+     */
+    public function test_instance_no_support(): void {
+        // Create a mock and queue two responses.
+
+        $mock = new MockHandler([
+            $this->get_mocked_version_response(['v99.9']),
+        ]);
+        $handlerstack = HandlerStack::create($mock);
+        $container = [];
+        $history = Middleware::history($container);
+        $handlerstack->push($history);
+        $client = new http_client(['handler' => $handlerstack]);
+        mocked_matrix_client::set_client($client);
+
+        $this->expectException(moodle_exception::class);
+        $this->expectExceptionMessage('No supported Matrix API versions found.');
+
+        mocked_matrix_client::instance(
+            'https://example.com',
+            'testtoken',
+        );
+    }
+
+    /**
+     * Test the feature implementation check methods.
+     *
+     * @covers ::implements_feature
+     * @covers ::get_supported_versions
+     * @dataProvider implements_feature_provider
+     * @param string $version
+     * @param array|string $features
+     * @param bool $expected
+     */
+    public function test_implements_feature(
+        string $version,
+        array|string $features,
+        bool $expected,
+    ): void {
+        $instance = $this->get_mocked_instance_for_version($version);
+        $this->assertEquals($expected, $instance->implements_feature($features));
+    }
+
+    /**
+     * Test the feature implementation requirement methods.
+     *
+     * @covers ::implements_feature
+     * @covers ::get_supported_versions
+     * @covers ::require_feature
+     * @dataProvider implements_feature_provider
+     * @param string $version
+     * @param array|string $features
+     * @param bool $expected
+     */
+    public function test_require_feature(
+        string $version,
+        array|string $features,
+        bool $expected,
+    ): void {
+        $instance = $this->get_mocked_instance_for_version($version);
+
+        if ($expected) {
+            $this->assertEmpty($instance->require_feature($features));
+        } else {
+            $this->expectException('moodle_exception');
+            $instance->require_feature($features);
+        }
+    }
+
+    /**
+     * Test the feature implementation requirement methods for a require all.
+     *
+     * @covers ::implements_feature
+     * @covers ::get_supported_versions
+     * @covers ::require_feature
+     * @covers ::require_features
+     * @dataProvider require_features_provider
+     * @param string $version
+     * @param array|string $features
+     * @param bool $expected
+     */
+    public function test_require_features(
+        string $version,
+        array|string $features,
+        bool $expected,
+    ): void {
+        $instance = $this->get_mocked_instance_for_version($version);
+
+        if ($expected) {
+            $this->assertEmpty($instance->require_features($features));
+        } else {
+            $this->expectException('moodle_exception');
+            $instance->require_features($features);
+        }
+    }
+
+    /**
+     * Data provider for feature implementation check tests.
+     *
+     * @return array
+     */
+    public static function implements_feature_provider(): array {
+        return [
+            'Basic supported feature' => [
+                'v1.7',
+                features\matrix\media_create_v1::class,
+                true,
+            ],
+            'Basic unsupported feature' => [
+                'v1.6',
+                features\matrix\media_create_v1::class,
+                false,
+            ],
+            '[supported] as array' => [
+                'v1.6',
+                [features\matrix\create_room_v3::class],
+                true,
+            ],
+            '[supported, supported] as array' => [
+                'v1.6',
+                [
+                    features\matrix\create_room_v3::class,
+                    features\matrix\update_room_avatar_v3::class,
+                ],
+                true,
+            ],
+            '[unsupported] as array' => [
+                'v1.6',
+                [
+                    features\matrix\media_create_v1::class,
+                ],
+                false,
+            ],
+            '[unsupported, supported] as array' => [
+                'v1.6',
+                [
+                    features\matrix\media_create_v1::class,
+                    features\matrix\update_room_avatar_v3::class,
+                ],
+                true,
+            ],
+        ];
+    }
+
+    /**
+     * Data provider for feature implementation check tests.
+     *
+     * @return array
+     */
+    public static function require_features_provider(): array {
+        // We'll just add to the standard testcases.
+        $testcases = array_map(static function (array $testcase): array {
+            $testcase[1] = [$testcase[1]];
+            return $testcase;
+        }, self::implements_feature_provider());
+
+        $testcases['Require many supported features'] = [
+            'v1.6',
+            [
+                features\matrix\create_room_v3::class,
+                features\matrix\update_room_avatar_v3::class,
+            ],
+            true,
+        ];
+
+        $testcases['Require many including an unsupported feature'] = [
+            'v1.6',
+            [
+                features\matrix\create_room_v3::class,
+                features\matrix\media_create_v1::class,
+            ],
+            false,
+        ];
+
+        $testcases['Require many including an unsupported feature which has an alternate'] = [
+            'v1.6',
+            [
+                features\matrix\create_room_v3::class,
+                [
+                    features\matrix\media_create_v1::class,
+                    features\matrix\update_room_avatar_v3::class,
+                ],
+            ],
+            true,
+        ];
+
+        return $testcases;
+    }
+
+    /**
+     * Test the get_version method.
+     *
+     * @param string $version
+     * @param string $expectedversion
+     * @dataProvider get_version_provider
+     * @covers ::get_version
+     * @covers ::get_version_from_classname
+     */
+    public function test_get_version(
+        string $version,
+        string $expectedversion,
+    ): void {
+        $instance = $this->get_mocked_instance_for_version($version);
+        $this->assertEquals($expectedversion, $instance->get_version());
+    }
+
+    /**
+     * Data provider for get_version tests.
+     *
+     * @return array
+     */
+    public static function get_version_provider(): array {
+        return [
+            ['v1.1', '1.1'],
+            ['v1.7', '1.7'],
+        ];
+    }
+
+    /**
+     * Tests the meets_version method.
+     *
+     * @param string $version The version of the API to test against
+     * @param string $testversion The version to test
+     * @param bool $expected Whether the version meets the requirement
+     * @dataProvider meets_version_provider
+     * @covers ::meets_version
+     */
+    public function test_meets_version(
+        string $version,
+        string $testversion,
+        bool $expected,
+    ): void {
+        $instance = $this->get_mocked_instance_for_version($version);
+        $this->assertEquals($expected, $instance->meets_version($testversion));
+    }
+
+    /**
+     * Tests the requires_version method.
+     *
+     * @param string $version The version of the API to test against
+     * @param string $testversion The version to test
+     * @param bool $expected Whether the version meets the requirement
+     * @dataProvider meets_version_provider
+     * @covers ::requires_version
+     */
+    public function test_requires_version(
+        string $version,
+        string $testversion,
+        bool $expected,
+    ): void {
+        $instance = $this->get_mocked_instance_for_version($version);
+
+        if ($expected) {
+            $this->assertEmpty($instance->requires_version($testversion));
+        } else {
+            $this->expectException('moodle_exception');
+            $instance->requires_version($testversion);
+        }
+    }
+
+    /**
+     * Data provider for meets_version tests.
+     *
+     * @return array
+     */
+    public static function meets_version_provider(): array {
+        return [
+            'Same version' => ['v1.1', '1.1', true],
+            'Same version latest' => ['v1.7', '1.7', true],
+            'Newer version rejected' => ['v1.1', '1.7', false],
+            'Older version accepted' => ['v1.7', '1.1', true],
+        ];
+    }
+
+    /**
+     * Test the execute method with a command.
+     *
+     * @covers ::execute
+     */
+    public function test_command_is_executed(): void {
+        $historycontainer = [];
+        $mock = new MockHandler();
+
+        $instance = $this->get_mocked_instance_for_version('v1.6', $historycontainer, $mock);
+        $command = new command(
+            $instance,
+            method: 'GET',
+            endpoint: 'test/endpoint',
+            params: [
+                'test' => 'test',
+            ],
+        );
+
+        $mock->append(new Response(200));
+
+        $rc = new \ReflectionClass($instance);
+        $rcm = $rc->getMethod('execute');
+        $result = $rcm->invoke($instance, $command);
+
+        $this->assertEquals(200, $result->getStatusCode());
+        $this->assertCount(1, $historycontainer);
+        $request = array_shift($historycontainer);
+        $this->assertEquals('GET', $request['request']->getMethod());
+        $this->assertEquals('/test/endpoint', $request['request']->getUri()->getPath());
+    }
+}

communication/provider/matrix/tests/matrix_client_test_trait.php

@@ -0,0 +1,169 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix;
+
+use communication_matrix\local\spec\{v1p1, v1p2, v1p3, v1p4, v1p5, v1p6, v1p7};
+use communication_matrix\tests\fixtures\mocked_matrix_client;
+use core\http_client;
+use GuzzleHttp\Handler\MockHandler;
+use GuzzleHttp\HandlerStack;
+use GuzzleHttp\Middleware;
+use GuzzleHttp\Psr7\Response;
+
+/**
+ * A trait with shared tooling for handling matrix_client tests.
+ *
+ * @package    communication_matrix
+ * @category   test
+ * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+trait matrix_client_test_trait {
+    public static function setUpBeforeClass(): void {
+        parent::setUpBeforeClass();
+
+        // Ensure that the mocked client is available.
+        require_once(__DIR__ . '/fixtures/mocked_matrix_client.php');
+    }
+
+    public function setUp(): void {
+        parent::setUp();
+
+        // Reset the test client.
+        mocked_matrix_client::reset_client();
+    }
+
+    public function tearDown(): void {
+        parent::tearDown();
+
+        // Reset the test client.
+        mocked_matrix_client::reset_client();
+    }
+
+    /**
+     * Get a mocked instance for a specific Matrix API version,
+     *
+     * @param string $version
+     * @param array $historycontainer An array which will be filled with history for the mocked client.
+     * @param MockHandler|null $mock A MockHandler object that can be appended to
+     * @return matrix_client
+     */
+    protected function get_mocked_instance_for_version(
+        string $version,
+        array &$historycontainer = [],
+        ?MockHandler $mock = null,
+    ): matrix_client {
+        if ($mock === null) {
+            $mock = new MockHandler();
+        }
+        // Add the version response.
+        $mock->append($this->get_mocked_version_response([$version]));
+
+        $handlerstack = HandlerStack::create($mock);
+        $history = Middleware::history($historycontainer);
+        $handlerstack->push($history);
+        $client = new http_client(['handler' => $handlerstack]);
+        mocked_matrix_client::set_client($client);
+
+        $client = mocked_matrix_client::instance(
+            'https://example.com',
+            'testtoken',
+        );
+
+        // Remove the request that is required to fetch the version from the history.
+        array_shift($historycontainer);
+
+        return $client;
+    }
+
+    /**
+     * Get a mocked response for the /versions well-known URI.
+     *
+     * @param array|null $versions
+     * @param array|null $unstablefeatures
+     * @return Response
+     */
+    protected function get_mocked_version_response(
+        array $versions = null,
+        array $unstablefeatures = null,
+    ): Response {
+        $data = (object) [
+            "versions" => array_values(self::get_current_versions()),
+            "unstable_features" => self::get_current_unstable_features(),
+        ];
+
+        if ($versions) {
+            $data->versions = array_values($versions);
+        }
+
+        if ($unstablefeatures) {
+            $data->unstable_features = $unstablefeatures;
+        }
+
+        return new Response(200, [], json_encode($data));
+    }
+
+    /**
+     * A helper to get the current versions returned by synapse.
+     *
+     * @return array
+     */
+    protected static function get_current_versions(): array {
+        return [
+            v1p1::class => "v1.1",
+            v1p2::class => "v1.2",
+            v1p3::class => "v1.3",
+            v1p4::class => "v1.4",
+            v1p5::class => "v1.5",
+            v1p6::class => "v1.6",
+            v1p7::class => "v1.7",
+        ];
+    }
+
+    /**
+     * A helper to get the current unstable features returned by synapse.
+     * @return array
+     */
+    protected static function get_current_unstable_features(): array {
+        return [
+            "org.matrix.label_based_filtering" => true,
+            "org.matrix.e2e_cross_signing" => true,
+            "org.matrix.msc2432" => true,
+            "uk.half-shot.msc2666.query_mutual_rooms" => true,
+            "io.element.e2ee_forced.public" => false,
+            "io.element.e2ee_forced.private" => false,
+            "io.element.e2ee_forced.trusted_private" => false,
+            "org.matrix.msc3026.busy_presence" => false,
+            "org.matrix.msc2285.stable" => true,
+            "org.matrix.msc3827.stable" => true,
+            "org.matrix.msc2716" => false,
+            "org.matrix.msc3440.stable" => true,
+            "org.matrix.msc3771" => true,
+            "org.matrix.msc3773" => false,
+            "fi.mau.msc2815" => false,
+            "fi.mau.msc2659.stable" => true,
+            "org.matrix.msc3882" => false,
+            "org.matrix.msc3881" => false,
+            "org.matrix.msc3874" => false,
+            "org.matrix.msc3886" => false,
+            "org.matrix.msc3912" => false,
+            "org.matrix.msc3952_intentional_mentions" => false,
+            "org.matrix.msc3981" => false,
+            "org.matrix.msc3391" => false,
+        ];
+    }
+}

communication/provider/matrix/tests/matrix_room_test.php

@@ -0,0 +1,140 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix;
+
+/**
+ * Tests for the matrix_room class.
+ *
+ * @package    communication_matrix
+ * @category   test
+ * @copyright  2023 Safat Shahin <safat.shahin@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @coversDefaultClass \communication_matrix\matrix_room
+ */
+class matrix_room_test extends \advanced_testcase {
+    /**
+     * Test for load_by_processor_id with no record.
+     *
+     * @covers ::load_by_processor_id
+     */
+    public function test_load_by_processor_id_none(): void {
+        $this->assertNull(matrix_room::load_by_processor_id(999999999));
+    }
+
+    /**
+     * Test for load_by_processor_id with valid records.
+     *
+     * @covers ::create_room_record
+     * @covers ::__construct
+     * @covers ::load_by_processor_id
+     * @covers ::get_processor_id
+     * @covers ::get_room_id
+     * @covers ::get_topic
+     */
+    public function test_create_room_record(): void {
+        $this->resetAfterTest();
+
+        $room = matrix_room::create_room_record(
+            processorid: 10000,
+            topic: null,
+        );
+        $this->assertInstanceOf(matrix_room::class, $room);
+        $this->assertEquals(10000, $room->get_processor_id());
+        $this->assertNotNull('', $room->get_topic());
+        $this->assertEquals('', $room->get_topic());
+        $this->assertNull($room->get_room_id());
+
+        $room = matrix_room::create_room_record(
+            processorid: 12345,
+            topic: 'The topic of this room is thusly',
+        );
+
+        $this->assertInstanceOf(matrix_room::class, $room);
+        $this->assertEquals(12345, $room->get_processor_id());
+        $this->assertEquals('The topic of this room is thusly', $room->get_topic());
+        $this->assertNull($room->get_room_id());
+
+        $room = matrix_room::create_room_record(
+            processorid: 54321,
+            topic: 'The topic of this room is thusly',
+            roomid: 'This is a roomid',
+        );
+
+        $this->assertInstanceOf(matrix_room::class, $room);
+        $this->assertEquals(54321, $room->get_processor_id());
+        $this->assertEquals('The topic of this room is thusly', $room->get_topic());
+        $this->assertEquals('This is a roomid', $room->get_room_id());
+
+        $reloadedroom = matrix_room::load_by_processor_id(54321);
+        $this->assertEquals(54321, $reloadedroom->get_processor_id());
+        $this->assertEquals('The topic of this room is thusly', $reloadedroom->get_topic());
+        $this->assertEquals('This is a roomid', $reloadedroom->get_room_id());
+    }
+
+    /**
+     * Test for update_room_record.
+     *
+     * @covers ::update_room_record
+     */
+    public function test_update_room_record(): void {
+        $this->resetAfterTest();
+
+        $room = matrix_room::create_room_record(
+            processorid: 12345,
+            topic: 'The topic of this room is that',
+        );
+
+        // Add a roomid.
+        $room->update_room_record(
+            roomid: 'This is a roomid',
+        );
+
+        $this->assertEquals('This is a roomid', $room->get_room_id());
+        $this->assertEquals('The topic of this room is that', $room->get_topic());
+        $this->assertEquals(12345, $room->get_processor_id());
+
+        // Alter the roomid and topic.
+        $room->update_room_record(
+            roomid: 'updatedRoomId',
+            topic: 'updatedTopic is here',
+        );
+
+        $this->assertEquals('updatedRoomId', $room->get_room_id());
+        $this->assertEquals('updatedTopic is here', $room->get_topic());
+        $this->assertEquals(12345, $room->get_processor_id());
+    }
+
+    /**
+     * Tests for delete_room_record.
+     *
+     * @covers ::delete_room_record
+     */
+    public function test_delete_room_record(): void {
+        global $DB;
+
+        $this->resetAfterTest();
+
+        $room = matrix_room::create_room_record(
+            processorid: 12345,
+            topic: 'The topic of this room is that',
+        );
+        $this->assertCount(1, $DB->get_records('matrix_room'));
+
+        $room->delete_room_record();
+        $this->assertCount(0, $DB->get_records('matrix_room'));
+    }
+}

communication/provider/matrix/tests/matrix_test_helper_trait.php

@@ -0,0 +1,295 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix;
+
+use core\context;
+use GuzzleHttp\Psr7\Response;
+
+/**
+ * Trait matrix_helper_trait to generate initial setup for matrix mock and associated helpers.
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Safat Shahin <safat.shahin@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+trait matrix_test_helper_trait {
+    /**
+     * @var string $accesstoken The token for matrix connection
+     */
+    protected string $accesstoken;
+
+    /**
+     * @var string $matrixhomeserverurl The server url of matrix synapse server
+     */
+    protected string $matrixhomeserverurl;
+
+    /**
+     * Initialize the mock configs in settings.
+     *
+     * @return void
+     */
+    protected function initialise_mock_configs(): void {
+        $this->matrixhomeserverurl = TEST_COMMUNICATION_MATRIX_MOCK_SERVER;
+        set_config('matrixhomeserverurl', $this->matrixhomeserverurl, 'communication_matrix');
+        $request = $this->request();
+        $response = $request->post($this->matrixhomeserverurl . '/backoffice/create-admin');
+        $admindata = json_decode($response->getBody());
+        $json = [
+            'identifier' => [
+                'type' => 'm.id.user',
+                'user' => $admindata->user_id,
+            ],
+            'type' => 'm.login.password',
+            'password' => $admindata->password,
+        ];
+        $request = $this->request($json);
+        $response = $request->post($this->matrixhomeserverurl . '/_matrix/client/r0/login');
+        $response = json_decode($response->getBody());
+        if (empty($response->access_token)) {
+            $this->markTestSkipped(
+                'The matrix mock server is not responsive, can not continue the tests'
+            );
+        }
+        $this->accesstoken = $response->access_token;
+        set_config('matrixaccesstoken', $this->accesstoken, 'communication_matrix');
+    }
+
+    /**
+     * Get the mock server url.
+     *
+     * @return string
+     */
+    public function get_matrix_server_url(): string {
+        if (empty($this->matrixhomeserverurl)) {
+            throw new \coding_exception('Can not get this information without initializing the mock server.');
+        }
+        return $this->matrixhomeserverurl;
+    }
+
+    /**
+     * Get the matrix access token.
+     *
+     * @return string
+     */
+    public function get_matrix_access_token(): string {
+        if (empty($this->accesstoken)) {
+            throw new \coding_exception('Can not get this information without initializing the mock server.');
+        }
+        return $this->accesstoken;
+    }
+
+    /**
+     * This test requires mock server to be present.
+     *
+     * @return void
+     */
+    protected function initialise_mock_server(): void {
+        if (!defined('TEST_COMMUNICATION_MATRIX_MOCK_SERVER')) {
+            $this->markTestSkipped(
+                'The TEST_COMMUNICATION_MATRIX_MOCK_SERVER constant must be defined to run communication_matrix tests'
+            );
+        }
+        $this->reset_mock();
+        $this->initialise_mock_configs();
+    }
+
+    /**
+     * Get matrix room data from matrix server.
+     *
+     * @param string $roomid The id of the room
+     * @return \stdClass
+     */
+    public function get_matrix_room_data(string $roomid): \stdClass {
+        $rooms = $this->backoffice_get_all_rooms();
+        foreach ($rooms as $room) {
+            if ($room->room_id === $roomid) {
+                return $room;
+            }
+        }
+    }
+
+    /**
+     * Get matrix user data from matrix server.
+     *
+     * @param string $roomid The id of the room
+     * @param string $matrixuserid The id of the user
+     * @return \stdClass
+     */
+    public function get_matrix_user_data(string $roomid, string $matrixuserid): \stdClass {
+        $users = $this->backoffice_get_all_users();
+
+        foreach ($users as $user) {
+            if ($user->userid === $matrixuserid) {
+                return $user;
+            }
+        }
+    }
+
+    /**
+     * A backoffice call to get all registered users from our mock server.
+     *
+     * @return array
+     */
+    public function backoffice_get_all_users(): array {
+        $client = new \core\http_client();
+
+        return json_decode($client->get($this->get_backoffice_uri('users'))->getBody())->users;
+    }
+
+    /**
+     * A backoffice method to create users and rooms on our mock server.
+     *
+     * @param array $users
+     * @param array $rooms
+     */
+    public function backoffice_create_users_and_rooms(
+        array $users = [],
+        array $rooms = [],
+    ): Response {
+        $client = new \core\http_client();
+        return $client->put(
+            $this->get_backoffice_uri('create'),
+            [
+                'json' => [
+                    'users' => $users,
+                    'rooms' => $rooms,
+                ],
+            ],
+        );
+    }
+
+    /**
+     * The http request for the api call.
+     *
+     * @param array $jsonarray The array of json
+     * @param array $headers The array of headers
+     * @return \core\http_client
+     */
+    public function request(array $jsonarray = [], array $headers = []): \core\http_client {
+        $response = new \core\http_client([
+            'headers' => $headers,
+            'json' => $jsonarray,
+        ]);
+        return $response;
+    }
+
+    /**
+     * Get the URI of a backoffice endpoint on the mock server.
+     *
+     * @param string $endpoint
+     * @return string
+     */
+    protected function get_backoffice_uri(string $endpoint): string {
+        return $this->get_matrix_server_url() . '/backoffice/' . $endpoint;
+    }
+
+    /**
+     * Fetch all rooms from the back office.
+     *
+     * @return array
+     */
+    public function backoffice_get_all_rooms(): array {
+        $client = new \core\http_client();
+
+        return json_decode($client->get($this->get_backoffice_uri('rooms'))->getBody())->rooms;
+    }
+
+    /**
+     * Return the first room from the server.
+     *
+     * In most cases there is only one room.
+     * @return \stdClass
+     */
+    public function backoffice_get_room(): \stdClass {
+        // Fetch the room information from the server.
+        $rooms = $this->backoffice_get_all_rooms();
+        $this->assertCount(1, $rooms);
+        $room = reset($rooms);
+        return $room;
+    }
+
+    /**
+     * Reset the mock server
+     *
+     * @return void
+     */
+    public function reset_mock(): void {
+        if (defined('TEST_COMMUNICATION_MATRIX_MOCK_SERVER')) {
+            $request = $this->request();
+            $response = $request->post(TEST_COMMUNICATION_MATRIX_MOCK_SERVER . '/backoffice/reset');
+            $response = json_decode($response->getBody());
+            if (empty($response->reset)) {
+                $this->markTestSkipped(
+                    'The matrix mock server is not responsive, can not continue the tests'
+                );
+            }
+        }
+    }
+
+    /**
+     * Helper to create a room.
+     *
+     * @param null|string $component
+     * @param null|string $itemtype
+     * @param null|int $itemid
+     * @param null|string $roomname
+     * @param null|string $roomtopic
+     * @param null|stored_file $roomavatar
+     * @param array $members
+     * @return api
+     */
+    protected function create_matrix_room(
+        ?string $component = 'core_course',
+        ?string $itemtype = 'example',
+        ?int $itemid = 1,
+        ?string $roomname = null,
+        ?string $roomtopic = null,
+        ?\stored_file $roomavatar = null,
+        array $members = [],
+        ?context $context = null,
+    ): \core_communication\api {
+        $context = $context ?? \core\context\system::instance();
+        // Create a new room.
+        $communication = \core_communication\api::load_by_instance(
+            context: $context,
+            component: $component,
+            instancetype: $itemtype,
+            instanceid: $itemid,
+            provider: 'communication_matrix',
+        );
+
+        $communication->create_and_configure_room(
+            communicationroomname: $roomname ?? 'Room name',
+            avatar: $roomavatar,
+            instance: (object) [
+                'matrixroomtopic' => $roomtopic ?? 'A fun topic',
+            ],
+        );
+
+        $communication->add_members_to_room($members);
+
+        // Run the adhoc task.
+        $this->run_all_adhoc_tasks();
+
+        return \core_communication\api::load_by_instance(
+            context: $context,
+            component: $component,
+            instancetype: $itemtype,
+            instanceid: $itemid,
+        );
+    }
+}

communication/provider/matrix/tests/matrix_user_manager_test.php

@@ -0,0 +1,239 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace communication_matrix;
+
+use moodle_exception;
+
+/**
+ * Class matrix_user_manager_test to test the matrix user manager.
+ *
+ * @package    communication_matrix
+ * @category   test
+ * @copyright  2023 Stevani Andolo <stevani.andolo@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @covers \communication_matrix\matrix_user_manager
+ */
+class matrix_user_manager_test extends \advanced_testcase {
+    /**
+     * Test fetcihing a users matrix userid from Moodle.
+     */
+    public function test_get_matrixid_from_moodle_without_field(): void {
+        $user = get_admin();
+
+        $this->assertNull(matrix_user_manager::get_matrixid_from_moodle($user->id));
+    }
+
+    /**
+     * Test fetching a user's matrix userid from Moodle.
+     */
+    public function test_get_matrixid_from_moodle(): void {
+        $this->resetAfterTest();
+
+        $user1 = $this->getDataGenerator()->create_user();
+        $user2 = $this->getDataGenerator()->create_user();
+
+        // Add user ids to both users.
+        matrix_user_manager::set_matrix_userid_in_moodle(
+            $user1->id,
+            '@someexampleuser:matrix.moodle.org',
+        );
+
+        matrix_user_manager::set_matrix_userid_in_moodle(
+            $user2->id,
+            '@someotherexampleuser:matrix.moodle.org',
+        );
+
+        // And confirm that they're fetched back.
+        $this->assertEquals(
+            '@someexampleuser:matrix.moodle.org',
+            matrix_user_manager::get_matrixid_from_moodle($user1->id),
+        );
+        $this->assertEquals(
+            '@someotherexampleuser:matrix.moodle.org',
+            matrix_user_manager::get_matrixid_from_moodle($user2->id),
+        );
+    }
+
+    /**
+     * Test fetching a formatted matrix userid from Moodle when no server is set.
+     */
+    public function test_get_formatted_matrix_userid_unset(): void {
+        $this->expectException(moodle_exception::class);
+
+        matrix_user_manager::get_formatted_matrix_userid('No value');
+    }
+
+    /**
+     * Test fetch of a formatted matrix userid.
+     *
+     * @dataProvider get_formatted_matrix_userid_provider
+     * @param string $server
+     * @param string $username The moodle username to turn into a Matrix username
+     * @param string $expecteduserid The expected matrix user id
+     */
+    public function test_get_formatted_matrix_userid(
+        string $server,
+        string $username,
+        string $expecteduserid,
+    ): void {
+        $this->resetAfterTest();
+
+        set_config('matrixhomeserverurl', $server, 'communication_matrix');
+        $this->assertEquals(
+            $expecteduserid,
+            matrix_user_manager::get_formatted_matrix_userid($username),
+        );
+    }
+
+    /**
+     * Data provider for get_formatted_matrix_userid.
+     *
+     * @return array
+     */
+    public static function get_formatted_matrix_userid_provider(): array {
+        return [
+            'alphanumeric' => [
+                'https://matrix.example.org',
+                'alphabet1',
+                '@alphabet1:matrix.example.org',
+            ],
+            'chara' => [
+                'https://matrix.example.org',
+                'asdf#$%^&*()+{}|<>?!,asdf',
+                '@asdf.................asdf:matrix.example.org',
+            ],
+            'local server' => [
+                'https://synapse',
+                'colin.creavey',
+                '@colin.creavey:synapse',
+            ],
+            'server with port' => [
+                'https://matrix.example.org:8448',
+                'colin.creavey',
+                '@colin.creavey:matrix.example.org',
+            ],
+            'numeric username' => [
+                'https://matrix.example.org',
+                '123456',
+                '@' . matrix_user_manager::MATRIX_USER_PREFIX . '123456:matrix.example.org',
+            ],
+        ];
+    }
+
+    /**
+     * Data provider for set_matrix_userid_in_moodle.
+     *
+     * @return array
+     */
+    public static function set_matrix_userid_in_moodle_provider(): array {
+        return array_combine(
+            array_keys(self::get_formatted_matrix_userid_provider()),
+            array_map(
+                fn($value) => [$value[2]],
+                self::get_formatted_matrix_userid_provider(),
+            ),
+        );
+    }
+
+    /**
+     * Test setting of a user's matrix userid in Moodle.
+     *
+     * @dataProvider set_matrix_userid_in_moodle_provider
+     * @param string $expectedusername
+     */
+    public function test_set_matrix_userid_in_moodle(
+        string $expectedusername,
+    ): void {
+        $this->resetAfterTest();
+
+        $user = $this->getDataGenerator()->create_user();
+        matrix_user_manager::set_matrix_userid_in_moodle($user->id, $expectedusername);
+
+        // Get created matrixuserid from moodle.
+        $this->assertEquals(
+            $expectedusername,
+            matrix_user_manager::get_matrixid_from_moodle($user->id),
+        );
+    }
+
+    /**
+     * Test for getting a formatted matrix home server id.
+     *
+     * @dataProvider get_formatted_matrix_home_server_provider
+     * @param string $input
+     * @param string $expectedoutput
+     */
+    public function test_get_formatted_matrix_home_server(
+        string $input,
+        string $expectedoutput
+    ): void {
+        $this->resetAfterTest();
+
+        set_config(
+            'matrixhomeserverurl',
+            $input,
+            'communication_matrix',
+        );
+
+        $this->assertEquals(
+            $expectedoutput,
+            matrix_user_manager::get_formatted_matrix_home_server(),
+        );
+    }
+
+    /**
+     * Data provider for get_formatted_matrix_home_server.
+     *
+     * @return array
+     */
+    public static function get_formatted_matrix_home_server_provider(): array {
+        return [
+            'www is removed' => [
+                'https://www.example.org',
+                'example.org',
+            ],
+            'www is not removed if it is not at the beginning' => [
+                'https://matrix.www.example.org',
+                'matrix.www.example.org',
+            ],
+            'others are not removed' => [
+                'https://matrix.example.org',
+                'matrix.example.org',
+            ],
+        ];
+    }
+
+    /**
+     * Test creation of matrix user profile fields.
+     */
+    public function test_create_matrix_user_profile_fields(): void {
+        global $CFG;
+        require_once("{$CFG->dirroot}/user/profile/lib.php");
+
+        $this->resetAfterTest();
+
+        $matrixprofilefield = get_config('communication_matrix', 'matrixuserid_field');
+        $this->assertFalse($matrixprofilefield);
+
+        $this->assertIsString(matrix_user_manager::create_matrix_user_profile_fields());
+        $matrixprofilefield = get_config('communication_matrix', 'matrixuserid_field');
+        $this->assertNotFalse($matrixprofilefield);
+
+        $user = $this->getDataGenerator()->create_user();
+        $this->assertObjectHasProperty($matrixprofilefield, profile_user_record($user->id));
+    }
+}

communication/provider/matrix/version.php

@@ -0,0 +1,30 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * Version information for communication_matrix.
+ *
+ * @package    communication_matrix
+ * @copyright  2023 Safat Shahin <safat.shahin@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+defined('MOODLE_INTERNAL') || die();
+
+$plugin->component = 'communication_matrix';
+$plugin->version = 2024042200;
+$plugin->requires = 2024041600;
+$plugin->maturity = MATURITY_ALPHA;

communication/provider/upgrade.txt

@@ -0,0 +1,2 @@
+This file describes API changes in /communication/provider/*
+Information provided here is intended especially for developers.