MDL-73008 tool_policy: New WS to set user acceptances

admin/tool/policy/classes/external/set_acceptances_status.php

@@ -0,0 +1,137 @@
+<?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 tool_policy\external;
+
+use core_external\external_api;
+use core_external\external_function_parameters;
+use core_external\external_single_structure;
+use core_external\external_multiple_structure;
+use core_external\external_value;
+use core_external\external_warnings;
+use tool_policy\api;
+use tool_policy\policy_version;
+use core_user;
+
+/**
+ * External function for setting user policies acceptances.
+ *
+ * @package    tool_policy
+ * @copyright  2023 Juan Leyva <juan@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since      Moodle 4.4
+ */
+class set_acceptances_status extends external_api {
+
+    /**
+     * Webservice parameters.
+     *
+     * @return external_function_parameters
+     */
+    public static function execute_parameters(): external_function_parameters {
+        return new external_function_parameters(
+            [
+                'policies' => new external_multiple_structure(
+                    new external_single_structure([
+                        'versionid' => new external_value(PARAM_INT, 'The policy version id.'),
+                        'status' => new external_value(PARAM_INT, 'The policy acceptance status. 0: decline, 1: accept.'),
+                    ]), 'Policies acceptances for the given user.'
+                ),
+                'userid' => new external_value(PARAM_INT,
+                    'The user id we want to set the acceptances. Default is the current user.', VALUE_DEFAULT, 0
+                ),
+            ]
+        );
+    }
+
+    /**
+     * Set the acceptance status (accept or decline only) for the indicated policies for the given user.
+     *
+     * @param array $policies the policies to set the acceptance status
+     * @param int $userid the user id we want to retrieve the acceptances
+     * @throws \moodle_exception
+     * @return array policies and acceptance status
+     */
+    public static function execute(array $policies, int $userid = 0): array {
+        global $USER;
+
+        $params = self::validate_parameters(self::execute_parameters(),
+            [
+                'policies' => $policies,
+                'userid' => $userid,
+            ]
+        );
+
+        // Do not check for the site policies in validate_context() to avoid the redirect loop.
+        if (!defined('NO_SITEPOLICY_CHECK')) {
+            define('NO_SITEPOLICY_CHECK', true);
+        }
+
+        $systemcontext = \context_system::instance();
+        external_api::validate_context($systemcontext);
+
+        if (empty($params['userid']) || $params['userid'] == $USER->id) {
+            $user = $USER;
+        } else {
+            $user = core_user::get_user($params['userid'], '*', MUST_EXIST);
+            core_user::require_active_user($user);
+        }
+
+        // Split acceptances.
+        $allcurrentpolicies = api::list_current_versions(policy_version::AUDIENCE_LOGGEDIN);
+        $requestedpolicies = $agreepolicies = $declinepolicies = [];
+        foreach ($params['policies'] as $policy) {
+            $requestedpolicies[$policy['versionid']] = $policy['status'];
+        }
+
+        foreach ($allcurrentpolicies as $policy) {
+            if (isset($requestedpolicies[$policy->id])) {
+                if ($requestedpolicies[$policy->id] === 1) {
+                    $agreepolicies[] = $policy->id;
+                } else if ($requestedpolicies[$policy->id] === 0) {
+                    $declinepolicies[] = $policy->id;
+                }
+            }
+        }
+
+        // Permissions check.
+        api::can_accept_policies($agreepolicies, $user->id, true);
+        api::can_decline_policies($declinepolicies, $user->id, true);
+
+        // Good to go.
+        api::accept_policies($agreepolicies, $user->id, null);
+        api::decline_policies($declinepolicies, $user->id, null);
+
+        $return = [
+            'policyagreed' => (int) $user->policyagreed,  // Final policy agreement status for $user.
+            'warnings' => [],
+        ];
+        return $return;
+    }
+
+    /**
+     * Webservice returns.
+     *
+     * @return external_single_structure
+     */
+    public static function execute_returns(): external_single_structure {
+        return new external_single_structure([
+            'policyagreed' => new external_value(PARAM_INT,
+                'Whether the user has provided acceptance to all current site policies. 1 if yes, 0 if not'),
+            'warnings'  => new external_warnings(),
+        ]);
+    }
+}

admin/tool/policy/db/services.php

@@ -52,4 +52,11 @@ $functions = [
         'type' => 'read',
         'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE],
     ],
+
+    'tool_policy_set_acceptances_status' => [
+        'classname' => '\tool_policy\external\set_acceptances_status',
+        'description' => 'Set the acceptance status (accept or decline only) for the indicated policies for the given user.',
+        'type' => 'write',
+        'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE],
+    ],
 ];

admin/tool/policy/tests/externallib_test.php

@@ -290,4 +290,110 @@ class externallib_test extends externallib_advanced_testcase {
         $this->expectException(\required_capability_exception::class);
         $policies = \tool_policy\external\get_user_acceptances::execute($user->id);
     }
+
+    /**
+     * Test for external function set_acceptances_status().
+     */
+    public function test_external_set_acceptances_status() {
+        global $CFG;
+
+        $this->resetAfterTest(true);
+        $CFG->sitepolicyhandler = 'tool_policy';
+        $user = $this->getDataGenerator()->create_user();
+        $this->setUser($user);
+
+        // Create optional policy.
+        $formdata = api::form_policydoc_data(new \tool_policy\policy_version(0));
+        $formdata->name = 'Test optional policy';
+        $formdata->revision = 'v1';
+        $formdata->optional = 1;
+        $formdata->summary_editor = ['text' => 'summary', 'format' => FORMAT_HTML, 'itemid' => 0];
+        $formdata->content_editor = ['text' => 'content', 'format' => FORMAT_HTML, 'itemid' => 0];
+        $optionalpolicy = api::form_policydoc_add($formdata);
+        api::make_current($optionalpolicy->get('id'));
+
+        // Accept all the policies.
+        $ids = [['versionid' => $this->policy2->get('id'), 'status' => 1], ['versionid' => $optionalpolicy->get('id'), 'status' => 1]];
+
+        $policies = \tool_policy\external\set_acceptances_status::execute($ids);
+        $policies = \core_external\external_api::clean_returnvalue(
+            \tool_policy\external\set_acceptances_status::execute_returns(), $policies);
+
+        $this->assertEquals(1, $policies['policyagreed']);
+        $this->assertCount(0, $policies['warnings']);
+
+        $policies = \tool_policy\external\get_user_acceptances::execute();
+        $policies = \core_external\external_api::clean_returnvalue(
+            \tool_policy\external\get_user_acceptances::execute_returns(), $policies);
+
+        $this->assertCount(2, $policies['policies']);
+        foreach ($policies['policies'] as $policy) {
+            $this->assertEquals(1, $policy['acceptance']['status']);    // Check all accepted.
+        }
+
+        // Decline optional only.
+        $policies = \tool_policy\external\set_acceptances_status::execute([['versionid' => $optionalpolicy->get('id'), 'status' => 0]]);
+        $policies = \core_external\external_api::clean_returnvalue(
+            \tool_policy\external\set_acceptances_status::execute_returns(), $policies);
+
+        $this->assertEquals(1, $policies['policyagreed']);
+        $this->assertCount(0, $policies['warnings']);
+
+        $policies = \tool_policy\external\get_user_acceptances::execute();
+        $policies = \core_external\external_api::clean_returnvalue(
+            \tool_policy\external\get_user_acceptances::execute_returns(), $policies);
+
+        $this->assertCount(2, $policies['policies']);
+        foreach ($policies['policies'] as $policy) {
+            if ($policy['versionid'] == $this->policy2->get('id')) {
+                $this->assertEquals(1, $policy['acceptance']['status']);    // Still accepted.
+            } else {
+                $this->assertEquals(0, $policy['acceptance']['status']);    // Not accepted.
+            }
+        }
+
+        // Parent & child case now. Accept the optional ONLY on behalf of someone else.
+        $this->parent->policyagreed = 1;
+        $this->setUser($this->parent);
+        $policies = \tool_policy\external\set_acceptances_status::execute([['versionid' => $optionalpolicy->get('id'), 'status' => 1]], $this->child->id);
+        $policies = \core_external\external_api::clean_returnvalue(
+            \tool_policy\external\set_acceptances_status::execute_returns(), $policies);
+
+        $this->assertEquals(0, $policies['policyagreed']);  // Mandatory missing.
+        $this->assertCount(0, $policies['warnings']);
+
+        $policies = \tool_policy\external\get_user_acceptances::execute($this->child->id);
+        $policies = \core_external\external_api::clean_returnvalue(
+            \tool_policy\external\get_user_acceptances::execute_returns(), $policies);
+
+        $this->assertCount(2, $policies['policies']);
+        foreach ($policies['policies'] as $policy) {
+            if ($policy['versionid'] == $this->policy2->get('id')) {
+                $this->assertNotContains('acceptance', $policy);    // Not yet accepted.
+            } else {
+                $this->assertEquals(1, $policy['acceptance']['status']);    // Accepted.
+            }
+        }
+
+        // Try to accept on behalf of other user with no permissions.
+        $this->expectException(\required_capability_exception::class);
+        $policies = \tool_policy\external\set_acceptances_status::execute([['versionid' => $optionalpolicy->get('id'), 'status' => 1]], $user->id);
+    }
+
+    /**
+     * Test for external function set_acceptances_status decline mandatory.
+     */
+    public function test_external_set_acceptances_status_decline_mandatory() {
+        global $CFG;
+
+        $this->resetAfterTest(true);
+        $CFG->sitepolicyhandler = 'tool_policy';
+        $this->parent->policyagreed = 1;
+        $this->setUser($this->parent);
+
+        $this->expectException(\moodle_exception::class);
+        $this->expectExceptionMessage(get_string('errorpolicyversioncompulsory', 'tool_policy'));
+        $ids = [['versionid' => $this->policy2->get('id'), 'status' => 0]];
+        $policies = \tool_policy\external\set_acceptances_status::execute($ids, $this->child->id);
+    }
 }