30a31,33
> require_once($CFG->dirroot . '/enrol/externallib.php');
> require_once($CFG->libdir . '/grade/grade_item.php');
> require_once($CFG->libdir . '/grade/grade_grade.php');
146a150,338
>      * Describes the parameters for get_course_users_grade.
>      *
>      * @return external_external_function_parameters
>      * @since Moodle 3.2
>      */
>     public static function get_course_users_grade_parameters() {
>         return new external_function_parameters (
>             array(
>                 'courseid'      => new external_value(PARAM_INT, 'Get grades for this course (required)', VALUE_REQUIRED, 0),
>                 'userid'        => new external_value(PARAM_INT, 'Return grade only for this user (optional)', VALUE_DEFAULT, 0),
>                 'gradeformat'   => new external_value(PARAM_RAW, 'The desired format for the grade (optional)', VALUE_DEFAULT, 0),
>                 'localized'     => new external_value(PARAM_RAW, 'Use localized decimals separator (optional)', VALUE_DEFAULT, 0),
>                 'decimals'      => new external_value(PARAM_RAW, 'Number of floating points after the decimal (optional)', VALUE_DEFAULT, 0),
>             )
>         );
>     }
> 
>     /**
>      * Get the given user courses final grades
>      *
>      * @param int $courseid get grades for users in this course (required)
>      * @param int $userid get grade for user in this course (optional)
>      * @param const $gradeformat returns grades in specified format (default: GRADE_DISPLAY_TYPE_REAL)
>      * @param bool $localized use localized decimal separator
>      * @param int $decimals The number of decimal places
>      *
>      * Available grade formats:
>      * GRADE_DISPLAY_TYPE_REAL
>      * GRADE_DISPLAY_TYPE_PERCENTAGE
>      * GRADE_DISPLAY_TYPE_LETTER
>      * GRADE_DISPLAY_TYPE_REAL_PERCENTAGE
>      * GRADE_DISPLAY_TYPE_REAL_LETTER
>      * GRADE_DISPLAY_TYPE_PERCENTAGE_REAL
>      * GRADE_DISPLAY_TYPE_LETTER_REAL
>      * GRADE_DISPLAY_TYPE_LETTER_PERCENTAGE
>      * GRADE_DISPLAY_TYPE_PERCENTAGE_LETTER
>      *
>      * @return array the grades tables
>      * @since Moodle 3.2
>      */
>     public static function get_course_users_grade($courseid, $userid=0, $gradeformat=GRADE_DISPLAY_TYPE_LETTER, $localized=true, $decimals=null) {
>         $warnings = [];
> 
>         // Validate the parameter.
>         $params = self::validate_parameters(self::get_course_users_grade_parameters(),
>             array(
>                 'courseid'      => $courseid,
>                 'userid'        => $userid,
>                 'gradeformat'   => $gradeformat,
>             )
>         );
>         $courseid = $params['courseid'];
> 
>         $systemcontext = context_system::instance();
>         self::validate_context($systemcontext);
> 
>         $userids = [];
>         // We need the site course, and course context.
>         $course = get_course($courseid);
>         $context = context_course::instance($course->id);
> 
>         if ($userid == 0) {
>             $foptions[] = [
>                'name'   => 'userfields',
>                'value'  => 'id,idnumber,firstname,lastname,email',
>             ];
> 
>             $users = core_enrol_external::get_enrolled_users($courseid, $foptions);
> 
>             foreach ($users as $user) {
>                 if (!empty($user['idnumber'])) {
>                     $userids[] = $user['id'];
>                 }
>             }
>         }
>         else {
>             $userids[] = $userid;
>             // todo Need to populate $users for a single userid. 
>             // Not sure which function will accept a single userid and return the same data as get_enrolled_users?
>         }
> 
>         // Force a regrade if required.
>         grade_regrade_final_grades_if_required($course);
> 
>         $coursegradeitem = grade_item::fetch_course_item($course->id);
>         $usergradegrade = grade_grade::fetch_users_grades($coursegradeitem, $userids);
>         $graderesultarray = [];
> 
>         foreach($usergradegrade as $gradeuserid => $gradegrade) {
>             $usergrade = [];
>             $usergrade['userid'] = $gradeuserid;
>             foreach ($users as $user) {
>                 if ($usergrade['userid'] == $user['id']) {
>                     $usergrade['idnumber']      = $user['idnumber'];
>                     $usergrade['fullname']      = $user['fullname'];
>                     $usergrade['email']         = $user['email'];
>                 }
>                 else {
>                     continue;
>                 }
>             }
>             $usergrade['finalgrade'] = $gradegrade->finalgrade;
>             $usergrade['grademax'] = $gradegrade->rawgrademax;
>             if (is_null($displaytype)) {
>                 $displaytype = $coursegradeitem->get_displaytype();
>             }
>             if (is_null($decimals)) {
>                 $decimals = $coursegradeitem->get_decimals();
>             }
> 
>             $value = (float) $gradegrade->finalgrade;
>             switch ($gradeformat) {
>                 case GRADE_DISPLAY_TYPE_REAL:
>                     $usergrade['gradeformatted'] = grade_format_gradevalue_real($value, $coursegradeitem, $decimals, $localized);
>                 break;
>                 case GRADE_DISPLAY_TYPE_PERCENTAGE:
>                     $usergrade['gradeformatted'] = grade_format_gradevalue_percentage($value, $coursegradeitem, $decimals, $localized);
>                 break;
>                 case GRADE_DISPLAY_TYPE_LETTER:
>                     $usergrade['gradeformatted'] = grade_format_gradevalue_letter($value, $coursegradeitem);
>                 break;
>                 case GRADE_DISPLAY_TYPE_REAL_PERCENTAGE:
>                     $usergrade['gradeformatted'] = grade_format_gradevalue_real($value, $coursegradeitem, $decimals, $localized)
>                                                  . ' (' . grade_format_gradevalue_percentage($value, $coursegradeitem, $decimals, $localized) . ')';
>                 break;
>                 case GRADE_DISPLAY_TYPE_REAL_LETTER:
>                     $usergrade['gradeformatted'] = grade_format_gradevalue_real($value, $coursegradeitem, $decimals, $localized)
>                                                  . ' (' . grade_format_gradevalue_letter($value, $coursegradeitem) . ')';
>                 break;
>                 case GRADE_DISPLAY_TYPE_PERCENTAGE_REAL:
>                     $usergrade['gradeformatted'] = grade_format_gradevalue_percentage($value, $coursegradeitem, $decimals, $localized)
>                                                  . ' (' . grade_format_gradevalue_real($value, $coursegradeitem, $decimals, $localized) . ')';
>                 break;
>                 case GRADE_DISPLAY_TYPE_LETTER_REAL:
>                     $usergrade['gradeformatted'] = grade_format_gradevalue_letter($value, $coursegradeitem)
>                                                  . ' (' .  grade_format_gradevalue_real($value, $coursegradeitem, $decimals, $localized) . ')';
>                 break;
>                 case GRADE_DISPLAY_TYPE_LETTER_PERCENTAGE:
>                     $usergrade['gradeformatted'] = grade_format_gradevalue_letter($value, $coursegradeitem)
>                                                  . ' (' . grade_format_gradevalue_percentage($value, $coursegradeitem, $decimals, $localized) . ')';
>                 break;
>                 case GRADE_DISPLAY_TYPE_PERCENTAGE_LETTER:
>                     $usergrade['gradeformatted'] = grade_format_gradevalue_percentage($value, $coursegradeitem, $decimals, $localized)
>                                                  . ' (' . grade_format_gradevalue_letter($value, $coursegradeitem) . ')';
>                 break;
>                 default:
>                     $usergrade['gradeformatted'] = '';
>                 break;
>             }
> 
>             $graderesultarray[] = $usergrade;
>         }
> 
>         $result = array();
>         $result['grades'] = $graderesultarray;
>         $result['warnings'] = array();
>         return $result;
>     }
> 
>     /**
>      * Describes the get_course_users_grade return value.
>      *
>      * @return external_single_structure
>      * @since Moodle 3.2
>      */
>     public static function get_course_users_grade_returns() {
>         return new external_single_structure(
>             array(
>                 'grades' => new external_multiple_structure(
>                     new external_single_structure(
>                         array(
>                             'id'            => new external_value(PARAM_INT, 'User ID', VALUE_OPTIONAL),
>                             'fullname'      => new external_value(PARAM_RAW, 'Full Name', VALUE_OPTIONAL),
>                             'email'         => new external_value(PARAM_RAW, 'Email', VALUE_OPTIONAL),
>                             'userid'        => new external_value(PARAM_RAW, 'ID Number', VALUE_OPTIONAL),
>                             'idnumber'      => new external_value(PARAM_RAW, 'ID Number', VALUE_OPTIONAL),
>                             'courseid'      => new external_value(PARAM_RAW, 'Course ID', VALUE_OPTIONAL),
>                             'finalgrade'    => new external_value(PARAM_RAW, 'raw final grade', VALUE_OPTIONAL),
>                             'grademax'      => new external_value(PARAM_RAW, 'max final grade', VALUE_OPTIONAL),
>                             'gradeformatted'=> new external_value(PARAM_RAW, 'Grade formatted', VALUE_OPTIONAL),
>                         )
>                     )
>                 ),
>                 'warnings' => new external_warnings()
>             )
>         );
>     }
> 
>     /**
