MDL-56126 user: New WS core_user_agree_site_policy

This commit includes a change in moodlelib to throw the
sitepolicynotagreed exception in a way that can be captured and
identified by external systems.

lang/en/error.php

@@ -490,6 +490,7 @@
 $string['sessionipnomatch2'] = '<p>Sorry, but your IP number seems to have changed from when you first logged in. This security feature prevents crackers stealing your identity while logged in to this site. You may see this error if you use wireless networks or if you are roaming between different networks. Please ask the site administrator for more help.</p>
 <p>If you want to continue please press F5 key to refresh this page.</p>';
 $string['shortnametaken'] = 'Short name is already used for another course ({$a})';
+$string['sitepolicynotagreed'] = 'Site policy not agreed: <a href="{$a}">Click here to open the site policy.</a>';
 $string['scheduledbackupsdisabled'] = 'Scheduled backups have been disabled by the server admin';
 $string['socksnotsupported'] = 'SOCKS5 proxy is not supported in PHP4';
 $string['spellcheckernotconf'] = 'Spellchecker not configured';

lib/db/services.php

@@ -921,6 +921,14 @@
         'type' => 'write',
         'capabilities' => 'moodle/site:config',
     ),
+    'core_user_agree_site_policy' => array(
+        'classname' => 'core_user_external',
+        'methodname' => 'agree_site_policy',
+        'classpath' => 'user/externallib.php',
+        'description' => 'Agree the site policy for the current user.',
+        'type' => 'write',
+        'services' => array(MOODLE_OFFICIAL_MOBILE_SERVICE),
+    ),
 
     // Competencies functions.
     'core_competency_create_competency_framework' => array(

lib/moodlelib.php

@@ -2685,15 +2685,15 @@ function require_login($courseorid = null, $autologinguest = true, $cm = null, $
     if (!$USER->policyagreed and !is_siteadmin()) {
         if (!empty($CFG->sitepolicy) and !isguestuser()) {
             if ($preventredirect) {
-                throw new require_login_exception('Policy not agreed');
+                throw new moodle_exception('sitepolicynotagreed', 'error', '', $CFG->sitepolicy);
             }
             if ($setwantsurltome) {
                 $SESSION->wantsurl = qualified_me();
             }
             redirect($CFG->wwwroot .'/user/policy.php');
         } else if (!empty($CFG->sitepolicyguest) and isguestuser()) {
             if ($preventredirect) {
-                throw new require_login_exception('Policy not agreed');
+                throw new moodle_exception('sitepolicynotagreed', 'error', '', $CFG->sitepolicyguest);
             }
             if ($setwantsurltome) {
                 $SESSION->wantsurl = qualified_me();

user/externallib.php

@@ -1660,4 +1660,81 @@ public static function set_user_preferences_returns() {
             )
         );
     }
+
+    /**
+     * Returns description of method parameters.
+     *
+     * @return external_function_parameters
+     * @since Moodle 3.2
+     */
+    public static function agree_site_policy_parameters() {
+        return new external_function_parameters(array());
+    }
+
+    /**
+     * Agree the site policy for the current user.
+     *
+     * @return array of warnings and status result
+     * @since Moodle 3.2
+     * @throws moodle_exception
+     */
+    public static function agree_site_policy() {
+        global $CFG, $DB, $USER;
+
+        $warnings = array();
+
+        $context = context_system::instance();
+        try {
+            // We expect an exception here since the user didn't agree the site policy yet.
+            self::validate_context($context);
+        } catch (Exception $e) {
+            // We are expecting only a sitepolicynotagreed exception.
+            if (!($e instanceof moodle_exception) or $e->errorcode != 'sitepolicynotagreed') {
+                // In case we receive a different exception, throw it.
+                throw $e;
+            }
+        }
+
+        if (empty($CFG->sitepolicy)) {
+            $status = false;
+            $warnings[] = array(
+                'item' => 'user',
+                'itemid' => $USER->id,
+                'warningcode' => 'nositepolicy',
+                'message' => 'The site does not have a site policy configured.'
+            );
+        } else if (!empty($USER->policyagreed)) {
+            $status = false;
+            $warnings[] = array(
+                'item' => 'user',
+                'itemid' => $USER->id,
+                'warningcode' => 'alreadyagreed',
+                'message' => 'The user already agreed the site policy.'
+            );
+        } else {
+            $DB->set_field('user', 'policyagreed', 1, array('id' => $USER->id));
+            $USER->policyagreed = 1;
+            $status = true;
+        }
+
+        $result = array();
+        $result['status'] = $status;
+        $result['warnings'] = $warnings;
+        return $result;
+    }
+
+    /**
+     * Returns description of method result value.
+     *
+     * @return external_description
+     * @since Moodle 3.2
+     */
+    public static function agree_site_policy_returns() {
+        return new external_single_structure(
+            array(
+                'status' => new external_value(PARAM_BOOL, 'Status: true only if we set the policyagreed to 1 for the user'),
+                'warnings' => new external_warnings()
+            )
+        );
+    }
 }

user/tests/externallib_test.php

@@ -1025,4 +1025,49 @@ public function test_set_user_preferences_other_user_not_being_admin() {
         $this->expectException('required_capability_exception');
         $result = core_user_external::set_user_preferences($preferences);
     }
+
+    /**
+     * Test agree_site_policy
+     */
+    public function test_agree_site_policy() {
+        global $CFG, $DB, $USER;
+        $this->resetAfterTest(true);
+
+        $user = self::getDataGenerator()->create_user();
+        $this->setUser($user);
+
+        // Site policy not set.
+        $result = core_user_external::agree_site_policy();
+        $result = external_api::clean_returnvalue(core_user_external::agree_site_policy_returns(), $result);
+        $this->assertFalse($result['status']);
+        $this->assertCount(1, $result['warnings']);
+        $this->assertEquals('nositepolicy', $result['warnings'][0]['warningcode']);
+
+        // Set a policy issue.
+        $CFG->sitepolicy = 'https://moodle.org';
+        $this->assertEquals(0, $USER->policyagreed);
+
+        $result = core_user_external::agree_site_policy();
+        $result = external_api::clean_returnvalue(core_user_external::agree_site_policy_returns(), $result);
+        $this->assertTrue($result['status']);
+        $this->assertCount(0, $result['warnings']);
+        $this->assertEquals(1, $USER->policyagreed);
+        $this->assertEquals(1, $DB->get_field('user', 'policyagreed', array('id' => $USER->id)));
+
+        // Try again, we should get a warning.
+        $result = core_user_external::agree_site_policy();
+        $result = external_api::clean_returnvalue(core_user_external::agree_site_policy_returns(), $result);
+        $this->assertFalse($result['status']);
+        $this->assertCount(1, $result['warnings']);
+        $this->assertEquals('alreadyagreed', $result['warnings'][0]['warningcode']);
+
+        // Set something to make require_login throws an exception.
+        $otheruser = self::getDataGenerator()->create_user();
+        $this->setUser($otheruser);
+
+        $DB->set_field('user', 'lastname', '', array('id' => $USER->id));
+        $USER->lastname = '';
+        $this->expectException('require_login_exception');
+        $result = core_user_external::agree_site_policy();
+    }
 }

version.php

@@ -29,7 +29,7 @@
 
 defined('MOODLE_INTERNAL') || die();
 
-$version  = 2016100400.00;              // YYYYMMDD      = weekly release date of this DEV branch.
+$version  = 2016100400.01;              // YYYYMMDD      = weekly release date of this DEV branch.
                                         //         RR    = release increments - 00 in DEV branches.
                                         //           .XX = incremental changes.