Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.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/>.

/**
 * 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(); > // Ensure the "value" datafield can be safely compared across all databases.
$where = "fieldid = ? AND {$datafield} = ?";
> if ($datafield === 'value') { $params = [$this->get_field()->get('id'), $value]; > $datafield = $DB->sql_cast_to_char($datafield); 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(); } }