Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 4.2.x will end 22 April 2024 (12 months).
  • Bug fixes for security issues in 4.2.x will end 7 October 2024 (18 months).
  • PHP version: minimum PHP 8.0.0 Note: minimum PHP version has increased since Moodle 4.1. PHP 8.1.x is supported too.
<?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/>.

/**
 * Definition of a grade object class for grade item, grade category etc to inherit from
 *
 * @package   core_grades
 * @category  grade
 * @copyright 2006 Nicolas Connault
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */

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

/**
 * An abstract object that holds methods and attributes common to all grade_* objects defined here.
 *
 * @package   core_grades
 * @category  grade
 * @copyright 2006 Nicolas Connault
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
abstract class grade_object {
    /**
     * The database table this grade object is stored in
     * @var string $table
     */
    public $table;

    /**
     * Array of required table fields, must start with 'id'.
     * @var array $required_fields
     */
    public $required_fields = array('id', 'timecreated', 'timemodified', 'hidden');

    /**
     * Array of optional fields with default values - usually long text information that is not always needed.
     * If you want to create an instance without optional fields use: new grade_object($only_required_fields, false);
     * @var array $optional_fields
     */
    public $optional_fields = array();

    /**
     * The PK.
     * @var int $id
     */
    public $id;

    /**
     * The first time this grade_object was created.
     * @var int $timecreated
     */
    public $timecreated;

    /**
     * The last time this grade_object was modified.
     * @var int $timemodified
     */
    public $timemodified;

    /**
     * 0 if visible, 1 always hidden or date not visible until
     * @var int $hidden
     */
    var $hidden = 0;

    /**
     * Constructor. Optionally (and by default) attempts to fetch corresponding row from the database
     *
     * @param array $params An array with required parameters for this grade object.
     * @param bool $fetch Whether to fetch corresponding row from the database or not,
     *        optional fields might not be defined if false used
     */
    public function __construct($params=NULL, $fetch=true) {
        if (!empty($params) and (is_array($params) or is_object($params))) {
            if ($fetch) {
                if ($data = $this->fetch($params)) {
                    grade_object::set_properties($this, $data);
                } else {
                    grade_object::set_properties($this, $this->optional_fields);//apply defaults for optional fields
                    grade_object::set_properties($this, $params);
                }

            } else {
                grade_object::set_properties($this, $params);
            }

        } else {
            grade_object::set_properties($this, $this->optional_fields);//apply defaults for optional fields
        }
    }

    /**
     * Makes sure all the optional fields are loaded.
     *
     * If id present, meaning the instance exists in the database, then data will be fetched from the database.
     * Defaults are used for new instances.
     */
    public function load_optional_fields() {
        global $DB;
        foreach ($this->optional_fields as $field=>$default) {
            if (property_exists($this, $field)) {
                continue;
            }
            if (empty($this->id)) {
                $this->$field = $default;
            } else {
                $this->$field = $DB->get_field($this->table, $field, array('id', $this->id));
            }
        }
    }

    /**
     * Finds and returns a grade_object instance based on params.
     *
     * @static
     * @abstract
     * @param array $params associative arrays varname=>value
     * @return object grade_object instance or false if none found.
     */
    public static function fetch($params) {
        throw new coding_exception('fetch() method needs to be overridden in each subclass of grade_object');
    }

    /**
     * Finds and returns all grade_object instances based on $params.
     *
     * @static
     * @abstract
     * @throws coding_exception Throws a coding exception if fetch_all() has not been overriden by the grade object subclass
     * @param array $params Associative arrays varname=>value
     * @return array|bool Array of grade_object instances or false if none found.
     */
    public static function fetch_all($params) {
        throw new coding_exception('fetch_all() method needs to be overridden in each subclass of grade_object');
    }

    /**
     * Factory method which uses the parameters to retrieve matching instances from the database
     *
     * @param string $table The table to retrieve from
     * @param string $classname The name of the class to instantiate
     * @param array $params An array of conditions like $fieldname => $fieldvalue
     * @return mixed An object instance or false if not found
     */
    protected static function fetch_helper($table, $classname, $params) {
        if ($instances = grade_object::fetch_all_helper($table, $classname, $params)) {
            if (count($instances) > 1) {
                // we should not tolerate any errors here - problems might appear later
< print_error('morethanonerecordinfetch','debug');
> throw new \moodle_exception('morethanonerecordinfetch', 'debug');
} return reset($instances); } else { return false; } } /** * Factory method which uses the parameters to retrieve all matching instances from the database * * @param string $table The table to retrieve from * @param string $classname The name of the class to instantiate * @param array $params An array of conditions like $fieldname => $fieldvalue * @return array|bool Array of object instances or false if not found */ public static function fetch_all_helper($table, $classname, $params) { global $DB; // Need to introspect DB here. $instance = new $classname(); $classvars = (array)$instance; $params = (array)$params; $wheresql = array(); $newparams = array(); $columns = $DB->get_columns($table); // Cached, no worries. foreach ($params as $var=>$value) { if (!in_array($var, $instance->required_fields) and !array_key_exists($var, $instance->optional_fields)) { continue; } if (!array_key_exists($var, $columns)) { continue; } if (is_null($value)) { $wheresql[] = " $var IS NULL "; } else { if ($columns[$var]->meta_type === 'X') { // We have a text/clob column, use the cross-db method for its comparison. $wheresql[] = ' ' . $DB->sql_compare_text($var) . ' = ' . $DB->sql_compare_text('?') . ' '; } else { // Other columns (varchar, integers...). $wheresql[] = " $var = ? "; } $newparams[] = $value; } } if (empty($wheresql)) { $wheresql = ''; } else { $wheresql = implode("AND", $wheresql); } global $DB; $rs = $DB->get_recordset_select($table, $wheresql, $newparams); //returning false rather than empty array if nothing found if (!$rs->valid()) { $rs->close(); return false; } $result = array(); foreach($rs as $data) { $instance = new $classname(); grade_object::set_properties($instance, $data); $result[$instance->id] = $instance; } $rs->close(); return $result; } /** * Updates this object in the Database, based on its object variables. ID must be set. * * @param string $source from where was the object updated (mod/forum, manual, etc.) * @param bool $isbulkupdate If bulk grade update is happening. * @return bool success */ public function update($source = null, $isbulkupdate = false) { global $USER, $CFG, $DB; if (empty($this->id)) { debugging('Can not update grade object, no id!'); return false; } $data = $this->get_record_data(); $DB->update_record($this->table, $data); $historyid = null; if (empty($CFG->disablegradehistory)) { unset($data->timecreated); $data->action = GRADE_HISTORY_UPDATE; $data->oldid = $this->id; $data->source = $source; $data->timemodified = time(); $data->loggeduser = $USER->id; $historyid = $DB->insert_record($this->table.'_history', $data); } $this->notify_changed(false, $isbulkupdate); $this->update_feedback_files($historyid); return true; } /** * Deletes this object from the database. * * @param string $source From where was the object deleted (mod/forum, manual, etc.) * @return bool success */ public function delete($source=null) { global $USER, $CFG, $DB; if (empty($this->id)) { debugging('Can not delete grade object, no id!'); return false; } $data = $this->get_record_data(); if ($DB->delete_records($this->table, array('id'=>$this->id))) { if (empty($CFG->disablegradehistory)) { unset($data->id); unset($data->timecreated); $data->action = GRADE_HISTORY_DELETE; $data->oldid = $this->id; $data->source = $source; $data->timemodified = time(); $data->loggeduser = $USER->id; $DB->insert_record($this->table.'_history', $data); } $this->notify_changed(true); $this->delete_feedback_files(); return true; } else { return false; } } /** * Returns object with fields and values that are defined in database * * @return stdClass */ public function get_record_data() { $data = new stdClass(); foreach ($this as $var=>$value) { if (in_array($var, $this->required_fields) or array_key_exists($var, $this->optional_fields)) { if (is_object($value) or is_array($value)) { debugging("Incorrect property '$var' found when inserting grade object"); } else { $data->$var = $value; } } } return $data; } /** * Records this object in the Database, sets its id to the returned value, and returns that value. * If successful this function also fetches the new object data from database and stores it * in object properties. * * @param string $source From where was the object inserted (mod/forum, manual, etc.) * @param string $isbulkupdate If bulk grade update is happening. * @return int The new grade object ID if successful, false otherwise */ public function insert($source = null, $isbulkupdate = false) { global $USER, $CFG, $DB; if (!empty($this->id)) { debugging("Grade object already exists!"); return false; } $data = $this->get_record_data(); $this->id = $DB->insert_record($this->table, $data); // set all object properties from real db data $this->update_from_db(); $data = $this->get_record_data(); $historyid = null; if (empty($CFG->disablegradehistory)) { unset($data->timecreated); $data->action = GRADE_HISTORY_INSERT; $data->oldid = $this->id; $data->source = $source; $data->timemodified = time(); $data->loggeduser = $USER->id; $historyid = $DB->insert_record($this->table.'_history', $data); } $this->notify_changed(false, $isbulkupdate); $this->add_feedback_files($historyid); return $this->id; } /** * Using this object's id field, fetches the matching record in the DB, and looks at * each variable in turn. If the DB has different data, the db's data is used to update * the object. This is different from the update() function, which acts on the DB record * based on the object. * * @return bool True if successful */ public function update_from_db() { if (empty($this->id)) { debugging("The object could not be used in its state to retrieve a matching record from the DB, because its id field is not set."); return false; } global $DB; if (!$params = $DB->get_record($this->table, array('id' => $this->id))) { debugging("Object with this id:{$this->id} does not exist in table:{$this->table}, can not update from db!"); return false; } grade_object::set_properties($this, $params); return true; } /** * Given an associated array or object, cycles through each key/variable * and assigns the value to the corresponding variable in this object. *
< * @param stdClass $instance The object to set the properties on
> * @param grade_object $instance The object to set the properties on
* @param array $params An array of properties to set like $propertyname => $propertyvalue * @return array|stdClass Either an associative array or an object containing property name, property value pairs */ public static function set_properties(&$instance, $params) { $params = (array) $params; foreach ($params as $var => $value) { if (in_array($var, $instance->required_fields) or array_key_exists($var, $instance->optional_fields)) { $instance->$var = $value; } } } /** * Called immediately after the object data has been inserted, updated, or * deleted in the database. Default does nothing, can be overridden to * hook in special behaviour. * * @param bool $deleted */ protected function notify_changed($deleted) { } /** * Handles adding feedback files in the gradebook. * * @param int|null $historyid */ protected function add_feedback_files(int $historyid = null) { } /** * Handles updating feedback files in the gradebook. * * @param int|null $historyid */ protected function update_feedback_files(int $historyid = null) { } /** * Handles deleting feedback files in the gradebook. */ protected function delete_feedback_files() { } /** * Returns the current hidden state of this grade_item * * This depends on the grade object hidden setting and the current time if hidden is set to a "hidden until" timestamp * * @return bool Current hidden state */ function is_hidden() { return ($this->hidden == 1 or ($this->hidden != 0 and $this->hidden > time())); } /** * Check grade object hidden status * * @return bool True if a "hidden until" timestamp is set, false if grade object is set to always visible or always hidden. */ function is_hiddenuntil() { return $this->hidden > 1; } /** * Check a grade item hidden status. * * @return int 0 means visible, 1 hidden always, a timestamp means "hidden until" */ function get_hidden() { return $this->hidden; } /** * Set a grade object hidden status * * @param int $hidden 0 means visiable, 1 means hidden always, a timestamp means "hidden until" * @param bool $cascade Ignored */ function set_hidden($hidden, $cascade=false) { $this->hidden = $hidden; $this->update(); } /** * Returns whether the grade object can control the visibility of the grades. * * @return bool */ public function can_control_visibility() { return true; } }