weekly release 3.9.11+

[moodle.git] / customfield / classes / data_controller.php

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

/**
 * Customfield component data controller abstract class
 *
 * @package   core_customfield
 * @copyright 2018 Toni Barbera <toni@moodle.com>
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */

namespace core_customfield;

use core_customfield\output\field_data;

defined('MOODLE_INTERNAL') || die;

/**
 * Base class for custom fields data controllers
 *
 * This class is a wrapper around the persistent data class that allows to define
 * how the element behaves in the instance edit forms.
 *
 * Custom field plugins must define a class
 * \{pluginname}\data_controller extends \core_customfield\data_controller
 *
 * @package core_customfield
 * @copyright 2018 Toni Barbera <toni@moodle.com>
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
abstract class data_controller {
    /**
     * Data persistent
     *
     * @var data
     */
    protected $data;

    /**
     * Field that this data belongs to.
     *
     * @var field_controller
     */
    protected $field;

    /**
     * data_controller constructor.
     *
     * @param int $id
     * @param \stdClass|null $record
     */
    public function __construct(int $id, \stdClass $record) {
        $this->data = new data($id, $record);
    }

    /**
     * Creates an instance of data_controller
     *
     * Parameters $id, $record and $field can complement each other but not conflict.
     * If $id is not specified, fieldid must be present either in $record or in $field.
     * If $id is not specified, instanceid must be present in $record
     *
     * No DB queries are performed if both $record and $field are specified.

     * @param int $id
     * @param \stdClass|null $record
     * @param field_controller|null $field
     * @return data_controller
     * @throws \coding_exception
     * @throws \moodle_exception
     */
    public static function create(int $id, \stdClass $record = null, field_controller $field = null) : data_controller {
        global $DB;
        if ($id && $record) {
            // This warning really should be in persistent as well.
            debugging('Too many parameters, either id need to be specified or a record, but not both.',
                DEBUG_DEVELOPER);
        }
        if ($id) {
            $record = $DB->get_record(data::TABLE, array('id' => $id), '*', MUST_EXIST);
        } else if (!$record) {
            $record = new \stdClass();
        }

        if (!$field && empty($record->fieldid)) {
            throw new \coding_exception('Not enough parameters to initialise data_controller - unknown field');
        }
        if (!$field) {
            $field = field_controller::create($record->fieldid);
        }
        if (empty($record->fieldid)) {
            $record->fieldid = $field->get('id');
        }
        if ($field->get('id') != $record->fieldid) {
            throw new \coding_exception('Field id from the record does not match field from the parameter');
        }
        $type = $field->get('type');
        $customfieldtype = "\\customfield_{$type}\\data_controller";
        if (!class_exists($customfieldtype) || !is_subclass_of($customfieldtype, self::class)) {
            throw new \moodle_exception('errorfieldtypenotfound', 'core_customfield', '', s($type));
        }
        $datacontroller = new $customfieldtype(0, $record);
        $datacontroller->field = $field;
        return $datacontroller;
    }

    /**
     * Returns the name of the field to be used on HTML forms.
     *
     * @return string
     */
    public function get_form_element_name() : string {
        return 'customfield_' . $this->get_field()->get('shortname');
    }

    /**
     * Persistent getter parser.
     *
     * @param string $property
     * @return mixed
     */
    final public function get($property) {
        return $this->data->get($property);
    }

    /**
     * Persistent setter parser.
     *
     * @param string $property
     * @param mixed $value
     * @return data
     */
    final public function set($property, $value) {
        return $this->data->set($property, $value);
    }

    /**
     * Return the name of the field in the db table {customfield_data} where the data is stored
     *
     * Must be one of the following:
     *   intvalue - can store integer values, this field is indexed
     *   decvalue - can store decimal values
     *   shortcharvalue - can store character values up to 255 characters long, this field is indexed
     *   charvalue - can store character values up to 1333 characters long, this field is not indexed but
     *     full text search is faster than on field 'value'
     *   value - can store character values of unlimited length ("text" field in the db)
     *
     * @return string
     */
    abstract public function datafield() : string;

    /**
     * Delete data. Element can override it if related information needs to be deleted as well (such as files)
     *
     * @return bool
     */
    public function delete() {
        return $this->data->delete();
    }

    /**
     * Persistent save parser.
     *
     * @return void
     */
    public function save() {
        $this->data->save();
    }

    /**
     * Field associated with this data
     *
     * @return field_controller
     */
    public function get_field() : field_controller {
        return $this->field;
    }

    /**
     * Saves the data coming from form
     *
     * @param \stdClass $datanew data coming from the form
     */
    public function instance_form_save(\stdClass $datanew) {
        $elementname = $this->get_form_element_name();
        if (!property_exists($datanew, $elementname)) {
            return;
        }
        $value = $datanew->$elementname;
        $this->data->set($this->datafield(), $value);
        $this->data->set('value', $value);
        $this->save();
    }

    /**
     * Prepares the custom field data related to the object to pass to mform->set_data() and adds them to it
     *
     * This function must be called before calling $form->set_data($object);
     *
     * @param \stdClass $instance the instance that has custom fields, if 'id' attribute is present the custom
     *    fields for this instance will be added, otherwise the default values will be added.
     */
    public function instance_form_before_set_data(\stdClass $instance) {
        $instance->{$this->get_form_element_name()} = $this->get_value();
    }

    /**
     * Checks if the value is empty
     *
     * @param mixed $value
     * @return bool
     */
    protected function is_empty($value) : bool {
        if ($this->datafield() === 'value' || $this->datafield() === 'charvalue' || $this->datafield() === 'shortcharvalue') {
            return '' . $value === '';
        }
        return empty($value);
    }

    /**
     * Checks if the value is unique
     *
     * @param mixed $value
     * @return bool
     */
    protected function is_unique($value) : bool {
        global $DB;
        $datafield = $this->datafield();
        $where = "fieldid = ? AND {$datafield} = ?";
        $params = [$this->get_field()->get('id'), $value];
        if ($this->get('id')) {
            $where .= ' AND id <> ?';
            $params[] = $this->get('id');
        }
        return !$DB->record_exists_select('customfield_data', $where, $params);
    }

    /**
     * Called from instance edit form in validation()
     *
     * @param array $data
     * @param array $files
     * @return array array of errors
     */
    public function instance_form_validation(array $data, array $files) : array {
        $errors = [];
        $elementname = $this->get_form_element_name();
        if ($this->get_field()->get_configdata_property('uniquevalues') == 1) {
            $value = $data[$elementname];
            if (!$this->is_empty($value) && !$this->is_unique($value)) {
                $errors[$elementname] = get_string('erroruniquevalues', 'core_customfield');
            }
        }
        return $errors;
    }

    /**
     * Called from instance edit form in definition_after_data()
     *
     * @param \MoodleQuickForm $mform
     */
    public function instance_form_definition_after_data(\MoodleQuickForm $mform) {

    }

    /**
     * Used by handlers to display data on various places.
     *
     * @return string
     */
    public function display() : string {
        global $PAGE;
        $output = $PAGE->get_renderer('core_customfield');
        return $output->render(new field_data($this));
    }

    /**
     * Returns the default value as it would be stored in the database (not in human-readable format).
     *
     * @return mixed
     */
    public abstract function get_default_value();

    /**
     * Returns the value as it is stored in the database or default value if data record is not present
     *
     * @return mixed
     */
    public function get_value() {
        if (!$this->get('id')) {
            return $this->get_default_value();
        }
        return $this->get($this->datafield());
    }

    /**
     * Return the context of the field
     *
     * @return \context
     */
    public function get_context() : \context {
        if ($this->get('contextid')) {
            return \context::instance_by_id($this->get('contextid'));
        } else if ($this->get('instanceid')) {
            return $this->get_field()->get_handler()->get_instance_context($this->get('instanceid'));
        } else {
            // Context is not yet known (for example, entity is not yet created).
            return \context_system::instance();
        }
    }

    /**
     * Add a field to the instance edit form.
     *
     * @param \MoodleQuickForm $mform
     */
    public abstract function instance_form_definition(\MoodleQuickForm $mform);

    /**
     * Returns value in a human-readable format or default value if data record is not present
     *
     * This is the default implementation that most likely needs to be overridden
     *
     * @return mixed|null value or null if empty
     */
    public function export_value() {
        $value = $this->get_value();

        if ($this->is_empty($value)) {
            return null;
        }

        if ($this->datafield() === 'intvalue') {
            return (int)$value;
        } else if ($this->datafield() === 'decvalue') {
            return (float)$value;
        } else if ($this->datafield() === 'value') {
            return format_text($value, $this->get('valueformat'), ['context' => $this->get_context()]);
        } else {
            return format_string($value, true, ['context' => $this->get_context()]);
        }
    }

    /**
     * Persistent to_record parser.
     *
     * @return \stdClass
     */
    final public function to_record() {
        return $this->data->to_record();
    }
}