MDL-54854 grade: New WS gradereport_overview_get_course_grades

grade/report/overview/classes/external.php

@@ -0,0 +1,145 @@
+<?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/>.
+
+/**
+ * External grade report overview API
+ *
+ * @package    gradereport_overview
+ * @copyright  2016 Juan Leyva <juan@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+defined('MOODLE_INTERNAL') || die;
+
+require_once($CFG->libdir . '/externallib.php');
+require_once($CFG->libdir . '/gradelib.php');
+require_once($CFG->dirroot . '/grade/lib.php');
+require_once($CFG->dirroot . '/grade/report/overview/lib.php');
+
+/**
+ * External grade overview report API implementation
+ *
+ * @package    gradereport_overview
+ * @copyright  2016 Juan Leyva <juan@moodle.com>
+ * @category   external
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class gradereport_overview_external extends external_api {
+
+    /**
+     * Describes the parameters for get_course_grades.
+     *
+     * @return external_external_function_parameters
+     * @since Moodle 3.2
+     */
+    public static function get_course_grades_parameters() {
+        return new external_function_parameters (
+            array(
+                'userid' => new external_value(PARAM_INT, 'Get grades for this user (optional, default current)', VALUE_DEFAULT, 0)
+            )
+        );
+    }
+
+    /**
+     * Get the given user courses final grades
+     *
+     * @param int $userid get grades for this user (optional, default current)
+     *
+     * @return array the grades tables
+     * @since Moodle 3.2
+     */
+    public static function get_course_grades($userid = 0) {
+        global $USER;
+
+        $warnings = array();
+
+        // Validate the parameter.
+        $params = self::validate_parameters(self::get_course_grades_parameters(),
+            array(
+                'userid' => $userid
+            )
+        );
+
+        $userid = $params['userid'];
+        if (empty($userid)) {
+            $userid = $USER->id;
+        }
+
+        $systemcontext = context_system::instance();
+        self::validate_context($systemcontext);
+
+        if ($USER->id != $userid) {
+            // We must check if the current user can view other users grades.
+            $user = core_user::get_user($userid, '*', MUST_EXIST);
+            core_user::require_active_user($user);
+            require_capability('moodle/grade:viewall', $systemcontext);
+        }
+
+        // We need the site course, and course context.
+        $course = get_course(SITEID);
+        $context = context_course::instance($course->id);
+
+        // Force a regrade if required.
+        grade_regrade_final_grades_if_required($course);
+        // Get the course final grades now.
+        $gpr = new grade_plugin_return(array('type' => 'report', 'plugin' => 'overview', 'courseid' => $course->id,
+                                        'userid' => $userid));
+        $report = new grade_report_overview($userid, $gpr, $context);
+        $coursesgrades = $report->setup_courses_data(true);
+
+        $grades = array();
+        foreach ($coursesgrades as $coursegrade) {
+            $gradeinfo = array(
+                'courseid' => $coursegrade['course']->id,
+                'grade' => grade_format_gradevalue($coursegrade['finalgrade'], $coursegrade['courseitem'], true),
+                'rawgrade' => $coursegrade['finalgrade'],
+            );
+            if (isset($coursegrade['rank'])) {
+                $gradeinfo['rank'] = $coursegrade['rank'];
+            }
+            $grades[] = $gradeinfo;
+        }
+
+        $result = array();
+        $result['grades'] = $grades;
+        $result['warnings'] = $warnings;
+        return $result;
+    }
+
+    /**
+     * Describes the get_course_grades return value.
+     *
+     * @return external_single_structure
+     * @since Moodle 3.2
+     */
+    public static function get_course_grades_returns() {
+        return new external_single_structure(
+            array(
+                'grades' => new external_multiple_structure(
+                    new external_single_structure(
+                        array(
+                            'courseid' => new external_value(PARAM_INT, 'Course id'),
+                            'grade' => new external_value(PARAM_RAW, 'Grade formatted'),
+                            'rawgrade' => new external_value(PARAM_RAW, 'Raw grade, not formatted'),
+                            'rank' => new external_value(PARAM_INT, 'Your rank in the course', VALUE_OPTIONAL),
+                        )
+                    )
+                ),
+                'warnings' => new external_warnings()
+            )
+        );
+    }
+}

grade/report/overview/db/services.php

@@ -0,0 +1,36 @@
+<?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/>.
+
+/**
+ * Overview grade report external functions and service definitions.
+ *
+ * @package    gradereport_overview
+ * @copyright  2016 Juan Leyva <juan@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+defined('MOODLE_INTERNAL') || die();
+
+$functions = array(
+
+    'gradereport_overview_get_course_grades' => array(
+        'classname' => 'gradereport_overview_external',
+        'methodname' => 'get_course_grades',
+        'description' => 'Get the given user courses final grades',
+        'type' => 'read',
+        'services' => array(MOODLE_OFFICIAL_MOBILE_SERVICE),
+    )
+);

grade/report/overview/tests/externallib_test.php

@@ -0,0 +1,187 @@
+<?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/>.
+
+/**
+ * Overview grade report functions unit tests
+ *
+ * @package    gradereport_overview
+ * @category   external
+ * @copyright  2015 Juan Leyva <juan@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+defined('MOODLE_INTERNAL') || die();
+
+global $CFG;
+
+require_once($CFG->dirroot . '/webservice/tests/helpers.php');
+
+/**
+ * Overview grade report functions unit tests
+ *
+ * @package    gradereport_overview
+ * @category   external
+ * @copyright  2015 Juan Leyva <juan@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class gradereport_overview_externallib_testcase extends externallib_advanced_testcase {
+
+    /**
+     * Set up for every test
+     */
+    public function setUp() {
+        global $DB;
+        $this->resetAfterTest(true);
+
+        $s1grade1 = 80;
+        $s1grade2 = 40;
+        $s2grade = 60;
+
+        $this->course1 = $this->getDataGenerator()->create_course();
+        $this->course2 = $this->getDataGenerator()->create_course();
+
+        $studentrole = $DB->get_record('role', array('shortname' => 'student'));
+        $teacherrole = $DB->get_record('role', array('shortname' => 'editingteacher'));
+        $this->student1 = $this->getDataGenerator()->create_user();
+        $this->teacher = $this->getDataGenerator()->create_user();
+        $this->getDataGenerator()->enrol_user($this->teacher->id, $this->course1->id, $teacherrole->id);
+        $this->getDataGenerator()->enrol_user($this->student1->id, $this->course1->id, $studentrole->id);
+        $this->getDataGenerator()->enrol_user($this->student1->id, $this->course2->id, $studentrole->id);
+
+        $this->student2 = $this->getDataGenerator()->create_user();
+        $this->getDataGenerator()->enrol_user($this->student2->id, $this->course1->id, $studentrole->id);
+        $this->getDataGenerator()->enrol_user($this->student2->id, $this->course2->id, $studentrole->id);
+
+        $assignment1 = $this->getDataGenerator()->create_module('assign', array('name' => "Test assign", 'course' => $this->course1->id));
+        $assignment2 = $this->getDataGenerator()->create_module('assign', array('name' => "Test assign", 'course' => $this->course2->id));
+        $modcontext1 = get_coursemodule_from_instance('assign', $assignment1->id, $this->course1->id);
+        $modcontext2 = get_coursemodule_from_instance('assign', $assignment2->id, $this->course2->id);
+        $assignment1->cmidnumber = $modcontext1->id;
+        $assignment2->cmidnumber = $modcontext2->id;
+
+        $this->student1grade1 = array('userid' => $this->student1->id, 'rawgrade' => $s1grade1);
+        $this->student1grade2 = array('userid' => $this->student1->id, 'rawgrade' => $s1grade2);
+        $this->student2grade = array('userid' => $this->student2->id, 'rawgrade' => $s2grade);
+        $studentgrades = array($this->student1->id => $this->student1grade1, $this->student2->id => $this->student2grade);
+        assign_grade_item_update($assignment1, $studentgrades);
+        $studentgrades = array($this->student1->id => $this->student1grade2);
+        assign_grade_item_update($assignment2, $studentgrades);
+
+        grade_get_setting($this->course1->id, 'report_overview_showrank', 1);
+    }
+
+    /**
+     * Test get_course_grades function case student
+     */
+    public function test_get_course_grades_student() {
+
+        // A user can see his own grades in both courses.
+        $this->setUser($this->student1);
+        $studentgrades = gradereport_overview_external::get_course_grades();
+        $studentgrades = external_api::clean_returnvalue(gradereport_overview_external::get_course_grades_returns(), $studentgrades);
+
+        $this->assertCount(0, $studentgrades['warnings']);
+        $this->assertCount(2, $studentgrades['grades']);
+        foreach ($studentgrades['grades'] as $grade) {
+            if ($grade['courseid'] == $this->course1->id) {
+                $this->assertEquals(80.00, $grade['grade']);
+                $this->assertEquals(80.0000, $grade['rawgrade']);
+                $this->assertEquals(1, $grade['rank']);
+            } else {
+                $this->assertEquals(40.00, $grade['grade']);
+                $this->assertEquals(40.0000, $grade['rawgrade']);
+                $this->assertArrayNotHasKey('rank', $grade);
+            }
+        }
+
+        // Second student, no grade in one course.
+        $this->setUser($this->student2);
+        $studentgrades = gradereport_overview_external::get_course_grades();
+        $studentgrades = external_api::clean_returnvalue(gradereport_overview_external::get_course_grades_returns(), $studentgrades);
+
+        $this->assertCount(0, $studentgrades['warnings']);
+        $this->assertCount(2, $studentgrades['grades']);
+        foreach ($studentgrades['grades'] as $grade) {
+            if ($grade['courseid'] == $this->course1->id) {
+                $this->assertEquals(60.00, $grade['grade']);
+                $this->assertEquals(60.0000, $grade['rawgrade']);
+                $this->assertEquals(2, $grade['rank']);
+            } else {
+                $this->assertEquals('-', $grade['grade']);
+                $this->assertEmpty($grade['rawgrade']);
+                $this->assertArrayNotHasKey('rank', $grade);
+            }
+        }
+    }
+
+    /**
+     * Test get_course_grades function case admin
+     */
+    public function test_get_course_grades_admin() {
+
+        // A admin must see all student grades.
+        $this->setAdminUser();
+
+        $studentgrades = gradereport_overview_external::get_course_grades($this->student1->id);
+        $studentgrades = external_api::clean_returnvalue(gradereport_overview_external::get_course_grades_returns(), $studentgrades);
+        $this->assertCount(0, $studentgrades['warnings']);
+        $this->assertCount(2, $studentgrades['grades']);
+        foreach ($studentgrades['grades'] as $grade) {
+            if ($grade['courseid'] == $this->course1->id) {
+                $this->assertEquals(80.00, $grade['grade']);
+                $this->assertEquals(80.0000, $grade['rawgrade']);
+            } else {
+                $this->assertEquals(40.00, $grade['grade']);
+                $this->assertEquals(40.0000, $grade['rawgrade']);
+            }
+        }
+
+        $studentgrades = gradereport_overview_external::get_course_grades($this->student2->id);
+        $studentgrades = external_api::clean_returnvalue(gradereport_overview_external::get_course_grades_returns(), $studentgrades);
+        $this->assertCount(0, $studentgrades['warnings']);
+        $this->assertCount(2, $studentgrades['grades']);
+
+        // Admins don't see grades.
+        $studentgrades = gradereport_overview_external::get_course_grades();
+        $studentgrades = external_api::clean_returnvalue(gradereport_overview_external::get_course_grades_returns(), $studentgrades);
+        $this->assertCount(0, $studentgrades['warnings']);
+        $this->assertCount(0, $studentgrades['grades']);
+    }
+
+    /**
+     * Test get_course_grades function case teacher
+     */
+    public function test_get_course_grades_teacher() {
+        // Teachers don't see grades.
+        $this->setUser($this->teacher);
+
+        $studentgrades = gradereport_overview_external::get_course_grades();
+        $studentgrades = external_api::clean_returnvalue(gradereport_overview_external::get_course_grades_returns(), $studentgrades);
+        $this->assertCount(0, $studentgrades['warnings']);
+        $this->assertCount(0, $studentgrades['grades']);
+    }
+
+    /**
+     * Test get_course_grades function case incorrect permissions
+     */
+    public function test_get_course_grades_permissions() {
+        // Student can't see other student grades.
+        $this->setUser($this->student2);
+
+        $this->expectException('required_capability_exception');
+        $studentgrade = gradereport_overview_external::get_course_grades($this->student1->id);
+    }
+}

grade/report/overview/version.php

@@ -24,6 +24,6 @@
 
 defined('MOODLE_INTERNAL') || die();
 
-$plugin->version   = 2016052300;        // The current plugin version (Date: YYYYMMDDXX)
+$plugin->version   = 2016052301;        // The current plugin version (Date: YYYYMMDDXX)
 $plugin->requires  = 2016051900;        // Requires this Moodle version
 $plugin->component = 'gradereport_overview'; // Full name of the plugin (used for diagnostics)