customfield/classes/api.php

   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.
  13 //
  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/>.
  16
  17 /**
  18  * Api customfield package
  19  *
  20  * @package   core_customfield
  21  * @copyright 2018 David Matamoros <davidmc@moodle.com>
  22  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23  */
  24
  25 namespace core_customfield;
  26
  27 use core\output\inplace_editable;
  28 use core_customfield\event\category_created;
  29 use core_customfield\event\category_deleted;
  30 use core_customfield\event\category_updated;
  31 use core_customfield\event\field_created;
  32 use core_customfield\event\field_deleted;
  33 use core_customfield\event\field_updated;
  34
  35 defined('MOODLE_INTERNAL') || die;
  36
  37 /**
  38  * Class api
  39  *
  40  * @package core_customfield
  41  * @copyright 2018 David Matamoros <davidmc@moodle.com>
  42  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  43  */
  44 class api {
  45
  46     /**
  47      * For the given instance and list of fields fields retrieves data associated with them
  48      *
  49      * @param field_controller[] $fields list of fields indexed by field id
  50      * @param int $instanceid
  51      * @param bool $adddefaults
  52      * @return data_controller[] array of data_controller objects indexed by fieldid. All fields are present,
  53      *    some data_controller objects may have 'id', some not
  54      *     If ($adddefaults): All fieldids are present, some data_controller objects may have 'id', some not.
  55      *     If (!$adddefaults): Only fieldids with data are present, all data_controller objects have 'id'.
  56      */
  57     public static function get_instance_fields_data(array $fields, int $instanceid, bool $adddefaults = true): array {
  58         return self::get_instances_fields_data($fields, [$instanceid], $adddefaults)[$instanceid];
  59     }
  60
  61     /**
  62      * For given list of instances and fields retrieves data associated with them
  63      *
  64      * @param field_controller[] $fields list of fields indexed by field id
  65      * @param int[] $instanceids
  66      * @param bool $adddefaults
  67      * @return data_controller[][] 2-dimension array, first index is instanceid, second index is fieldid.
  68      *     If ($adddefaults): All instanceids and all fieldids are present, some data_controller objects may have 'id', some not.
  69      *     If (!$adddefaults): All instanceids are present but only fieldids with data are present, all
  70      *         data_controller objects have 'id'.
  71      */
  72     public static function get_instances_fields_data(array $fields, array $instanceids, bool $adddefaults = true): array {
  73         global $DB;
  74
  75         // Create the results array where instances and fields order is the same as in the input arrays.
  76         $result = array_fill_keys($instanceids, array_fill_keys(array_keys($fields), null));
  77
  78         if (empty($instanceids) || empty($fields)) {
  79             return $result;
  80         }
  81
  82         // Retrieve all existing data.
  83         list($sqlfields, $params) = $DB->get_in_or_equal(array_keys($fields), SQL_PARAMS_NAMED, 'fld');
  84         list($sqlinstances, $iparams) = $DB->get_in_or_equal($instanceids, SQL_PARAMS_NAMED, 'ins');
  85         $sql = "SELECT d.*
  86                   FROM {customfield_field} f
  87                   JOIN {customfield_data} d ON (f.id = d.fieldid AND d.instanceid {$sqlinstances})
  88                  WHERE f.id {$sqlfields}";
  89         $fieldsdata = $DB->get_recordset_sql($sql, $params + $iparams);
  90         foreach ($fieldsdata as $data) {
  91             $result[$data->instanceid][$data->fieldid] = data_controller::create(0, $data, $fields[$data->fieldid]);
  92         }
  93         $fieldsdata->close();
  94
  95         if ($adddefaults) {
  96             // Add default data where it was not retrieved.
  97             foreach ($instanceids as $instanceid) {
  98                 foreach ($fields as $fieldid => $field) {
  99                     if ($result[$instanceid][$fieldid] === null) {
 100                         $result[$instanceid][$fieldid] =
 101                             data_controller::create(0, (object)['instanceid' => $instanceid], $field);
 102                     }
 103                 }
 104             }
 105         } else {
 106             // Remove null-placeholders for data that was not retrieved.
 107             foreach ($instanceids as $instanceid) {
 108                 $result[$instanceid] = array_filter($result[$instanceid]);
 109             }
 110         }
 111
 112         return $result;
 113     }
 114
 115     /**
 116      * Retrieve a list of all available custom field types
 117      *
 118      * @return   array   a list of the fieldtypes suitable to use in a select statement
 119      */
 120     public static function get_available_field_types() {
 121         $fieldtypes = array();
 122
 123         $plugins = \core\plugininfo\customfield::get_enabled_plugins();
 124         foreach ($plugins as $type => $unused) {
 125             $fieldtypes[$type] = get_string('pluginname', 'customfield_' . $type);
 126         }
 127         asort($fieldtypes);
 128
 129         return $fieldtypes;
 130     }
 131
 132     /**
 133      * Updates or creates a field with data that came from a form
 134      *
 135      * @param field_controller $field
 136      * @param \stdClass $formdata
 137      */
 138     public static function save_field_configuration(field_controller $field, \stdClass $formdata) {
 139         foreach ($formdata as $key => $value) {
 140             if ($key === 'configdata' && is_array($formdata->configdata)) {
 141                 $field->set($key, json_encode($value));
 142             } else if ($key === 'id' || ($key === 'type' && $field->get('id'))) {
 143                 continue;
 144             } else if (field::has_property($key)) {
 145                 $field->set($key, $value);
 146             }
 147         }
 148
 149         $isnewfield = empty($field->get('id'));
 150
 151         // Process files in description.
 152         if (isset($formdata->description_editor)) {
 153             if (!$field->get('id')) {
 154                 // We need 'id' field to store files used in description.
 155                 $field->save();
 156             }
 157
 158             $data = (object) ['description_editor' => $formdata->description_editor];
 159             $textoptions = $field->get_handler()->get_description_text_options();
 160             $data = file_postupdate_standard_editor($data, 'description', $textoptions, $textoptions['context'],
 161                 'core_customfield', 'description', $field->get('id'));
 162             $field->set('description', $data->description);
 163             $field->set('descriptionformat', $data->descriptionformat);
 164         }
 165
 166         // Save the field.
 167         $field->save();
 168
 169         if ($isnewfield) {
 170             // Move to the end of the category.
 171             self::move_field($field, $field->get('categoryid'));
 172         }
 173
 174         if ($isnewfield) {
 175             field_created::create_from_object($field)->trigger();
 176         } else {
 177             field_updated::create_from_object($field)->trigger();
 178         }
 179     }
 180
 181     /**
 182      * Change fields sort order, move field to another category
 183      *
 184      * @param field_controller $field field that needs to be moved
 185      * @param int $categoryid category that needs to be moved
 186      * @param int $beforeid id of the category this category needs to be moved before, 0 to move to the end
 187      */
 188     public static function move_field(field_controller $field, int $categoryid, int $beforeid = 0) {
 189         global $DB;
 190
 191         if ($field->get('categoryid') != $categoryid) {
 192             // Move field to another category. Validate that this category exists and belongs to the same component/area/itemid.
 193             $category = $field->get_category();
 194             $DB->get_record(category::TABLE, [
 195                 'component' => $category->get('component'),
 196                 'area' => $category->get('area'),
 197                 'itemid' => $category->get('itemid'),
 198                 'id' => $categoryid], 'id', MUST_EXIST);
 199             $field->set('categoryid', $categoryid);
 200             $field->save();
 201             field_updated::create_from_object($field)->trigger();
 202         }
 203
 204         // Reorder fields in the target category.
 205         $records = $DB->get_records(field::TABLE, ['categoryid' => $categoryid], 'sortorder, id', '*');
 206
 207         $id = $field->get('id');
 208         $fieldsids = array_values(array_diff(array_keys($records), [$id]));
 209         $idx = $beforeid ? array_search($beforeid, $fieldsids) : false;
 210         if ($idx === false) {
 211             // Set as the last field.
 212             $fieldsids = array_merge($fieldsids, [$id]);
 213         } else {
 214             // Set before field with id $beforeid.
 215             $fieldsids = array_merge(array_slice($fieldsids, 0, $idx), [$id], array_slice($fieldsids, $idx));
 216         }
 217
 218         foreach (array_values($fieldsids) as $idx => $fieldid) {
 219             // Use persistent class to update the sortorder for each field that needs updating.
 220             if ($records[$fieldid]->sortorder != $idx) {
 221                 $f = ($fieldid == $id) ? $field : new field(0, $records[$fieldid]);
 222                 $f->set('sortorder', $idx);
 223                 $f->save();
 224             }
 225         }
 226     }
 227
 228     /**
 229      * Delete a field
 230      *
 231      * @param field_controller $field
 232      */
 233     public static function delete_field_configuration(field_controller $field): bool {
 234         $event = field_deleted::create_from_object($field);
 235         get_file_storage()->delete_area_files($field->get_handler()->get_configuration_context()->id, 'core_customfield',
 236             'description', $field->get('id'));
 237         $result = $field->delete();
 238         $event->trigger();
 239         return $result;
 240     }
 241
 242     /**
 243      * Returns an object for inplace editable
 244      *
 245      * @param category_controller $category category that needs to be moved
 246      * @param bool $editable
 247      * @return inplace_editable
 248      */
 249     public static function get_category_inplace_editable(category_controller $category, bool $editable = true): inplace_editable {
 250         return new inplace_editable('core_customfield',
 251                                     'category',
 252                                     $category->get('id'),
 253                                     $editable,
 254                                     $category->get_formatted_name(),
 255                                     $category->get('name'),
 256                                     get_string('editcategoryname', 'core_customfield'),
 257                                     get_string('newvaluefor', 'core_form', $category->get_formatted_name())
 258         );
 259     }
 260
 261     /**
 262      * Reorder categories, move given category before another category
 263      *
 264      * @param category_controller $category category that needs to be moved
 265      * @param int $beforeid id of the category this category needs to be moved before, 0 to move to the end
 266      */
 267     public static function move_category(category_controller $category, int $beforeid = 0) {
 268         global $DB;
 269         $records = $DB->get_records(category::TABLE, [
 270             'component' => $category->get('component'),
 271             'area' => $category->get('area'),
 272             'itemid' => $category->get('itemid')
 273         ], 'sortorder, id', '*');
 274
 275         $id = $category->get('id');
 276         $categoriesids = array_values(array_diff(array_keys($records), [$id]));
 277         $idx = $beforeid ? array_search($beforeid, $categoriesids) : false;
 278         if ($idx === false) {
 279             // Set as the last category.
 280             $categoriesids = array_merge($categoriesids, [$id]);
 281         } else {
 282             // Set before category with id $beforeid.
 283             $categoriesids = array_merge(array_slice($categoriesids, 0, $idx), [$id], array_slice($categoriesids, $idx));
 284         }
 285
 286         foreach (array_values($categoriesids) as $idx => $categoryid) {
 287             // Use persistent class to update the sortorder for each category that needs updating.
 288             if ($records[$categoryid]->sortorder != $idx) {
 289                 $c = ($categoryid == $id) ? $category : category_controller::create(0, $records[$categoryid]);
 290                 $c->set('sortorder', $idx);
 291                 $c->save();
 292             }
 293         }
 294     }
 295
 296     /**
 297      * Insert or update custom field category
 298      *
 299      * @param category_controller $category
 300      */
 301     public static function save_category(category_controller $category) {
 302         $isnewcategory = empty($category->get('id'));
 303
 304         $category->save();
 305
 306         if ($isnewcategory) {
 307             // Move to the end.
 308             self::move_category($category);
 309             category_created::create_from_object($category)->trigger();
 310         } else {
 311             category_updated::create_from_object($category)->trigger();
 312         }
 313     }
 314
 315     /**
 316      * Delete a custom field category
 317      *
 318      * @param category_controller $category
 319      * @return bool
 320      */
 321     public static function delete_category(category_controller $category): bool {
 322         $event = category_deleted::create_from_object($category);
 323
 324         // Delete all fields.
 325         foreach ($category->get_fields() as $field) {
 326             self::delete_field_configuration($field);
 327         }
 328
 329         $result = $category->delete();
 330         $event->trigger();
 331         return $result;
 332     }
 333
 334     /**
 335      * Returns a list of categories with their related fields.
 336      *
 337      * @param string $component
 338      * @param string $area
 339      * @param int $itemid
 340      * @return category_controller[]
 341      */
 342     public static function get_categories_with_fields(string $component, string $area, int $itemid): array {
 343         global $DB;
 344
 345         $categories = [];
 346
 347         $options = [
 348                 'component' => $component,
 349                 'area'      => $area,
 350                 'itemid'    => $itemid
 351         ];
 352
 353         $plugins = \core\plugininfo\customfield::get_enabled_plugins();
 354         list($sqlfields, $params) = $DB->get_in_or_equal(array_keys($plugins), SQL_PARAMS_NAMED, 'param', true, null);
 355
 356         $fields = 'f.*, ' . join(', ', array_map(function($field) {
 357                 return "c.$field AS category_$field";
 358         }, array_diff(array_keys(category::properties_definition()), ['usermodified', 'timemodified'])));
 359         $sql = "SELECT $fields
 360                   FROM {customfield_category} c
 361              LEFT JOIN {customfield_field} f ON c.id = f.categoryid AND f.type $sqlfields
 362                  WHERE c.component = :component AND c.area = :area AND c.itemid = :itemid
 363               ORDER BY c.sortorder, f.sortorder";
 364         $fieldsdata = $DB->get_recordset_sql($sql, $options + $params);
 365
 366         foreach ($fieldsdata as $data) {
 367             if (!array_key_exists($data->category_id, $categories)) {
 368                 $categoryobj = new \stdClass();
 369                 foreach ($data as $key => $value) {
 370                     if (preg_match('/^category_(.*)$/', $key, $matches)) {
 371                         $categoryobj->{$matches[1]} = $value;
 372                     }
 373                 }
 374                 $category = category_controller::create(0, $categoryobj);
 375                 $categories[$categoryobj->id] = $category;
 376             } else {
 377                 $category = $categories[$data->categoryid];
 378             }
 379             if ($data->id) {
 380                 $fieldobj = new \stdClass();
 381                 foreach ($data as $key => $value) {
 382                     if (!preg_match('/^category_/', $key)) {
 383                         $fieldobj->{$key} = $value;
 384                     }
 385                 }
 386                 $field = field_controller::create(0, $fieldobj, $category);
 387             }
 388         }
 389         $fieldsdata->close();
 390
 391         return $categories;
 392     }
 393
 394     /**
 395      * Prepares the object to pass to field configuration form set_data() method
 396      *
 397      * @param field_controller $field
 398      * @return \stdClass
 399      */
 400     public static function prepare_field_for_config_form(field_controller $field): \stdClass {
 401         if ($field->get('id')) {
 402             $formdata = $field->to_record();
 403             $formdata->configdata = $field->get('configdata');
 404             // Preprocess the description.
 405             $textoptions = $field->get_handler()->get_description_text_options();
 406             file_prepare_standard_editor($formdata, 'description', $textoptions, $textoptions['context'], 'core_customfield',
 407                 'description', $formdata->id);
 408         } else {
 409             $formdata = (object)['categoryid' => $field->get('categoryid'), 'type' => $field->get('type'), 'configdata' => []];
 410         }
 411         // Allow field to do more preprocessing (usually for editor or filemanager elements).
 412         $field->prepare_for_config_form($formdata);
 413         return $formdata;
 414     }
 415
 416     /**
 417      * Get a list of the course custom fields that support course grouping in
 418      * block_myoverview
 419      * @return array $shortname => $name
 420      */
 421     public static function get_fields_supporting_course_grouping() {
 422         global $DB;
 423         $sql = "
 424             SELECT f.*
 425               FROM {customfield_field} f
 426               JOIN {customfield_category} cat ON cat.id = f.categoryid
 427              WHERE cat.component = 'core_course' AND cat.area = 'course'
 428              ORDER BY f.name
 429         ";
 430         $ret = [];
 431         $fields = $DB->get_records_sql($sql);
 432         foreach ($fields as $field) {
 433             $inst = field_controller::create(0, $field);
 434             $isvisible = $inst->get_configdata_property('visibility') == \core_course\customfield\course_handler::VISIBLETOALL;
 435             // Only visible fields to everybody supporting course grouping will be displayed.
 436             if ($inst->supports_course_grouping() && $isvisible) {
 437                 $ret[$inst->get('shortname')] = $inst->get('name');
 438             }
 439         }
 440         return $ret;
 441     }
 442 }