MDL-57665 mod_lesson: New WS mod_lesson_get_user_timers

diff --git a/mod/lesson/classes/external.php b/mod/lesson/classes/external.php
index 05f4ca1..7810f88 100644 (file)
--- a/mod/lesson/classes/external.php
+++ b/mod/lesson/classes/external.php
@@ -832,4 +832,85 @@ class mod_lesson_external extends external_api {
             )
         );
     }
+
+    /**
+     * Describes the parameters for get_user_timers.
+     *
+     * @return external_external_function_parameters
+     * @since Moodle 3.3
+     */
+    public static function get_user_timers_parameters() {
+        return new external_function_parameters (
+            array(
+                'lessonid' => new external_value(PARAM_INT, 'lesson instance id'),
+                'userid' => new external_value(PARAM_INT, 'the user id (empty for current user)', VALUE_DEFAULT, null),
+            )
+        );
+    }
+
+    /**
+     * Return the timers in the current lesson for the given user.
+     *
+     * @param int $lessonid lesson instance id
+     * @param int $userid only fetch timers of the given user
+     * @return array of warnings and timers
+     * @since Moodle 3.3
+     * @throws moodle_exception
+     */
+    public static function get_user_timers($lessonid, $userid = null) {
+        global $USER;
+
+        $params = array(
+            'lessonid' => $lessonid,
+            'userid' => $userid,
+        );
+        $params = self::validate_parameters(self::get_user_timers_parameters(), $params);
+        $warnings = array();
+
+        list($lesson, $course, $cm, $context) = self::validate_lesson($params['lessonid']);
+
+        // Default value for userid.
+        if (empty($params['userid'])) {
+            $params['userid'] = $USER->id;
+        }
+
+        // Extra checks so only users with permissions can view other users attempts.
+        if ($USER->id != $params['userid']) {
+            self::check_can_view_user_data($params['userid'], $course, $cm, $context);
+        }
+
+        $timers = $lesson->get_user_timers($params['userid']);
+
+        $result = array();
+        $result['timers'] = $timers;
+        $result['warnings'] = $warnings;
+        return $result;
+    }
+
+    /**
+     * Describes the get_user_timers return value.
+     *
+     * @return external_single_structure
+     * @since Moodle 3.3
+     */
+    public static function get_user_timers_returns() {
+        return new external_single_structure(
+            array(
+                'timers' => new external_multiple_structure(
+                    new external_single_structure(
+                        array(
+                            'id' => new external_value(PARAM_INT, 'The attempt id'),
+                            'lessonid' => new external_value(PARAM_INT, 'The lesson id'),
+                            'userid' => new external_value(PARAM_INT, 'The user id'),
+                            'starttime' => new external_value(PARAM_INT, 'First access time for a new timer session'),
+                            'lessontime' => new external_value(PARAM_INT, 'Last access time to the lesson during the timer session'),
+                            'completed' => new external_value(PARAM_INT, 'If the lesson for this timer was completed'),
+                        ),
+                        'The timers'
+                    )
+                ),
+                'warnings' => new external_warnings(),
+            )
+        );
+    }
 }

diff --git a/mod/lesson/db/services.php b/mod/lesson/db/services.php
index b6bc6aa..e9e0b7c 100644 (file)
--- a/mod/lesson/db/services.php
+++ b/mod/lesson/db/services.php
@@ -84,4 +84,12 @@ $functions = array(
         'capabilities'  => 'mod/lesson:view',
         'services'      => array(MOODLE_OFFICIAL_MOBILE_SERVICE)
     ),
+    'mod_lesson_get_user_timers' => array(
+        'classname'     => 'mod_lesson_external',
+        'methodname'    => 'get_user_timers',
+        'description'   => 'Return the timers in the current lesson for the given user.',
+        'type'          => 'read',
+        'capabilities'  => 'mod/lesson:view',
+        'services'      => array(MOODLE_OFFICIAL_MOBILE_SERVICE)
+    ),
 );

diff --git a/mod/lesson/tests/external_test.php b/mod/lesson/tests/external_test.php
index 5168a57..ac6d564 100644 (file)
--- a/mod/lesson/tests/external_test.php
+++ b/mod/lesson/tests/external_test.php
@@ -629,4 +629,41 @@ class mod_lesson_external_testcase extends externallib_advanced_testcase {
         $this->assertCount(0, $result['warnings']);
         $this->assertCount(0, $result['pages']);
     }
+
+    /**
+     * Test get_user_timers
+     */
+    public function test_get_user_timers() {
+        global $DB;
+
+        // Create a couple of timers for the current user.
+        $timer1 = new stdClass;
+        $timer1->lessonid = $this->lesson->id;
+        $timer1->userid = $this->student->id;
+        $timer1->completed = 1;
+        $timer1->starttime = time() - WEEKSECS;
+        $timer1->lessontime = time();
+        $timer1->id = $DB->insert_record("lesson_timer", $timer1);
+
+        $timer2 = new stdClass;
+        $timer2->lessonid = $this->lesson->id;
+        $timer2->userid = $this->student->id;
+        $timer2->completed = 0;
+        $timer2->starttime = time() - DAYSECS;
+        $timer2->lessontime = time() + 1;
+        $timer2->id = $DB->insert_record("lesson_timer", $timer2);
+
+        // Test retrieve timers.
+        $result = mod_lesson_external::get_user_timers($this->lesson->id, $this->student->id);
+        $result = external_api::clean_returnvalue(mod_lesson_external::get_user_timers_returns(), $result);
+        $this->assertCount(0, $result['warnings']);
+        $this->assertCount(2, $result['timers']);
+        foreach ($result['timers'] as $timer) {
+            if ($timer['id'] == $timer1->id) {
+                $this->assertEquals($timer1, (object) $timer);
+            } else {
+                $this->assertEquals($timer2, (object) $timer);
+            }
+        }
+    }
 }

diff --git a/mod/lesson/version.php b/mod/lesson/version.php
index 7162569..ac2a5f8 100644 (file)
--- a/mod/lesson/version.php
+++ b/mod/lesson/version.php
@@ -24,7 +24,7 @@
 
 defined('MOODLE_INTERNAL') || die();
 
-$plugin->version   = 2016120506;     // The current module version (Date: YYYYMMDDXX)
+$plugin->version   = 2016120507;     // The current module version (Date: YYYYMMDDXX)
 $plugin->requires  = 2016112900;    // Requires this Moodle version
 $plugin->component = 'mod_lesson'; // Full name of the plugin (used for diagnostics)
 $plugin->cron      = 0;