[Summary view]

Differences Between: [Versions 310 and 401] [Versions 310 and 402] [Versions 310 and 403]

   1  <?php
   2  // This file is part of Moodle - http://moodle.org/
   3  //
   4  // Moodle is free software: you can redistribute it and/or modify
   5  // it under the terms of the GNU General Public License as published by
   6  // the Free Software Foundation, either version 3 of the License, or
   7  // (at your option) any later version.
   8  //
   9  // Moodle is distributed in the hope that it will be useful,
  10  // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  // GNU General Public License for more details.
  13  //
  14  // You should have received a copy of the GNU General Public License
  15  // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16  
  17  /**
  18   * Course completion critieria aggregation
  19   *
  20   * @package core_completion
  21   * @category completion
  22   * @copyright 2009 Catalyst IT Ltd
  23   * @author Aaron Barnes <aaronb@catalyst.net.nz>
  24   * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  25   */
  26  
  27  defined('MOODLE_INTERNAL') || die();
  28  
  29  
  30  /**
  31   * Trigger for the new data_object api.
  32   *
  33   * See data_object::__constructor
  34   */
  35  define('DATA_OBJECT_FETCH_BY_KEY',  2);
  36  
  37  /**
  38   * A data abstraction object that holds methods and attributes
  39   *
  40   * @package core_completion
  41   * @category completion
  42   * @copyright 2009 Catalyst IT Ltd
  43   * @author Aaron Barnes <aaronb@catalyst.net.nz>
  44   * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  45   */
  46  abstract class data_object {
  47  
  48      /* @var string Table that the class maps to in the database */
  49      public $table;
  50  
  51      /* @var array Array of required table fields, must start with 'id'. */
  52      public $required_fields = array('id');
  53  
  54      /**
  55       * Array of optional fields with default values - usually long text information that is not always needed.
  56       * If you want to create an instance without optional fields use: new data_object($only_required_fields, false);
  57       * @var array
  58       */
  59      public $optional_fields = array();
  60  
  61      /* @var Array of unique fields, used in where clauses and constructor */
  62      public $unique_fields = array();
  63  
  64      /* @var int The primary key */
  65      public $id;
  66  
  67  
  68      /**
  69       * Constructor. Optionally (and by default) attempts to fetch corresponding row from DB.
  70       *
  71       * If $fetch is not false, there are a few different things that can happen:
  72       * - true:
  73       *   load corresponding row from the database, using $params as the WHERE clause
  74       *
  75       * - DATA_OBJECT_FETCH_BY_KEY:
  76       *  load corresponding row from the database, using only the $id in the WHERE clause (if set),
  77       *  otherwise using the columns listed in $this->unique_fields.
  78       *
  79       * - array():
  80       *   load corresponding row from the database, using the columns listed in this array
  81       *   in the WHERE clause
  82       *
  83       * @param   array   $params     required parameters and their values for this data object
  84       * @param   mixed   $fetch      if false, do not attempt to fetch from the database, otherwise see notes
  85       */
  86      public function __construct($params = null, $fetch = true) {
  87  
  88          if (is_object($params)) {
  89              throw new coding_exception('data_object params should be in the form of an array, not an object');
  90          }
  91  
  92          // If no params given, apply defaults for optional fields
  93          if (empty($params) || !is_array($params)) {
  94              self::set_properties($this, $this->optional_fields);
  95              return;
  96          }
  97  
  98          // If fetch is false, do not load from database
  99          if ($fetch === false) {
 100              self::set_properties($this, $params);
 101              return;
 102          }
 103  
 104          // Compose where clause only from fields in unique_fields
 105          if ($fetch === DATA_OBJECT_FETCH_BY_KEY && !empty($this->unique_fields)) {
 106              if (empty($params['id'])) {
 107                  $where = array_intersect_key($params, array_flip($this->unique_fields));
 108              }
 109              else {
 110                  $where = array('id' => $params['id']);
 111              }
 112          // Compose where clause from given field names
 113          } else if (is_array($fetch) && !empty($fetch)) {
 114              $where = array_intersect_key($params, array_flip($fetch));
 115          // Use entire params array for where clause
 116          } else {
 117              $where = $params;
 118          }
 119  
 120          // Attempt to load from database
 121          if ($data = $this->fetch($where)) {
 122              // Apply data from database, then data sent to constructor
 123              self::set_properties($this, $data);
 124              self::set_properties($this, $params);
 125          } else {
 126              // Apply defaults for optional fields, then data from constructor
 127              self::set_properties($this, $this->optional_fields);
 128              self::set_properties($this, $params);
 129          }
 130      }
 131  
 132      /**
 133       * Makes sure all the optional fields are loaded.
 134       *
 135       * If id present (==instance exists in db) fetches data from db.
 136       * Defaults are used for new instances.
 137       */
 138      public function load_optional_fields() {
 139          global $DB;
 140          foreach ($this->optional_fields as $field=>$default) {
 141              if (property_exists($this, $field)) {
 142                  continue;
 143              }
 144              if (empty($this->id)) {
 145                  $this->$field = $default;
 146              } else {
 147                  $this->$field = $DB->get_field($this->table, $field, array('id', $this->id));
 148              }
 149          }
 150      }
 151  
 152      /**
 153       * Finds and returns a data_object instance based on params.
 154       *
 155       * This function MUST be overridden by all deriving classes.
 156       *
 157       * @param array $params associative arrays varname => value
 158       * @throws coding_exception This function MUST be overridden
 159       * @return data_object instance  of data_object or false if none found.
 160       */
 161      public static function fetch($params) {
 162          throw new coding_exception('fetch() method needs to be overridden in each subclass of data_object');
 163      }
 164  
 165      /**
 166       * Finds and returns all data_object instances based on params.
 167       *
 168       * This function MUST be overridden by all deriving classes.
 169       *
 170       * @param array $params associative arrays varname => value
 171       * @throws coding_exception This function MUST be overridden
 172       * @return array array of data_object instances or false if none found.
 173       */
 174      public static function fetch_all($params) {
 175          throw new coding_exception('fetch_all() method needs to be overridden in each subclass of data_object');
 176      }
 177  
 178      /**
 179       * Factory method - uses the parameters to retrieve matching instance from the DB.
 180       *
 181       * @final
 182       * @param string $table The table name to fetch from
 183       * @param string $classname The class that you want the result instantiated as
 184       * @param array $params Any params required to select the desired row
 185       * @return object Instance of $classname or false.
 186       */
 187      protected static function fetch_helper($table, $classname, $params) {
 188          if ($instances = self::fetch_all_helper($table, $classname, $params)) {
 189              if (count($instances) > 1) {
 190                  // we should not tolerate any errors here - problems might appear later
 191                  print_error('morethanonerecordinfetch','debug');
 192              }
 193              return reset($instances);
 194          } else {
 195              return false;
 196          }
 197      }
 198  
 199      /**
 200       * Factory method - uses the parameters to retrieve all matching instances from the DB.
 201       *
 202       * @final
 203       * @param string $table The table name to fetch from
 204       * @param string $classname The class that you want the result instantiated as
 205       * @param array $params Any params required to select the desired row
 206       * @return mixed array of object instances or false if not found
 207       */
 208      public static function fetch_all_helper($table, $classname, $params) {
 209          $instance = new $classname();
 210  
 211          $classvars = (array)$instance;
 212          $params    = (array)$params;
 213  
 214          $wheresql = array();
 215  
 216          $dbparams = array();
 217          foreach ($params as $var=>$value) {
 218              if (!in_array($var, $instance->required_fields) and !array_key_exists($var, $instance->optional_fields)) {
 219                  continue;
 220              }
 221              if (is_null($value)) {
 222                  $wheresql[] = " $var IS NULL ";
 223              } else {
 224                  $wheresql[] = " $var = ? ";
 225                  $dbparams[] = $value;
 226              }
 227          }
 228  
 229          if (empty($wheresql)) {
 230              $wheresql = '';
 231          } else {
 232              $wheresql = implode("AND", $wheresql);
 233          }
 234  
 235          global $DB;
 236          if ($datas = $DB->get_records_select($table, $wheresql, $dbparams)) {
 237  
 238              $result = array();
 239              foreach($datas as $data) {
 240                  $instance = new $classname();
 241                  self::set_properties($instance, $data);
 242                  $result[$instance->id] = $instance;
 243              }
 244              return $result;
 245  
 246          } else {
 247  
 248              return false;
 249          }
 250      }
 251  
 252      /**
 253       * Updates this object in the Database, based on its object variables. ID must be set.
 254       *
 255       * @return bool success
 256       */
 257      public function update() {
 258          global $DB;
 259  
 260          if (empty($this->id)) {
 261              debugging('Can not update data object, no id!');
 262              return false;
 263          }
 264  
 265          $data = $this->get_record_data();
 266  
 267          $DB->update_record($this->table, $data);
 268  
 269          $this->notify_changed(false);
 270          return true;
 271      }
 272  
 273      /**
 274       * Deletes this object from the database.
 275       *
 276       * @return bool success
 277       */
 278      public function delete() {
 279          global $DB;
 280  
 281          if (empty($this->id)) {
 282              debugging('Can not delete data object, no id!');
 283              return false;
 284          }
 285  
 286          $data = $this->get_record_data();
 287  
 288          if ($DB->delete_records($this->table, array('id'=>$this->id))) {
 289              $this->notify_changed(true);
 290              return true;
 291  
 292          } else {
 293              return false;
 294          }
 295      }
 296  
 297      /**
 298       * Returns object with fields and values that are defined in database
 299       *
 300       * @return stdClass
 301       */
 302      public function get_record_data() {
 303          $data = new stdClass();
 304  
 305          foreach ($this as $var=>$value) {
 306              if (in_array($var, $this->required_fields) or array_key_exists($var, $this->optional_fields)) {
 307                  if (is_object($value) or is_array($value)) {
 308                      debugging("Incorrect property '$var' found when inserting data object");
 309                  } else {
 310                      $data->$var = $value;
 311                  }
 312              }
 313          }
 314          return $data;
 315      }
 316  
 317      /**
 318       * Records this object in the Database, sets its id to the returned value, and returns that value.
 319       * If successful this function also fetches the new object data from database and stores it
 320       * in object properties.
 321       *
 322       * @return int PK ID if successful, false otherwise
 323       */
 324      public function insert() {
 325          global $DB;
 326  
 327          if (!empty($this->id)) {
 328              debugging("Data object already exists!");
 329              return false;
 330          }
 331  
 332          $data = $this->get_record_data();
 333  
 334          $this->id = $DB->insert_record($this->table, $data);
 335  
 336          // set all object properties from real db data
 337          $this->update_from_db();
 338  
 339          $this->notify_changed(false);
 340          return $this->id;
 341      }
 342  
 343      /**
 344       * Using this object's id field, fetches the matching record in the DB, and looks at
 345       * each variable in turn. If the DB has different data, the db's data is used to update
 346       * the object. This is different from the update() function, which acts on the DB record
 347       * based on the object.
 348       *
 349       * @return bool True for success, false otherwise.
 350       */
 351      public function update_from_db() {
 352          if (empty($this->id)) {
 353              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.");
 354              return false;
 355          }
 356          global $DB;
 357          if (!$params = $DB->get_record($this->table, array('id' => $this->id))) {
 358              debugging("Object with this id:{$this->id} does not exist in table:{$this->table}, can not update from db!");
 359              return false;
 360          }
 361  
 362          self::set_properties($this, $params);
 363  
 364          return true;
 365      }
 366  
 367      /**
 368       * Given an associated array or object, cycles through each key/variable
 369       * and assigns the value to the corresponding variable in this object.
 370       *
 371       * @final
 372       * @param data_object $instance
 373       * @param array $params
 374       */
 375      public static function set_properties(&$instance, $params) {
 376          $params = (array) $params;
 377          foreach ($params as $var => $value) {
 378              if (in_array($var, $instance->required_fields) or array_key_exists($var, $instance->optional_fields)) {
 379                  $instance->$var = $value;
 380              }
 381          }
 382      }
 383  
 384      /**
 385       * Called immediately after the object data has been inserted, updated, or
 386       * deleted in the database. Default does nothing, can be overridden to
 387       * hook in special behaviour.
 388       *
 389       * @param bool $deleted Set this to true if it has been deleted.
 390       */
 391      public function notify_changed($deleted) {
 392      }
 393  }