first commit

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;
+}