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

/**

 * Course completion critieria aggregation

 *

 * @package core_completion

 * @category completion

 * @copyright 2009 Catalyst IT Ltd

 * @author Aaron Barnes <aaronb@catalyst.net.nz>

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

 */

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

/**

 * Trigger for the new data_object api.

 *

 * See data_object::__constructor

 */

define('DATA_OBJECT_FETCH_BY_KEY',  2);

/**

 * A data abstraction object that holds methods and attributes

 *

 * @package core_completion

 * @category completion

 * @copyright 2009 Catalyst IT Ltd

 * @author Aaron Barnes <aaronb@catalyst.net.nz>

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

 */

abstract class data_object {

    /* @var string Table that the class maps to in the database */

    public $table;

    /* @var array Array of required table fields, must start with 'id'. */

    public $required_fields = array('id');

    /**

     * 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 data_object($only_required_fields, false);

     * @var array

     */

    public $optional_fields = array();

    /* @var Array of unique fields, used in where clauses and constructor */

    public $unique_fields = array();

    /* @var int The primary key */

    public $id;

    /** @var int completed status. */

    public $completedself;

    /**

     * Constructor. Optionally (and by default) attempts to fetch corresponding row from DB.

     *

     * If $fetch is not false, there are a few different things that can happen:

     * - true:

     *   load corresponding row from the database, using $params as the WHERE clause

     *

     * - DATA_OBJECT_FETCH_BY_KEY:

     *  load corresponding row from the database, using only the $id in the WHERE clause (if set),

     *  otherwise using the columns listed in $this->unique_fields.

     *

     * - array():

     *   load corresponding row from the database, using the columns listed in this array

     *   in the WHERE clause

     *

     * @param   array   $params     required parameters and their values for this data object

     * @param   mixed   $fetch      if false, do not attempt to fetch from the database, otherwise see notes

     */

    public function __construct($params = null, $fetch = true) {

        if (is_object($params)) {

            throw new coding_exception('data_object params should be in the form of an array, not an object');

        }

        // If no params given, apply defaults for optional fields

        if (empty($params) || !is_array($params)) {

            self::set_properties($this, $this->optional_fields);

            return;

        }

        // If fetch is false, do not load from database

        if ($fetch === false) {

            self::set_properties($this, $params);

            return;

        }

        // Compose where clause only from fields in unique_fields

        if ($fetch === DATA_OBJECT_FETCH_BY_KEY && !empty($this->unique_fields)) {

            if (empty($params['id'])) {

                $where = array_intersect_key($params, array_flip($this->unique_fields));

            }

            else {

                $where = array('id' => $params['id']);

            }

        // Compose where clause from given field names

        } else if (is_array($fetch) && !empty($fetch)) {

            $where = array_intersect_key($params, array_flip($fetch));

        // Use entire params array for where clause

        } else {

            $where = $params;

        }

        // Attempt to load from database

        if ($data = $this->fetch($where)) {

            // Apply data from database, then data sent to constructor

            self::set_properties($this, $data);

            self::set_properties($this, $params);

        } else {

            // Apply defaults for optional fields, then data from constructor

            self::set_properties($this, $this->optional_fields);

            self::set_properties($this, $params);

        }

    }

    /**

     * Makes sure all the optional fields are loaded.

     *

     * If id present (==instance exists in db) fetches data from db.

     * 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 data_object instance based on params.

     *

     * This function MUST be overridden by all deriving classes.

     *

     * @param array $params associative arrays varname => value

     * @throws coding_exception This function MUST be overridden

     * @return data_object instance  of data_object or false if none found.

     */

    public static function fetch($params) {

        throw new coding_exception('fetch() method needs to be overridden in each subclass of data_object');

    }

    /**

     * Finds and returns all data_object instances based on params.

     *

     * This function MUST be overridden by all deriving classes.

     *

     * @param array $params associative arrays varname => value

     * @throws coding_exception This function MUST be overridden

     * @return array array of data_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 data_object');

    }

    /**

     * Factory method - uses the parameters to retrieve matching instance from the DB.

     *

     * @final

     * @param string $table The table name to fetch from

     * @param string $classname The class that you want the result instantiated as

     * @param array $params Any params required to select the desired row

     * @return object Instance of $classname or false.

     */

    protected static function fetch_helper($table, $classname, $params) {

        if ($instances = self::fetch_all_helper($table, $classname, $params)) {

            if (count($instances) > 1) {

                // we should not tolerate any errors here - problems might appear later

                throw new \moodle_exception('morethanonerecordinfetch', 'debug');

            }

            return reset($instances);

        } else {

            return false;

        }

    }

    /**

     * Factory method - uses the parameters to retrieve all matching instances from the DB.

     *

     * @final

     * @param string $table The table name to fetch from

     * @param string $classname The class that you want the result instantiated as

     * @param array $params Any params required to select the desired row

     * @return mixed array of object instances or false if not found

     */

    public static function fetch_all_helper($table, $classname, $params) {

        $instance = new $classname();

        $classvars = (array)$instance;

        $params    = (array)$params;

        $wheresql = array();

        $dbparams = array();

        foreach ($params as $var=>$value) {

            if (!in_array($var, $instance->required_fields) and !array_key_exists($var, $instance->optional_fields)) {

                continue;

            }

            if (is_null($value)) {

                $wheresql[] = " $var IS NULL ";

            } else {

                $wheresql[] = " $var = ? ";

                $dbparams[] = $value;

            }

        }

        if (empty($wheresql)) {

            $wheresql = '';

        } else {

            $wheresql = implode("AND", $wheresql);

        }

        global $DB;

        if ($datas = $DB->get_records_select($table, $wheresql, $dbparams)) {

            $result = array();

            foreach($datas as $data) {

                $instance = new $classname();

                self::set_properties($instance, $data);

                $result[$instance->id] = $instance;

            }

            return $result;

        } else {

            return false;

        }

    }

    /**

     * Updates this object in the Database, based on its object variables. ID must be set.

     *

     * @return bool success

     */

    public function update() {

        global $DB;

        if (empty($this->id)) {

            debugging('Can not update data object, no id!');

            return false;

        }

        $data = $this->get_record_data();

        $DB->update_record($this->table, $data);

        $this->notify_changed(false);

        return true;

    }

    /**

     * Deletes this object from the database.

     *

     * @return bool success

     */

    public function delete() {

        global $DB;

        if (empty($this->id)) {

            debugging('Can not delete data object, no id!');

            return false;

        }

        $data = $this->get_record_data();

        if ($DB->delete_records($this->table, array('id'=>$this->id))) {

            $this->notify_changed(true);

            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 data 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.

     *

     * @return int PK ID if successful, false otherwise

     */

    public function insert() {

        global $DB;

        if (!empty($this->id)) {

            debugging("Data 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();

        $this->notify_changed(false);

        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 for success, false otherwise.

     */

    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;

        }

        self::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.

     *

     * @final

     * @param data_object $instance

     * @param array $params

     */

    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 Set this to true if it has been deleted.

     */

    public function notify_changed($deleted) {

    }

}