lib/grade/grade_object.php

   1 <?php // $Id$
   2
   3 ///////////////////////////////////////////////////////////////////////////
   4 //                                                                       //
   5 // NOTICE OF COPYRIGHT                                                   //
   6 //                                                                       //
   7 // Moodle - Modular Object-Oriented Dynamic Learning Environment         //
   8 //          http://moodle.com                                            //
   9 //                                                                       //
  10 // Copyright (C) 2001-2007  Martin Dougiamas  http://dougiamas.com       //
  11 //                                                                       //
  12 // This program is free software; you can redistribute it and/or modify  //
  13 // it under the terms of the GNU General Public License as published by  //
  14 // the Free Software Foundation; either version 2 of the License, or     //
  15 // (at your option) any later version.                                   //
  16 //                                                                       //
  17 // This program is distributed in the hope that it will be useful,       //
  18 // but WITHOUT ANY WARRANTY; without even the implied warranty of        //
  19 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         //
  20 // GNU General Public License for more details:                          //
  21 //                                                                       //
  22 //          http://www.gnu.org/copyleft/gpl.html                         //
  23 //                                                                       //
  24 ///////////////////////////////////////////////////////////////////////////
  25
  26 /**
  27  * An abstract object that holds methods and attributes common to all grade_* objects defined here.
  28  * @abstract
  29  */
  30 class grade_object {
  31     /**
  32      * Array of class variables that are not part of the DB table fields
  33      * @var array $nonfields
  34      */
  35     var $nonfields = array('nonfields', 'required_fields');
  36
  37     /**
  38      * Array of required fields (keys) and their default values (values).
  39      * @var array $required_fields
  40      */
  41     var $required_fields = array();
  42
  43     /**
  44      * The PK.
  45      * @var int $id
  46      */
  47     var $id;
  48
  49     /**
  50      * The first time this grade_calculation was created.
  51      * @var int $timecreated
  52      */
  53     var $timecreated;
  54
  55     /**
  56      * The last time this grade_calculation was modified.
  57      * @var int $timemodified
  58      */
  59     var $timemodified;
  60
  61     /**
  62      * Constructor. Optionally (and by default) attempts to fetch corresponding row from DB.
  63      * @param array $params an array with required parameters for this grade object.
  64      * @param boolean $fetch Whether to fetch corresponding row from DB or not.
  65      */
  66     function grade_object($params=NULL, $fetch = true) {
  67         if (!empty($params) and (is_array($params) or is_object($params))) {
  68             if ($fetch and $data = $this->fetch($params)) {
  69                 grade_object::set_properties($this, $data);
  70
  71             } else {
  72                 grade_object::set_properties($this, $params);
  73             }
  74         }
  75     }
  76
  77     /**
  78      * Finds and returns a grade_object instance based on params.
  79      * @static abstract
  80      *
  81      * @param array $params associative arrays varname=>value
  82      * @return object grade_object instance or false if none found.
  83      */
  84     function fetch($params) {
  85         error('Abstract method fetch() not overrided in '.get_class($this));
  86     }
  87
  88     /**
  89      * Finds and returns all grade_object instances based on params.
  90      * @static abstract
  91      *
  92      * @param array $params associative arrays varname=>value
  93      * @return array array of grade_object insatnces or false if none found.
  94      */
  95     function fetch_all($params) {
  96         error('Abstract method fetch_all() not overrided in '.get_class($this));
  97     }
  98
  99     /**
 100      * Factory method - uses the parameters to retrieve matching instance from the DB.
 101      * @static final protected
 102      * @return mixed object insatnce or false if not found
 103      */
 104     function fetch_helper($table, $classname, $params) {
 105         // we have to do use this hack because of the incomplete OOP implementation in PHP4 :-(
 106         // in PHP5 we could do it much better
 107         if ($instances = grade_object::fetch_all_helper($table, $classname, $params)) {
 108             if (count($instances) > 1) {
 109                 // we should not tolerate any errors here - proplems might appear later
 110                 error('Found more than one record in fetch() !');
 111             }
 112             return reset($instances);
 113         } else {
 114             return false;
 115         }
 116     }
 117
 118     /**
 119      * Factory method - uses the parameters to retrieve all matching instances from the DB.
 120      * @static final protected
 121      * @return mixed array of object instances or false if not found
 122      */
 123     function fetch_all_helper($table, $classname, $params) {
 124         // we have to do use this hack because of the incomplete OOP implementation in PHP4 :-(
 125         // in PHP5 we could do it much better
 126         $instance = new $classname();
 127
 128         $classvars = (array)$instance;
 129         $params    = (array)$params;
 130
 131         $wheresql = array();
 132
 133         // remove incorrect params - warn developer if needed
 134         foreach ($params as $var=>$value) {
 135             if (!array_key_exists($var, $classvars) or in_array($var, $instance->nonfields)) {
 136                 debugging("Incorrect property name $var for class $classname");
 137                 continue;
 138             }
 139             if (is_null($value)) {
 140                 $wheresql[] = " $var IS NULL ";
 141             } else {
 142                 $value = addslashes($value);
 143                 $wheresql[] = " $var = '$value' ";
 144             }
 145         }
 146
 147         if (empty($wheresql)) {
 148             $wheresql = '';
 149         } else {
 150             $wheresql = implode("AND", $wheresql);
 151         }
 152
 153         if ($datas = get_records_select($table, $wheresql, 'id')) {
 154             $result = array();
 155             foreach($datas as $data) {
 156                 $instance = new $classname();
 157                 grade_object::set_properties($instance, $data);
 158                 $result[$instance->id] = $instance;
 159             }
 160             return $result;
 161
 162         } else {
 163             return false;
 164         }
 165     }
 166
 167     /**
 168      * Updates this object in the Database, based on its object variables. ID must be set.
 169      *
 170      * @return boolean
 171      */
 172     function update() {
 173         global $USER;
 174
 175         $this->timemodified = time();
 176
 177         if (array_key_exists('usermodified', $this)) {
 178             $this->usermodified = $USER->id;
 179         }
 180
 181         // we need to do this to prevent infinite loops in addslashes_recursive - grade_item -> category ->grade_item
 182         $data = new object();
 183         foreach ($this as $var=>$value) {
 184             if (!in_array($var, $this->nonfields)) {
 185                 $data->$var = addslashes_recursive($value);
 186             }
 187         }
 188
 189         return update_record($this->table, $data);
 190     }
 191
 192     /**
 193      * Deletes this object from the database.
 194      */
 195     function delete() {
 196         return delete_records($this->table, 'id', $this->id);
 197     }
 198
 199     /**
 200      * Records this object in the Database, sets its id to the returned value, and returns that value.
 201      * If successful this function also fetches the new object data from database and stores it
 202      * in object properties.
 203      * @return int PK ID if successful, false otherwise
 204      */
 205     function insert() {
 206         global $USER;
 207
 208         if (!empty($this->id)) {
 209             debugging("Grade object already exists!");
 210             return false;
 211         }
 212
 213         $this->timecreated = $this->timemodified = time();
 214
 215         if (array_key_exists('usermodified', $this)) {
 216             $this->usermodified = $USER->id;
 217         }
 218
 219         // we need to do this to prevent infinite loops in addslashes_recursive - grade_item -> category ->grade_item
 220         $data = new object();
 221         foreach ($this as $var=>$value) {
 222             if (!in_array($var, $this->nonfields)) {
 223                 $data->$var = addslashes_recursive($value);
 224             }
 225         }
 226
 227         if (!$this->id = insert_record($this->table, addslashes_recursive($data))) {
 228             debugging("Could not insert object into db");
 229             return false;
 230         }
 231
 232         // set all object properties from real db data
 233         $this->update_from_db();
 234
 235         return $this->id;
 236     }
 237
 238     /**
 239      * Using this object's id field, fetches the matching record in the DB, and looks at
 240      * each variable in turn. If the DB has different data, the db's data is used to update
 241      * the object. This is different from the update() function, which acts on the DB record
 242      * based on the object.
 243      */
 244     function update_from_db() {
 245         if (empty($this->id)) {
 246             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.");
 247             return false;
 248         }
 249
 250         if (!$params = get_record($this->table, 'id', $this->id)) {
 251             debugging("Object with this id:{$this->id} does not exist in table:{$this->table}, can not update from db!");
 252             return false;
 253         }
 254
 255         grade_object::set_properties($this, $params);
 256
 257         return true;
 258     }
 259
 260     /**
 261      * Given an associated array or object, cycles through each key/variable
 262      * and assigns the value to the corresponding variable in this object.
 263      * @static final
 264      */
 265     function set_properties(&$instance, $params) {
 266         $classvars = (array)$instance;
 267         foreach ($params as $var => $value) {
 268             if (array_key_exists($var, $classvars)) {
 269                 $instance->$var = $value;
 270             }
 271         }
 272     }
 273
 274 }
 275 ?>