Proyectos de Subversion Moodle

<?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/>.

/**

 * Library of functions for gradebook - both public and internal

 *

 * @package   core_grades

 * @copyright 1999 onwards Martin Dougiamas  {@link http://moodle.com}

 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

defined('MOODLE_INTERNAL') || die();

global $CFG;

/** Include essential files */

require_once($CFG->libdir . '/grade/constants.php');

require_once($CFG->libdir . '/grade/grade_category.php');

require_once($CFG->libdir . '/grade/grade_item.php');

require_once($CFG->libdir . '/grade/grade_grade.php');

require_once($CFG->libdir . '/grade/grade_scale.php');

require_once($CFG->libdir . '/grade/grade_outcome.php');

/////////////////////////////////////////////////////////////////////

///// Start of public API for communication with modules/blocks /////

/////////////////////////////////////////////////////////////////////

/**

 * Submit new or update grade; update/create grade_item definition. Grade must have userid specified,

 * rawgrade and feedback with format are optional. rawgrade NULL means 'Not graded'.

 * Missing property or key means does not change the existing value.

 *

 * Only following grade item properties can be changed 'itemname', 'idnumber', 'gradetype', 'grademax',

 * 'grademin', 'scaleid', 'multfactor', 'plusfactor', 'deleted' and 'hidden'. 'reset' means delete all current grades including locked ones.

 *

 * Manual, course or category items can not be updated by this function.

 *

 * @category grade

 * @param string $source Source of the grade such as 'mod/assignment'

 * @param int    $courseid ID of course

 * @param string $itemtype Type of grade item. For example, mod or block

 * @param string $itemmodule More specific then $itemtype. For example, assignment or forum. May be NULL for some item types

 * @param int    $iteminstance Instance ID of graded item

 * @param int    $itemnumber Most probably 0. Modules can use other numbers when having more than one grade for each user

 * @param mixed  $grades Grade (object, array) or several grades (arrays of arrays or objects), NULL if updating grade_item definition only

 * @param mixed  $itemdetails Object or array describing the grading item, NULL if no change

 * @param bool   $isbulkupdate If bulk grade update is happening.

 * @return int Returns GRADE_UPDATE_OK, GRADE_UPDATE_FAILED, GRADE_UPDATE_MULTIPLE or GRADE_UPDATE_ITEM_LOCKED

 */

function grade_update($source, $courseid, $itemtype, $itemmodule, $iteminstance, $itemnumber, $grades = null,

        $itemdetails = null, $isbulkupdate = false) {

    global $USER, $CFG, $DB;

    // only following grade_item properties can be changed in this function

    $allowed = array('itemname', 'idnumber', 'gradetype', 'grademax', 'grademin', 'scaleid', 'multfactor', 'plusfactor', 'deleted', 'hidden');

    // list of 10,5 numeric fields

    $floats  = array('grademin', 'grademax', 'multfactor', 'plusfactor');

    // grade item identification

    $params = compact('courseid', 'itemtype', 'itemmodule', 'iteminstance', 'itemnumber');

    if (is_null($courseid) or is_null($itemtype)) {

        debugging('Missing courseid or itemtype');

        return GRADE_UPDATE_FAILED;

    }

    if (!$gradeitems = grade_item::fetch_all($params)) {

        // create a new one

        $gradeitem = false;

    } else if (count($gradeitems) == 1) {

        $gradeitem = reset($gradeitems);

        unset($gradeitems); // Release memory.

    } else {

        debugging('Found more than one grade item');

        return GRADE_UPDATE_MULTIPLE;

    }

    if (!empty($itemdetails['deleted'])) {

        if ($gradeitem) {

            if ($gradeitem->delete($source)) {

                return GRADE_UPDATE_OK;

            } else {

                return GRADE_UPDATE_FAILED;

            }

        }

        return GRADE_UPDATE_OK;

    }

/// Create or update the grade_item if needed

    if (!$gradeitem) {

        if ($itemdetails) {

            $itemdetails = (array)$itemdetails;

            // grademin and grademax ignored when scale specified

            if (array_key_exists('scaleid', $itemdetails)) {

                if ($itemdetails['scaleid']) {

                    unset($itemdetails['grademin']);

                    unset($itemdetails['grademax']);

                }

            }

            foreach ($itemdetails as $k=>$v) {

                if (!in_array($k, $allowed)) {

                    // ignore it

                    continue;

                }

                if ($k == 'gradetype' and $v == GRADE_TYPE_NONE) {

                    // no grade item needed!

                    return GRADE_UPDATE_OK;

                }

                $params[$k] = $v;

            }

        }

        $gradeitem = new grade_item($params);

        $gradeitem->insert(null, $isbulkupdate);

    } else {

        if ($gradeitem->is_locked()) {

            // no notice() here, test returned value instead!

            return GRADE_UPDATE_ITEM_LOCKED;

        }

        if ($itemdetails) {

            $itemdetails = (array)$itemdetails;

            $update = false;

            foreach ($itemdetails as $k=>$v) {

                if (!in_array($k, $allowed)) {

                    // ignore it

                    continue;

                }

                if (in_array($k, $floats)) {

                    if (grade_floats_different($gradeitem->{$k}, $v)) {

                        $gradeitem->{$k} = $v;

                        $update = true;

                    }

                } else {

                    if ($gradeitem->{$k} != $v) {

                        $gradeitem->{$k} = $v;

                        $update = true;

                    }

                }

            }

            if ($update) {

                $gradeitem->update(null, $isbulkupdate);

            }

        }

    }

/// reset grades if requested

    if (!empty($itemdetails['reset'])) {

        $gradeitem->delete_all_grades('reset');

        return GRADE_UPDATE_OK;

    }

/// Some extra checks

    // do we use grading?

    if ($gradeitem->gradetype == GRADE_TYPE_NONE) {

        return GRADE_UPDATE_OK;

    }

    // no grade submitted

    if (empty($grades)) {

        return GRADE_UPDATE_OK;

    }

/// Finally start processing of grades

    if (is_object($grades)) {

        $grades = array($grades->userid=>$grades);

    } else {

        if (array_key_exists('userid', $grades)) {

            $grades = array($grades['userid']=>$grades);

        }

    }

/// normalize and verify grade array

    foreach($grades as $k=>$g) {

        if (!is_array($g)) {

            $g = (array)$g;

            $grades[$k] = $g;

        }

        if (empty($g['userid']) or $k != $g['userid']) {

            debugging('Incorrect grade array index, must be user id! Grade ignored.');

            unset($grades[$k]);

        }

    }

    if (empty($grades)) {

        return GRADE_UPDATE_FAILED;

    }

    $count = count($grades);

    if ($count > 0 and $count < 200) {

        list($uids, $params) = $DB->get_in_or_equal(array_keys($grades), SQL_PARAMS_NAMED, $start='uid');

        $params['gid'] = $gradeitem->id;

        $sql = "SELECT * FROM {grade_grades} WHERE itemid = :gid AND userid $uids";

    } else {

        $sql = "SELECT * FROM {grade_grades} WHERE itemid = :gid";

        $params = array('gid' => $gradeitem->id);

    }

    $rs = $DB->get_recordset_sql($sql, $params);

    $failed = false;

    while (count($grades) > 0) {

        $gradegrade = null;

        $grade       = null;

        foreach ($rs as $gd) {

            $userid = $gd->userid;

            if (!isset($grades[$userid])) {

                // this grade not requested, continue

                continue;

            }

            // existing grade requested

            $grade       = $grades[$userid];

            $gradegrade = new grade_grade($gd, false);

            unset($grades[$userid]);

            break;

        }

        if (is_null($gradegrade)) {

            if (count($grades) == 0) {

                // No more grades to process.

                break;

            }

            $grade       = reset($grades);

            $userid      = $grade['userid'];

            $gradegrade = new grade_grade(array('itemid' => $gradeitem->id, 'userid' => $userid), false);

            $gradegrade->load_optional_fields(); // add feedback and info too

            unset($grades[$userid]);

        }

        $rawgrade       = false;

        $feedback       = false;

        $feedbackformat = FORMAT_MOODLE;

        $feedbackfiles = [];

        $usermodified   = $USER->id;

        $datesubmitted  = null;

        $dategraded     = null;

        if (array_key_exists('rawgrade', $grade)) {

            $rawgrade = $grade['rawgrade'];

        }

        if (array_key_exists('feedback', $grade)) {

            $feedback = $grade['feedback'];

        }

        if (array_key_exists('feedbackformat', $grade)) {

            $feedbackformat = $grade['feedbackformat'];

        }

        if (array_key_exists('feedbackfiles', $grade)) {

            $feedbackfiles = $grade['feedbackfiles'];

        }

        if (array_key_exists('usermodified', $grade)) {

            $usermodified = $grade['usermodified'];

        }

        if (array_key_exists('datesubmitted', $grade)) {

            $datesubmitted = $grade['datesubmitted'];

        }

        if (array_key_exists('dategraded', $grade)) {

            $dategraded = $grade['dategraded'];

        }

        // update or insert the grade

        if (!$gradeitem->update_raw_grade($userid, $rawgrade, $source, $feedback, $feedbackformat, $usermodified,

                $dategraded, $datesubmitted, $gradegrade, $feedbackfiles, $isbulkupdate)) {

            $failed = true;

        }

    }

    if ($rs) {

        $rs->close();

    }

    if (!$failed) {

        return GRADE_UPDATE_OK;

    } else {

        return GRADE_UPDATE_FAILED;

    }

}

/**

 * Updates a user's outcomes. Manual outcomes can not be updated.

 *

 * @category grade

 * @param string $source Source of the grade such as 'mod/assignment'

 * @param int    $courseid ID of course

 * @param string $itemtype Type of grade item. For example, 'mod' or 'block'

 * @param string $itemmodule More specific then $itemtype. For example, 'forum' or 'quiz'. May be NULL for some item types

 * @param int    $iteminstance Instance ID of graded item. For example the forum ID.

 * @param int    $userid ID of the graded user

 * @param array  $data Array consisting of grade item itemnumber ({@link grade_update()}) => outcomegrade

 * @return bool returns true if grade items were found and updated successfully

 */

function grade_update_outcomes($source, $courseid, $itemtype, $itemmodule, $iteminstance, $userid, $data) {

    if ($items = grade_item::fetch_all(array('itemtype'=>$itemtype, 'itemmodule'=>$itemmodule, 'iteminstance'=>$iteminstance, 'courseid'=>$courseid))) {

        $result = true;

        foreach ($items as $item) {

            if (!array_key_exists($item->itemnumber, $data)) {

                continue;

            }

            $grade = $data[$item->itemnumber] < 1 ? null : $data[$item->itemnumber];

            $result = ($item->update_final_grade($userid, $grade, $source) && $result);

        }

        return $result;

    }

    return false; //grade items not found

}

/**

 * Return true if the course needs regrading.

 *

 * @param int $courseid The course ID

 * @return bool true if course grades need updating.

 */

function grade_needs_regrade_final_grades($courseid) {

    $course_item = grade_item::fetch_course_item($courseid);

    return $course_item->needsupdate;

}

/**

 * Return true if the regrade process is likely to be time consuming and

 * will therefore require the progress bar.

 *

 * @param int $courseid The course ID

 * @return bool Whether the regrade process is likely to be time consuming

 */

function grade_needs_regrade_progress_bar($courseid) {

    global $DB;

    $grade_items = grade_item::fetch_all(array('courseid' => $courseid));

    if (!$grade_items) {

        // If there are no grade items then we definitely don't need a progress bar!

        return false;

    }

    list($sql, $params) = $DB->get_in_or_equal(array_keys($grade_items), SQL_PARAMS_NAMED, 'gi');

    $gradecount = $DB->count_records_select('grade_grades', 'itemid ' . $sql, $params);

    // This figure may seem arbitrary, but after analysis it seems that 100 grade_grades can be calculated in ~= 0.5 seconds.

    // Any longer than this and we want to show the progress bar.

    return $gradecount > 100;

}

/**

 * Check whether regarding of final grades is required and, if so, perform the regrade.

 *

 * If the regrade is expected to be time consuming (see grade_needs_regrade_progress_bar), then this

 * function will output the progress bar, and redirect to the current PAGE->url after regrading

 * completes. Otherwise the regrading will happen immediately and the page will be loaded as per

 * normal.

 *

 * A callback may be specified, which is called if regrading has taken place.

 * The callback may optionally return a URL which will be redirected to when the progress bar is present.

 *

 * @param stdClass $course The course to regrade

 * @param callable $callback A function to call if regrading took place

 * @return moodle_url|false The URL to redirect to if redirecting

 */

function grade_regrade_final_grades_if_required($course, callable $callback = null) {

    global $PAGE, $OUTPUT;

    if (!grade_needs_regrade_final_grades($course->id)) {

        return false;

    }

    if (grade_needs_regrade_progress_bar($course->id)) {

        if ($PAGE->state !== moodle_page::STATE_IN_BODY) {

            $PAGE->set_heading($course->fullname);

            echo $OUTPUT->header();

        }

        echo $OUTPUT->heading(get_string('recalculatinggrades', 'grades'));

        $progress = new \core\progress\display(true);

        $status = grade_regrade_final_grades($course->id, null, null, $progress);

        // Show regrade errors and set the course to no longer needing regrade (stop endless loop).

        if (is_array($status)) {

            foreach ($status as $error) {

                $errortext = new \core\output\notification($error, \core\output\notification::NOTIFY_ERROR);

                echo $OUTPUT->render($errortext);

            }

            $courseitem = grade_item::fetch_course_item($course->id);

            $courseitem->regrading_finished();

        }

        if ($callback) {

            //

            $url = call_user_func($callback);

        }

        if (empty($url)) {

            $url = $PAGE->url;

        }

        echo $OUTPUT->continue_button($url);

        echo $OUTPUT->footer();

        die();

    } else {

        $result = grade_regrade_final_grades($course->id);

        if ($callback) {

            call_user_func($callback);

        }

        return $result;

    }

}

/**

 * Returns grading information for given activity, optionally with user grades.

 * Manual, course or category items can not be queried.

 *

 * This function can be VERY costly - it is doing full course grades recalculation if needsupdate = 1

 * for course grade item. So be sure you really need it.

 * If you need just certain grades consider using grade_item::refresh_grades()

 * together with grade_item::get_grade() instead.

 *

 * @param int    $courseid ID of course

 * @param string $itemtype Type of grade item. For example, 'mod' or 'block'

 * @param string $itemmodule More specific then $itemtype. For example, 'forum' or 'quiz'. May be NULL for some item types

 * @param int    $iteminstance ID of the item module

 * @param mixed  $userid_or_ids Either a single user ID, an array of user IDs or null. If user ID or IDs are not supplied returns information about grade_item

 * @return stdClass Object with keys {items, outcomes, errors}, where 'items' is an array of grade

 *               information objects (scaleid, name, grade and locked status, etc.) indexed with itemnumbers

 * @category grade

 */

function grade_get_grades($courseid, $itemtype, $itemmodule, $iteminstance, $userid_or_ids=null) {

    global $CFG;

    $return = new stdClass();

    $return->items    = array();

    $return->outcomes = array();

    $return->errors = [];

    $courseitem = grade_item::fetch_course_item($courseid);

    $needsupdate = array();

    if ($courseitem->needsupdate) {

        $result = grade_regrade_final_grades($courseid);

        if ($result !== true) {

            $needsupdate = array_keys($result);

            // Return regrade errors if the user has capability.

            $context = context_course::instance($courseid);

            if (has_capability('moodle/grade:edit', $context)) {

                $return->errors = $result;

            }

            $courseitem->regrading_finished();

        }

    }

    if ($grade_items = grade_item::fetch_all(array('itemtype'=>$itemtype, 'itemmodule'=>$itemmodule, 'iteminstance'=>$iteminstance, 'courseid'=>$courseid))) {

        foreach ($grade_items as $grade_item) {

            $decimalpoints = null;

            if (empty($grade_item->outcomeid)) {

                // prepare information about grade item

                $item = new stdClass();

                $item->id = $grade_item->id;

                $item->itemnumber = $grade_item->itemnumber;

                $item->itemtype  = $grade_item->itemtype;

                $item->itemmodule = $grade_item->itemmodule;

                $item->iteminstance = $grade_item->iteminstance;

                $item->scaleid    = $grade_item->scaleid;

                $item->name       = $grade_item->get_name();

                $item->grademin   = $grade_item->grademin;

                $item->grademax   = $grade_item->grademax;

                $item->gradepass  = $grade_item->gradepass;

                $item->locked     = $grade_item->is_locked();

                $item->hidden     = $grade_item->is_hidden();

                $item->grades     = array();

                switch ($grade_item->gradetype) {

                    case GRADE_TYPE_NONE:

                        break;

                    case GRADE_TYPE_VALUE:

                        $item->scaleid = 0;

                        break;

                    case GRADE_TYPE_TEXT:

                        $item->scaleid   = 0;

                        $item->grademin   = 0;

                        $item->grademax   = 0;

                        $item->gradepass  = 0;

                        break;

                }

                if (empty($userid_or_ids)) {

                    $userids = array();

                } else if (is_array($userid_or_ids)) {

                    $userids = $userid_or_ids;

                } else {

                    $userids = array($userid_or_ids);

                }

                if ($userids) {

                    $grade_grades = grade_grade::fetch_users_grades($grade_item, $userids, true);

                    foreach ($userids as $userid) {

                        $grade_grades[$userid]->grade_item =& $grade_item;

                        $grade = new stdClass();

                        $grade->grade          = $grade_grades[$userid]->finalgrade;

                        $grade->locked         = $grade_grades[$userid]->is_locked();

                        $grade->hidden         = $grade_grades[$userid]->is_hidden();

                        $grade->overridden     = $grade_grades[$userid]->overridden;

                        $grade->feedback       = $grade_grades[$userid]->feedback;

                        $grade->feedbackformat = $grade_grades[$userid]->feedbackformat;

                        $grade->usermodified   = $grade_grades[$userid]->usermodified;

                        $grade->datesubmitted  = $grade_grades[$userid]->get_datesubmitted();

                        $grade->dategraded     = $grade_grades[$userid]->get_dategraded();

                        // create text representation of grade

                        if ($grade_item->gradetype == GRADE_TYPE_TEXT or $grade_item->gradetype == GRADE_TYPE_NONE) {

                            $grade->grade          = null;

                            $grade->str_grade      = '-';

                            $grade->str_long_grade = $grade->str_grade;

                        } else if (in_array($grade_item->id, $needsupdate)) {

                            $grade->grade          = false;

                            $grade->str_grade      = get_string('error');

                            $grade->str_long_grade = $grade->str_grade;

                        } else if (is_null($grade->grade)) {

                            $grade->str_grade      = '-';

                            $grade->str_long_grade = $grade->str_grade;

                        } else {

                            $grade->str_grade = grade_format_gradevalue($grade->grade, $grade_item);

                            if ($grade_item->gradetype == GRADE_TYPE_SCALE or $grade_item->get_displaytype() != GRADE_DISPLAY_TYPE_REAL) {

                                $grade->str_long_grade = $grade->str_grade;

                            } else {

                                $a = new stdClass();

                                $a->grade = $grade->str_grade;

                                $a->max   = grade_format_gradevalue($grade_item->grademax, $grade_item);

                                $grade->str_long_grade = get_string('gradelong', 'grades', $a);

                            }

                        }

                        // create html representation of feedback

                        if (is_null($grade->feedback)) {

                            $grade->str_feedback = '';

                        } else {

                            $feedback = file_rewrite_pluginfile_urls(

                                $grade->feedback,

                                'pluginfile.php',

                                $grade_grades[$userid]->get_context()->id,

                                GRADE_FILE_COMPONENT,

                                GRADE_FEEDBACK_FILEAREA,

                                $grade_grades[$userid]->id

                            );

                            $grade->str_feedback = format_text($feedback, $grade->feedbackformat,

                                ['context' => $grade_grades[$userid]->get_context()]);

                        }

                        $item->grades[$userid] = $grade;

                    }

                }

                $return->items[$grade_item->itemnumber] = $item;

            } else {

                if (!$grade_outcome = grade_outcome::fetch(array('id'=>$grade_item->outcomeid))) {

                    debugging('Incorect outcomeid found');

                    continue;

                }

                // outcome info

                $outcome = new stdClass();

                $outcome->id = $grade_item->id;

                $outcome->itemnumber = $grade_item->itemnumber;

                $outcome->itemtype   = $grade_item->itemtype;

                $outcome->itemmodule = $grade_item->itemmodule;

                $outcome->iteminstance = $grade_item->iteminstance;

                $outcome->scaleid    = $grade_outcome->scaleid;

                $outcome->name       = $grade_outcome->get_name();

                $outcome->locked     = $grade_item->is_locked();

                $outcome->hidden     = $grade_item->is_hidden();

                if (empty($userid_or_ids)) {

                    $userids = array();

                } else if (is_array($userid_or_ids)) {

                    $userids = $userid_or_ids;

                } else {

                    $userids = array($userid_or_ids);

                }

                if ($userids) {

                    $grade_grades = grade_grade::fetch_users_grades($grade_item, $userids, true);

                    foreach ($userids as $userid) {

                        $grade_grades[$userid]->grade_item =& $grade_item;

                        $grade = new stdClass();

                        $grade->grade          = $grade_grades[$userid]->finalgrade;

                        $grade->locked         = $grade_grades[$userid]->is_locked();

                        $grade->hidden         = $grade_grades[$userid]->is_hidden();

                        $grade->feedback       = $grade_grades[$userid]->feedback;

                        $grade->feedbackformat = $grade_grades[$userid]->feedbackformat;

                        $grade->usermodified   = $grade_grades[$userid]->usermodified;

                        $grade->datesubmitted  = $grade_grades[$userid]->get_datesubmitted();

                        $grade->dategraded     = $grade_grades[$userid]->get_dategraded();

                        // create text representation of grade

                        if (in_array($grade_item->id, $needsupdate)) {

                            $grade->grade     = false;

                            $grade->str_grade = get_string('error');

                        } else if (is_null($grade->grade)) {

                            $grade->grade = 0;

                            $grade->str_grade = get_string('nooutcome', 'grades');

                        } else {

                            $grade->grade = (int)$grade->grade;

                            $scale = $grade_item->load_scale();

                            $grade->str_grade = format_string($scale->scale_items[(int)$grade->grade-1]);

                        }

                        // create html representation of feedback

                        if (is_null($grade->feedback)) {

                            $grade->str_feedback = '';

                        } else {

                            $grade->str_feedback = format_text($grade->feedback, $grade->feedbackformat);

                        }

                        $outcome->grades[$userid] = $grade;

                    }

                }

                if (isset($return->outcomes[$grade_item->itemnumber])) {

                    // itemnumber duplicates - lets fix them!

                    $newnumber = $grade_item->itemnumber + 1;

                    while(grade_item::fetch(array('itemtype'=>$itemtype, 'itemmodule'=>$itemmodule, 'iteminstance'=>$iteminstance, 'courseid'=>$courseid, 'itemnumber'=>$newnumber))) {

                        $newnumber++;

                    }

                    $outcome->itemnumber    = $newnumber;

                    $grade_item->itemnumber = $newnumber;

                    $grade_item->update('system');

                }

                $return->outcomes[$grade_item->itemnumber] = $outcome;

            }

        }

    }

    // sort results using itemnumbers

    ksort($return->items, SORT_NUMERIC);

    ksort($return->outcomes, SORT_NUMERIC);

    return $return;

}

///////////////////////////////////////////////////////////////////

///// End of public API for communication with modules/blocks /////

///////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////

///// Internal API: used by gradebook plugins and Moodle core /////

///////////////////////////////////////////////////////////////////

/**

 * Returns a  course gradebook setting

 *

 * @param int $courseid

 * @param string $name of setting, maybe null if reset only

 * @param string $default value to return if setting is not found

 * @param bool $resetcache force reset of internal static cache

 * @return string value of the setting, $default if setting not found, NULL if supplied $name is null

 */

function grade_get_setting($courseid, $name, $default=null, $resetcache=false) {

    global $DB;

    $cache = cache::make('core', 'gradesetting');

    $gradesetting = $cache->get($courseid) ?: array();

    if ($resetcache or empty($gradesetting)) {

        $gradesetting = array();

        $cache->set($courseid, $gradesetting);

    } else if (is_null($name)) {

        return null;

    } else if (array_key_exists($name, $gradesetting)) {

        return $gradesetting[$name];

    }

    if (!$data = $DB->get_record('grade_settings', array('courseid'=>$courseid, 'name'=>$name))) {

        $result = null;

    } else {

        $result = $data->value;

    }

    if (is_null($result)) {

        $result = $default;

    }

    $gradesetting[$name] = $result;

    $cache->set($courseid, $gradesetting);

    return $result;

}

/**

 * Returns all course gradebook settings as object properties

 *

 * @param int $courseid

 * @return object

 */

function grade_get_settings($courseid) {

    global $DB;

     $settings = new stdClass();

     $settings->id = $courseid;

    if ($records = $DB->get_records('grade_settings', array('courseid'=>$courseid))) {

        foreach ($records as $record) {

            $settings->{$record->name} = $record->value;

        }

    }

    return $settings;

}

/**

 * Add, update or delete a course gradebook setting

 *

 * @param int $courseid The course ID

 * @param string $name Name of the setting

 * @param string $value Value of the setting. NULL means delete the setting.

 */

function grade_set_setting($courseid, $name, $value) {

    global $DB;

    if (is_null($value)) {

        $DB->delete_records('grade_settings', array('courseid'=>$courseid, 'name'=>$name));

    } else if (!$existing = $DB->get_record('grade_settings', array('courseid'=>$courseid, 'name'=>$name))) {

        $data = new stdClass();

        $data->courseid = $courseid;

        $data->name     = $name;

        $data->value    = $value;

        $DB->insert_record('grade_settings', $data);

    } else {

        $data = new stdClass();

        $data->id       = $existing->id;

        $data->value    = $value;

        $DB->update_record('grade_settings', $data);

    }

    grade_get_setting($courseid, null, null, true); // reset the cache

}

/**

 * Returns string representation of grade value

 *

 * @param float|null $value The grade value

 * @param object $grade_item Grade item object passed by reference to prevent scale reloading

 * @param bool $localized use localised decimal separator

 * @param int $displaytype type of display. For example GRADE_DISPLAY_TYPE_REAL, GRADE_DISPLAY_TYPE_PERCENTAGE, GRADE_DISPLAY_TYPE_LETTER

 * @param int $decimals The number of decimal places when displaying float values

 * @return string

 */

function grade_format_gradevalue(?float $value, &$grade_item, $localized=true, $displaytype=null, $decimals=null) {

    if ($grade_item->gradetype == GRADE_TYPE_NONE or $grade_item->gradetype == GRADE_TYPE_TEXT) {

        return '';

    }

    // no grade yet?

    if (is_null($value)) {

        return '-';

    }

    if ($grade_item->gradetype != GRADE_TYPE_VALUE and $grade_item->gradetype != GRADE_TYPE_SCALE) {

        //unknown type??

        return '';

    }

    if (is_null($displaytype)) {

        $displaytype = $grade_item->get_displaytype();

    }

    if (is_null($decimals)) {

        $decimals = $grade_item->get_decimals();

    }

    switch ($displaytype) {

        case GRADE_DISPLAY_TYPE_REAL:

            return grade_format_gradevalue_real($value, $grade_item, $decimals, $localized);

        case GRADE_DISPLAY_TYPE_PERCENTAGE:

            return grade_format_gradevalue_percentage($value, $grade_item, $decimals, $localized);

        case GRADE_DISPLAY_TYPE_LETTER:

            return grade_format_gradevalue_letter($value, $grade_item);

        case GRADE_DISPLAY_TYPE_REAL_PERCENTAGE:

            return grade_format_gradevalue_real($value, $grade_item, $decimals, $localized) . ' (' .

                    grade_format_gradevalue_percentage($value, $grade_item, $decimals, $localized) . ')';

        case GRADE_DISPLAY_TYPE_REAL_LETTER:

            return grade_format_gradevalue_real($value, $grade_item, $decimals, $localized) . ' (' .

                    grade_format_gradevalue_letter($value, $grade_item) . ')';

        case GRADE_DISPLAY_TYPE_PERCENTAGE_REAL:

            return grade_format_gradevalue_percentage($value, $grade_item, $decimals, $localized) . ' (' .

                    grade_format_gradevalue_real($value, $grade_item, $decimals, $localized) . ')';

        case GRADE_DISPLAY_TYPE_LETTER_REAL:

            return grade_format_gradevalue_letter($value, $grade_item) . ' (' .

                    grade_format_gradevalue_real($value, $grade_item, $decimals, $localized) . ')';

        case GRADE_DISPLAY_TYPE_LETTER_PERCENTAGE:

            return grade_format_gradevalue_letter($value, $grade_item) . ' (' .

                    grade_format_gradevalue_percentage($value, $grade_item, $decimals, $localized) . ')';

        case GRADE_DISPLAY_TYPE_PERCENTAGE_LETTER:

            return grade_format_gradevalue_percentage($value, $grade_item, $decimals, $localized) . ' (' .

                    grade_format_gradevalue_letter($value, $grade_item) . ')';

        default:

            return '';

    }

}

/**

 * Returns a float representation of a grade value

 *

 * @param float|null $value The grade value

 * @param object $grade_item Grade item object

 * @param int $decimals The number of decimal places

 * @param bool $localized use localised decimal separator

 * @return string

 */

function grade_format_gradevalue_real(?float $value, $grade_item, $decimals, $localized) {

    if ($grade_item->gradetype == GRADE_TYPE_SCALE) {

        if (!$scale = $grade_item->load_scale()) {

            return get_string('error');

        }

        $value = $grade_item->bounded_grade($value);

        return format_string($scale->scale_items[$value-1]);

    } else {

        return format_float($value, $decimals, $localized);

    }

}

/**

 * Returns a percentage representation of a grade value

 *

 * @param float|null $value The grade value

 * @param object $grade_item Grade item object

 * @param int $decimals The number of decimal places

 * @param bool $localized use localised decimal separator

 * @return string

 */

function grade_format_gradevalue_percentage(?float $value, $grade_item, $decimals, $localized) {

    $min = $grade_item->grademin;

    $max = $grade_item->grademax;

    if ($min == $max) {

        return '';

    }

    $value = $grade_item->bounded_grade($value);

    $percentage = (($value-$min)*100)/($max-$min);

    return format_float($percentage, $decimals, $localized).' %';

}

/**

 * Returns a letter grade representation of a grade value

 * The array of grade letters used is produced by {@link grade_get_letters()} using the course context

 *

 * @param float|null $value The grade value

 * @param object $grade_item Grade item object

 * @return string

 */

function grade_format_gradevalue_letter(?float $value, $grade_item) {

    global $CFG;

    $context = context_course::instance($grade_item->courseid, IGNORE_MISSING);

    if (!$letters = grade_get_letters($context)) {

        return ''; // no letters??

    }

    if (is_null($value)) {

        return '-';

    }

    $value = grade_grade::standardise_score($value, $grade_item->grademin, $grade_item->grademax, 0, 100);

    $value = bounded_number(0, $value, 100); // just in case

    $gradebookcalculationsfreeze = 'gradebook_calculations_freeze_' . $grade_item->courseid;

    foreach ($letters as $boundary => $letter) {

        if (property_exists($CFG, $gradebookcalculationsfreeze) && (int)$CFG->{$gradebookcalculationsfreeze} <= 20160518) {

            // Do nothing.

        } else {

            // The boundary is a percentage out of 100 so use 0 as the min and 100 as the max.

            $boundary = grade_grade::standardise_score($boundary, 0, 100, 0, 100);

        }

        if ($value >= $boundary) {

            return format_string($letter);

        }

    }

    return '-'; // no match? maybe '' would be more correct

}

/**

 * Returns grade options for gradebook grade category menu

 *

 * @param int $courseid The course ID

 * @param bool $includenew Include option for new category at array index -1

 * @return array of grade categories in course

 */

function grade_get_categories_menu($courseid, $includenew=false) {

    $result = array();

    if (!$categories = grade_category::fetch_all(array('courseid'=>$courseid))) {

        //make sure course category exists

        if (!grade_category::fetch_course_category($courseid)) {

            debugging('Can not create course grade category!');

            return $result;

        }

        $categories = grade_category::fetch_all(array('courseid'=>$courseid));

    }

    foreach ($categories as $key=>$category) {

        if ($category->is_course_category()) {

            $result[$category->id] = get_string('uncategorised', 'grades');

            unset($categories[$key]);

        }

    }

    if ($includenew) {

        $result[-1] = get_string('newcategory', 'grades');

    }

    $cats = array();

    foreach ($categories as $category) {

        $cats[$category->id] = $category->get_name();

    }

    core_collator::asort($cats);

    return ($result+$cats);

}

/**

 * Returns the array of grade letters to be used in the supplied context

 *

 * @param object $context Context object or null for defaults

 * @return array of grade_boundary (minimum) => letter_string

 */

function grade_get_letters($context=null) {

    global $DB;

    if (empty($context)) {

        //default grading letters

        return array('93'=>'A', '90'=>'A-', '87'=>'B+', '83'=>'B', '80'=>'B-', '77'=>'C+', '73'=>'C', '70'=>'C-', '67'=>'D+', '60'=>'D', '0'=>'F');

    }

    $cache = cache::make('core', 'grade_letters');

    $data = $cache->get($context->id);

    if (!empty($data)) {

        return $data;

    }

    $letters = array();

    $contexts = $context->get_parent_context_ids();

    array_unshift($contexts, $context->id);

    foreach ($contexts as $ctxid) {

        if ($records = $DB->get_records('grade_letters', array('contextid'=>$ctxid), 'lowerboundary DESC')) {

            foreach ($records as $record) {

                $letters[$record->lowerboundary] = $record->letter;

            }

        }

        if (!empty($letters)) {

            // Cache the grade letters for this context.

            $cache->set($context->id, $letters);

            return $letters;

        }

    }

    $letters = grade_get_letters(null);