From 0aea55c3e6874f009c4b33829ec0b15b944bee62 Mon Sep 17 00:00:00 2001 From: Alexander Van der Bellen Date: Wed, 22 Nov 2023 12:04:25 +0800 Subject: [PATCH] MDL-79151 backup: Add custom field backup and restore API --- backup/moodle2/backup_stepslib.php | 1 + backup/moodle2/restore_stepslib.php | 6 +- course/classes/customfield/course_handler.php | 4 +- customfield/classes/data_controller.php | 21 +++ customfield/classes/handler.php | 37 ++++- .../textarea/classes/data_controller.php | 31 +++++ .../field/textarea/tests/plugin_test.php | 127 ++++++++++++++++++ customfield/upgrade.txt | 8 ++ group/classes/customfield/group_handler.php | 4 +- .../classes/customfield/grouping_handler.php | 4 +- .../classes/customfield/question_handler.php | 6 +- 11 files changed, 241 insertions(+), 8 deletions(-) diff --git a/backup/moodle2/backup_stepslib.php b/backup/moodle2/backup_stepslib.php index 4466c1db6af..e5496e40874 100644 --- a/backup/moodle2/backup_stepslib.php +++ b/backup/moodle2/backup_stepslib.php @@ -559,6 +559,7 @@ class backup_course_structure_step extends backup_structure_step { $handler = core_course\customfield\course_handler::create(); $fieldsforbackup = $handler->get_instance_data_for_backup($this->task->get_courseid()); + $handler->backup_define_structure($this->task->get_courseid(), $customfield); $customfield->set_source_array($fieldsforbackup); // Some annotations diff --git a/backup/moodle2/restore_stepslib.php b/backup/moodle2/restore_stepslib.php index a715c372035..27dc0c946f0 100644 --- a/backup/moodle2/restore_stepslib.php +++ b/backup/moodle2/restore_stepslib.php @@ -2010,7 +2010,11 @@ class restore_course_structure_step extends restore_structure_step { */ public function process_customfield($data) { $handler = core_course\customfield\course_handler::create(); - $handler->restore_instance_data_from_backup($this->task, $data); + $newid = $handler->restore_instance_data_from_backup($this->task, $data); + + if ($newid) { + $handler->restore_define_structure($this, $newid, $data['id']); + } } /** diff --git a/course/classes/customfield/course_handler.php b/course/classes/customfield/course_handler.php index 50cc977a925..99b16ded926 100644 --- a/course/classes/customfield/course_handler.php +++ b/course/classes/customfield/course_handler.php @@ -215,6 +215,8 @@ class course_handler extends \core_customfield\handler { * * @param \restore_task $task * @param array $data + * + * @return int|void Conditionally returns the ID of the created or updated record. */ public function restore_instance_data_from_backup(\restore_task $task, array $data) { $courseid = $task->get_courseid(); @@ -235,7 +237,7 @@ class course_handler extends \core_customfield\handler { $d->set('contextid', $context->id); $d->save(); } - return; + return $d->get('id'); } } } diff --git a/customfield/classes/data_controller.php b/customfield/classes/data_controller.php index a0393e8515b..3c51d77c6fe 100644 --- a/customfield/classes/data_controller.php +++ b/customfield/classes/data_controller.php @@ -24,6 +24,7 @@ namespace core_customfield; +use backup_nested_element; use core_customfield\output\field_data; defined('MOODLE_INTERNAL') || die; @@ -363,6 +364,26 @@ abstract class data_controller { } } + /** + * Callback for backup, allowing custom fields to add additional data to the backup. + * It is not an abstract method for backward compatibility reasons. + * + * @param \backup_nested_element $customfieldelement The custom field element to be backed up. + */ + public function backup_define_structure(backup_nested_element $customfieldelement): void { + } + + /** + * Callback for restore, allowing custom fields to restore additional data from the backup. + * It is not an abstract method for backward compatibility reasons. + * + * @param \restore_structure_step $step The restore step instance. + * @param int $newid The new ID for the custom field data after restore. + * @param int $oldid The original ID of the custom field data before backup. + */ + public function restore_define_structure(\restore_structure_step $step, int $newid, int $oldid): void { + } + /** * Persistent to_record parser. * diff --git a/customfield/classes/handler.php b/customfield/classes/handler.php index 2d81404bb1c..a6cd753a2ab 100644 --- a/customfield/classes/handler.php +++ b/customfield/classes/handler.php @@ -24,6 +24,7 @@ namespace core_customfield; +use backup_nested_element; use core_customfield\output\field_data; use stdClass; @@ -496,6 +497,37 @@ abstract class handler { return $this->can_view($field, $instanceid) || $this->can_edit($field, $instanceid); } + /** + * Run the custom field backup callback for each controller. + * + * @param int $instanceid The instance ID. + * @param \backup_nested_element $customfieldselement The custom field element to be backed up. + */ + public function backup_define_structure(int $instanceid, backup_nested_element $customfieldselement): void { + $datacontrollers = $this->get_instance_data($instanceid); + + foreach ($datacontrollers as $controller) { + if ($this->can_backup($controller->get_field(), $instanceid)) { + $controller->backup_define_structure($customfieldselement); + } + } + } + + /** + * Run the custom field restore callback for each controller. + * + * @param \restore_structure_step $step The restore step instance. + * @param int $newid The new ID for the custom field data after restore. + * @param int $oldid The original ID of the custom field data before backup. + */ + public function restore_define_structure(\restore_structure_step $step, int $newid, int $oldid): void { + $datacontrollers = $this->get_instance_data($newid); + + foreach ($datacontrollers as $controller) { + $controller->restore_define_structure($step, $newid, $oldid); + } + } + /** * Get raw data associated with all fields current user can view or edit * @@ -708,11 +740,12 @@ abstract class handler { /** * Creates or updates custom field data for a instanceid from backup data. - * - * The handlers have to override it if they support backup + * The handlers have to override it if they support backup. * * @param \restore_task $task * @param array $data + * + * @return int|void Implementations should conditionally return the ID of the created or updated record. */ public function restore_instance_data_from_backup(\restore_task $task, array $data) { throw new \coding_exception('Must be implemented in the handler'); diff --git a/customfield/field/textarea/classes/data_controller.php b/customfield/field/textarea/classes/data_controller.php index b5cb10dbf52..f3eb5af074e 100644 --- a/customfield/field/textarea/classes/data_controller.php +++ b/customfield/field/textarea/classes/data_controller.php @@ -24,6 +24,8 @@ namespace customfield_textarea; +use backup_nested_element; + defined('MOODLE_INTERNAL') || die; /** @@ -191,6 +193,35 @@ class data_controller extends \core_customfield\data_controller { return $this->get_field()->get_configdata_property('defaultvalue'); } + /** + * Implement the backup callback for the custom field element. + * This includes any embedded files in the custom field element. + * + * @param \backup_nested_element $customfieldelement The custom field element to be backed up. + */ + public function backup_define_structure(backup_nested_element $customfieldelement): void { + $annotations = $customfieldelement->get_file_annotations(); + + if (!isset($annotations['customfield_textarea']['value'])) { + $customfieldelement->annotate_files('customfield_textarea', 'value', 'id'); + } + } + + /** + * Implement the restore callback for the custom field element. + * This includes restoring any embedded files in the custom field element. + * + * @param \restore_structure_step $step The restore step instance. + * @param int $newid The new ID for the custom field data after restore. + * @param int $oldid The original ID of the custom field data before backup. + */ + public function restore_define_structure(\restore_structure_step $step, int $newid, int $oldid): void { + if (!$step->get_mappingid('customfield_data', $oldid)) { + $step->set_mapping('customfield_data', $oldid, $newid, true); + $step->add_related_files('customfield_textarea', 'value', 'customfield_data'); + } + } + /** * Returns value in a human-readable format * diff --git a/customfield/field/textarea/tests/plugin_test.php b/customfield/field/textarea/tests/plugin_test.php index 884e230a945..df27b1175d2 100644 --- a/customfield/field/textarea/tests/plugin_test.php +++ b/customfield/field/textarea/tests/plugin_test.php @@ -18,6 +18,9 @@ namespace customfield_textarea; use core_customfield_generator; use core_customfield_test_instance_form; +use context_user; +use context_course; +use context_system; /** * Functional test for customfield_textarea @@ -192,4 +195,128 @@ class plugin_test extends \advanced_testcase { public function test_delete() { $this->cfcat->get_handler()->delete_all(); } + + /** + * Test embedded file backup and restore. + * + * @covers \customfield_textarea\data_controller::backup_define_structure + * @covers \customfield_textarea\data_controller::backup_restore_structure + */ + public function test_embedded_file_backup_and_restore(): void { + global $CFG, $USER, $DB; + require_once($CFG->dirroot . '/customfield/tests/fixtures/test_instance_form.php'); + $this->setAdminUser(); + $handler = $this->cfcat->get_handler(); + + // Create a file. + $fs = get_file_storage(); + $filerecord = [ + 'contextid' => context_user::instance($USER->id)->id, + 'component' => 'user', + 'filearea' => 'draft', + 'itemid' => file_get_unused_draft_itemid(), + 'filepath' => '/', + 'filename' => 'mytextfile.txt', + ]; + $fs->create_file_from_string($filerecord, 'Some text contents'); + + // Add the file to the custom field. + $submitdata = (array) $this->courses[1]; + $submitdata['customfield_myfield1_editor'] = [ + 'text' => 'Here is a file: @@PLUGINFILE@@/mytextfile.txt', + 'format' => FORMAT_HTML, + 'itemid' => $filerecord['itemid'], + ]; + + // Set the required field and submit. + $submitdata['customfield_myfield2_editor'] = ['text' => 'Some text', 'format' => FORMAT_HTML]; + core_customfield_test_instance_form::mock_submit($submitdata, []); + $form = new core_customfield_test_instance_form('POST', + ['handler' => $handler, 'instance' => $this->courses[1]]); + $this->assertTrue($form->is_validated()); + + $data = $form->get_data(); + $this->assertNotEmpty($data->customfield_myfield1_editor); + $this->assertNotEmpty($data->customfield_myfield2_editor); + $handler->instance_form_save($data); + + // Check if the draft file exists. + $context = context_course::instance($this->courses[1]->id); + $file = $fs->get_file($filerecord['contextid'], $filerecord['component'], $filerecord['filearea'], $filerecord['itemid'], + $filerecord['filepath'], $filerecord['filename']); + $this->assertNotEmpty($file); + + // Check if the permanent file exists. + $file = $fs->get_file($context->id, 'customfield_textarea', 'value', $this->cfdata[1]->get('id'), '/', 'mytextfile.txt'); + $this->assertNotEmpty($file); + + // Backup and restore the course. + $backupid = $this->backup($this->courses[1]); + $newcourseid = $this->restore($backupid, $this->courses[1], '_copy'); + + $newcontext = context_course::instance($newcourseid); + + $newcfdata = $DB->get_record('customfield_data', ['instanceid' => $newcourseid, 'fieldid' => $this->cfields[1]->get('id')]); + + // Check if the permanent file exists in the new course after restore. + $file = $fs->get_file($newcontext->id, 'customfield_textarea', 'value', $newcfdata->id, '/', 'mytextfile.txt'); + $this->assertNotEmpty($file); + } + + /** + * Backs a course up to temp directory. + * + * @param \stdClass $course Course object to backup + * @return string ID of backup + */ + protected function backup($course): string { + global $USER, $CFG; + require_once($CFG->dirroot . '/backup/util/includes/backup_includes.php'); + + // Turn off file logging, otherwise it can't delete the file (Windows). + $CFG->backup_file_logger_level = \backup::LOG_NONE; + + // Do backup with default settings. MODE_IMPORT means it will just + // create the directory and not zip it. + $bc = new \backup_controller(\backup::TYPE_1COURSE, $course->id, + \backup::FORMAT_MOODLE, \backup::INTERACTIVE_NO, \backup::MODE_IMPORT, + $USER->id); + $bc->get_plan()->get_setting('users')->set_status(\backup_setting::NOT_LOCKED); + $bc->get_plan()->get_setting('users')->set_value(true); + $bc->get_plan()->get_setting('logs')->set_value(true); + $backupid = $bc->get_backupid(); + + $bc->execute_plan(); + $bc->destroy(); + return $backupid; + } + + /** + * Restores a course from temp directory. + * + * @param string $backupid Backup id + * @param \stdClass $course Original course object + * @param string $suffix Suffix to add after original course shortname and fullname + * @return int New course id + * @throws \restore_controller_exception + */ + protected function restore(string $backupid, $course, string $suffix): int { + global $USER, $CFG; + require_once($CFG->dirroot . '/backup/util/includes/restore_includes.php'); + + // Do restore to new course with default settings. + $newcourseid = \restore_dbops::create_new_course( + $course->fullname . $suffix, $course->shortname . $suffix, $course->category); + $rc = new \restore_controller($backupid, $newcourseid, + \backup::INTERACTIVE_NO, \backup::MODE_GENERAL, $USER->id, + \backup::TARGET_NEW_COURSE); + $rc->get_plan()->get_setting('logs')->set_value(true); + $rc->get_plan()->get_setting('users')->set_value(true); + + $this->assertTrue($rc->execute_precheck()); + $rc->execute_plan(); + $rc->destroy(); + + return $newcourseid; + } } diff --git a/customfield/upgrade.txt b/customfield/upgrade.txt index 73d2537a7ab..d954b887c03 100644 --- a/customfield/upgrade.txt +++ b/customfield/upgrade.txt @@ -1,6 +1,14 @@ This files describes API changes in /customfield/*, Information provided here is intended especially for developers. +=== 4.4 === +* Enhance the handling of files embedded within textarea custom fields in the course backup and restore functionalities. + These files are now properly backed up when a course is backed up, and restored when the course is restored. + Other types of custom fields can also benefit from this new API. See MDL-79151 for more information. + `\core_customfield\handler::restore_instance_data_from_backup()` now conditionally returns a data_controller id and + there are two new methods, `\core_customfield\data_controller::backup_define_structure()` and + `\core_customfield\data_controller::restore_define_structure()`. + === 4.3 === * Field categories are now consistently of type `PARAM_TEXT`, ensure instance `get_formatted_name()` helper is used during output diff --git a/group/classes/customfield/group_handler.php b/group/classes/customfield/group_handler.php index dbb036a2c8e..df3a194a648 100644 --- a/group/classes/customfield/group_handler.php +++ b/group/classes/customfield/group_handler.php @@ -162,6 +162,8 @@ class group_handler extends handler { * * @param restore_task $task * @param array $data + * + * @return int|void Conditionally returns the ID of the created or updated record. */ public function restore_instance_data_from_backup(restore_task $task, array $data) { $instanceid = $data['groupid']; @@ -180,7 +182,7 @@ class group_handler extends handler { $d->set('contextid', $context->id); $d->save(); } - return; + return $d->get('id'); } } } diff --git a/group/classes/customfield/grouping_handler.php b/group/classes/customfield/grouping_handler.php index a66b97c4abb..3fdac037871 100644 --- a/group/classes/customfield/grouping_handler.php +++ b/group/classes/customfield/grouping_handler.php @@ -163,6 +163,8 @@ class grouping_handler extends handler { * * @param restore_task $task * @param array $data + * + * @return int|void Conditionally returns the ID of the created or updated record. */ public function restore_instance_data_from_backup(restore_task $task, array $data) { $instanceid = $data['groupingid']; @@ -181,7 +183,7 @@ class grouping_handler extends handler { $d->set('contextid', $context->id); $d->save(); } - return; + return $d->get('id'); } } } diff --git a/question/bank/customfields/classes/customfield/question_handler.php b/question/bank/customfields/classes/customfield/question_handler.php index 17b76e3fa52..3ee8c641ae0 100644 --- a/question/bank/customfields/classes/customfield/question_handler.php +++ b/question/bank/customfields/classes/customfield/question_handler.php @@ -303,8 +303,10 @@ class question_handler extends \core_customfield\handler { * * @param \restore_task $task * @param array $data + * + * @return int|void Conditionally returns the ID of the created or updated record. */ - public function restore_instance_data_from_backup(\restore_task $task, array $data): void { + public function restore_instance_data_from_backup(\restore_task $task, array $data) { $editablefields = $this->get_editable_fields($data['newquestion']); $records = api::get_instance_fields_data($editablefields, $data['newquestion']); @@ -322,7 +324,7 @@ class question_handler extends \core_customfield\handler { $d->set('contextid', $data['fieldcontextid']); $d->save(); } - return; + return $d->get('id'); } } }