moodle/customfield/classes/field_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/>.

/**
 * Field 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;

defined('MOODLE_INTERNAL') || die;

/**
 * Base class for custom fields controllers
 *
 * This class is a wrapper around the persistent field class that allows to define the field
 * configuration
 *
 * Custom field plugins must define a class
 * \{pluginname}\field_controller extends \core_customfield\field_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 field_controller {

    /**
     * Field persistent class
     *
     * @var field
     */
    protected $field;

    /**
     * Category of the field.
     *
     * @var category_controller
     */
    protected $category;

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

    /**
     * Creates an instance of field_controller
     *
     * Parameters $id, $record and $category can complement each other but not conflict.
     * If $id is not specified, categoryid must be present either in $record or in $category.
     * If $id is not specified, type must be present in $record
     *
     * No DB queries are performed if both $record and $category are specified.
     *
     * @param int $id
     * @param \stdClass|null $record
     * @param category_controller|null $category
     * @return field_controller will return the instance of the class from the customfield element plugin
     * @throws \coding_exception
     * @throws \moodle_exception
     */
    public static function create(int $id, \stdClass $record = null, category_controller $category = null): field_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) {
            if (!$record = $DB->get_record(field::TABLE, array('id' => $id), '*', IGNORE_MISSING)) {
                throw new \moodle_exception('fieldnotfound', 'core_customfield');
            }
        }

        if (empty($record->categoryid)) {
            if (!$category) {
                throw new \coding_exception('Not enough parameters to initialise field_controller - unknown category');
            } else {
                $record->categoryid = $category->get('id');
            }
        }
        if (empty($record->type)) {
            throw new \coding_exception('Not enough parameters to initialise field_controller - unknown field type');
        }

        $type = $record->type;
        if (!$category) {
            $category = category_controller::create($record->categoryid);
        }
        if ($category->get('id') != $record->categoryid) {
            throw new \coding_exception('Category of the field does not match category from the parameter');
        }

        $customfieldtype = "\\customfield_{$type}\\field_controller";
        if (!class_exists($customfieldtype) || !is_subclass_of($customfieldtype, self::class)) {
            throw new \moodle_exception('errorfieldtypenotfound', 'core_customfield', '', s($type));
        }
        $fieldcontroller = new $customfieldtype(0, $record);
        $fieldcontroller->category = $category;
        $category->add_field($fieldcontroller);
        return $fieldcontroller;
    }

    /**
     * Perform pre-processing of field values, for example those that originate from an external source (e.g. upload course tool)
     *
     * Override in plugin classes as necessary
     *
     * @param string $value
     * @return mixed
     */
    public function parse_value(string $value) {
        return $value;
    }

    /**
     * Validate the data on the field configuration form
     *
     * Plugins can override it
     *
     * @param array $data from the add/edit profile field form
     * @param array $files
     * @return array associative array of error messages
     */
    public function config_form_validation(array $data, $files = array()): array {
        return array();
    }


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

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

    /**
     * Delete a field and all associated data
     *
     * Plugins may override it if it is necessary to delete related data (such as files)
     *
     * Not that the delete() method from data_controller is not called here.
     *
     * @return bool
     */
    public function delete(): bool {
        global $DB;
        $DB->delete_records('customfield_data', ['fieldid' => $this->get('id')]);
        return $this->field->delete();
    }

    /**
     * Save or update the persistent class to database.
     *
     * @return void
     */
    public function save() {
        $this->field->save();
    }

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

    /**
     * Get the category associated with this field
     *
     * @return category_controller
     */
    final public function get_category(): category_controller {
        return $this->category;
    }

    /**
     * Get configdata property.
     *
     * @param string $property name of the property
     * @return mixed
     */
    public function get_configdata_property(string $property) {
        $configdata = $this->field->get('configdata');
        if (!isset($configdata[$property])) {
            return null;
        }
        return $configdata[$property];
    }

    /**
     * Returns a handler for this field
     *
     * @return handler
     */
    final public function get_handler(): handler {
        return $this->get_category()->get_handler();
    }

    /**
     * Prepare the field data to set in the configuration form
     *
     * Plugin can override if some preprocessing required for editor or filemanager fields
     *
     * @param \stdClass $formdata
     */
    public function prepare_for_config_form(\stdClass $formdata) {
    }

    /**
     * Add specific settings to the field configuration form, for example "default value"
     *
     * @param \MoodleQuickForm $mform
     */
    abstract public function config_form_definition(\MoodleQuickForm $mform);

    /**
     * Returns the field name formatted according to configuration context.
     *
     * @return string
     */
    public function get_formatted_name(): string {
        $context = $this->get_handler()->get_configuration_context();
        return format_string($this->get('name'), true, ['context' => $context]);
    }

    /**
     * Does this custom field type support being used as part of the block_myoverview
     * custom field grouping?
     * @return bool
     */
    public function supports_course_grouping(): bool {
        return false;
    }

    /**
     * If this field supports course filtering, then this function needs overriding to
     * return the formatted values for this.
     * @param array $values the used values that need grouping
     * @return array
     */
    public function course_grouping_format_values($values): array {
        return [];
    }
}