Merge branch 'MDL-81457-main' of https://github.com/andrewnicols/moodle
[moodle.git] / customfield / classes / field_controller.php
blob5dc580e8985efcb6718b7ca7c4619fe1f2c48892
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.
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/>.
17 /**
18 * Field controller abstract class
20 * @package core_customfield
21 * @copyright 2018 Toni Barbera <toni@moodle.com>
22 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25 namespace core_customfield;
27 defined('MOODLE_INTERNAL') || die;
29 /**
30 * Base class for custom fields controllers
32 * This class is a wrapper around the persistent field class that allows to define the field
33 * configuration
35 * Custom field plugins must define a class
36 * \{pluginname}\field_controller extends \core_customfield\field_controller
38 * @package core_customfield
39 * @copyright 2018 Toni Barbera <toni@moodle.com>
40 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
42 abstract class field_controller {
44 /**
45 * Field persistent class
47 * @var field
49 protected $field;
51 /**
52 * Category of the field.
54 * @var category_controller
56 protected $category;
58 /**
59 * Constructor.
61 * @param int $id
62 * @param \stdClass|null $record
64 public function __construct(int $id = 0, \stdClass $record = null) {
65 $this->field = new field($id, $record);
68 /**
69 * Creates an instance of field_controller
71 * Parameters $id, $record and $category can complement each other but not conflict.
72 * If $id is not specified, categoryid must be present either in $record or in $category.
73 * If $id is not specified, type must be present in $record
75 * No DB queries are performed if both $record and $category are specified.
77 * @param int $id
78 * @param \stdClass|null $record
79 * @param category_controller|null $category
80 * @return field_controller will return the instance of the class from the customfield element plugin
81 * @throws \coding_exception
82 * @throws \moodle_exception
84 public static function create(int $id, \stdClass $record = null, category_controller $category = null): field_controller {
85 global $DB;
86 if ($id && $record) {
87 // This warning really should be in persistent as well.
88 debugging('Too many parameters, either id need to be specified or a record, but not both.',
89 DEBUG_DEVELOPER);
91 if ($id) {
92 if (!$record = $DB->get_record(field::TABLE, array('id' => $id), '*', IGNORE_MISSING)) {
93 throw new \moodle_exception('fieldnotfound', 'core_customfield');
97 if (empty($record->categoryid)) {
98 if (!$category) {
99 throw new \coding_exception('Not enough parameters to initialise field_controller - unknown category');
100 } else {
101 $record->categoryid = $category->get('id');
104 if (empty($record->type)) {
105 throw new \coding_exception('Not enough parameters to initialise field_controller - unknown field type');
108 $type = $record->type;
109 if (!$category) {
110 $category = category_controller::create($record->categoryid);
112 if ($category->get('id') != $record->categoryid) {
113 throw new \coding_exception('Category of the field does not match category from the parameter');
116 $customfieldtype = "\\customfield_{$type}\\field_controller";
117 if (!class_exists($customfieldtype) || !is_subclass_of($customfieldtype, self::class)) {
118 throw new \moodle_exception('errorfieldtypenotfound', 'core_customfield', '', s($type));
120 $fieldcontroller = new $customfieldtype(0, $record);
121 $fieldcontroller->category = $category;
122 $category->add_field($fieldcontroller);
123 return $fieldcontroller;
127 * Perform pre-processing of field values, for example those that originate from an external source (e.g. upload course tool)
129 * Override in plugin classes as necessary
131 * @param string $value
132 * @return mixed
134 public function parse_value(string $value) {
135 return $value;
139 * Validate the data on the field configuration form
141 * Plugins can override it
143 * @param array $data from the add/edit profile field form
144 * @param array $files
145 * @return array associative array of error messages
147 public function config_form_validation(array $data, $files = array()): array {
148 return array();
153 * Persistent getter parser.
155 * @param string $property
156 * @return mixed
158 final public function get(string $property) {
159 return $this->field->get($property);
163 * Persistent setter parser.
165 * @param string $property
166 * @param mixed $value
167 * @return field
169 final public function set($property, $value) {
170 return $this->field->set($property, $value);
174 * Delete a field and all associated data
176 * Plugins may override it if it is necessary to delete related data (such as files)
178 * Not that the delete() method from data_controller is not called here.
180 * @return bool
182 public function delete(): bool {
183 global $DB;
184 $DB->delete_records('customfield_data', ['fieldid' => $this->get('id')]);
185 return $this->field->delete();
189 * Save or update the persistent class to database.
191 * @return void
193 public function save() {
194 $this->field->save();
198 * Persistent to_record parser.
200 * @return \stdClass
202 final public function to_record() {
203 return $this->field->to_record();
207 * Get the category associated with this field
209 * @return category_controller
211 final public function get_category(): category_controller {
212 return $this->category;
216 * Get configdata property.
218 * @param string $property name of the property
219 * @return mixed
221 public function get_configdata_property(string $property) {
222 $configdata = $this->field->get('configdata');
223 if (!isset($configdata[$property])) {
224 return null;
226 return $configdata[$property];
230 * Returns a handler for this field
232 * @return handler
234 final public function get_handler(): handler {
235 return $this->get_category()->get_handler();
239 * Prepare the field data to set in the configuration form
241 * Plugin can override if some preprocessing required for editor or filemanager fields
243 * @param \stdClass $formdata
245 public function prepare_for_config_form(\stdClass $formdata) {
249 * Add specific settings to the field configuration form, for example "default value"
251 * @param \MoodleQuickForm $mform
253 abstract public function config_form_definition(\MoodleQuickForm $mform);
256 * Returns the field name formatted according to configuration context.
258 * @return string
260 public function get_formatted_name(): string {
261 $context = $this->get_handler()->get_configuration_context();
262 return format_string($this->get('name'), true, ['context' => $context]);
266 * Does this custom field type support being used as part of the block_myoverview
267 * custom field grouping?
268 * @return bool
270 public function supports_course_grouping(): bool {
271 return false;
275 * If this field supports course filtering, then this function needs overriding to
276 * return the formatted values for this.
277 * @param array $values the used values that need grouping
278 * @return array
280 public function course_grouping_format_values($values): array {
281 return [];