Tekst źródłowy strony Restore 2.0 for developers

{{Template:Development:Backup 2.0}}{{Moodle_2.0}}{{Work in progress}}

== Introduction ==

This page tries to explain, from a development perspective, '''how to implement''' the restore feature for various Moodle 2.x plugins, mainly, modules and blocks. 

In order to work with Restore 2.0 you must read the [https://docs.moodle.org/en/Development:Backup_2.0_for_developers Backup 2.0 documentation]. Everything will be crystal clear once you have read it. 

In this documentation you will learn about some points that you can not easily deduce from [https://docs.moodle.org/en/Development:Backup_2.0_for_developers Backup 2.0 documentation] concerning the Choice module.

== Coding ==
the restore is composed by two main php files: restore_choice_stepslib.php and restore_choice_activity_task.class.php
=== restore_choice_stepslib.php ===

<code php>
/**
 * Structure step to restore one choice activity
 */
class restore_choice_activity_structure_step extends restore_activity_structure_step {

    protected function define_structure() {

        $paths = array();
        $userinfo = $this->get_setting_value('userinfo');

        $paths[] = new restore_path_element('choice', '/activity/choice');
        $paths[] = new restore_path_element('choice_option', '/activity/choice/options/option');
        if ($userinfo) {
            $paths[] = new restore_path_element('choice_answer', '/activity/choice/answers/answer');
        }

        // Return the paths wrapped into standard activity structure
        return $this->prepare_activity_structure($paths);
    }

    protected function process_choice($data) {
        global $DB;

        $data = (object)$data;
        $oldid = $data->id;
        $data->course = $this->get_courseid();

        $data->timeopen = $this->apply_date_offset($data->timeopen);
        $data->timeclose = $this->apply_date_offset($data->timeclose);
        $data->timemodified = $this->apply_date_offset($data->timemodified);

        // insert the choice record
        $newitemid = $DB->insert_record('choice', $data);
        // immediately after inserting "activity" record, call this
        $this->apply_activity_instance($newitemid);
    }

    protected function process_choice_option($data) {
        global $DB;

        $data = (object)$data;
        $oldid = $data->id;

        $data->choiceid = $this->get_new_parentid('choice');
        $data->timemodified = $this->apply_date_offset($data->timemodified);

        $newitemid = $DB->insert_record('choice_options', $data);
        $this->set_mapping('choice_option', $oldid, $newitemid);
    }

    protected function process_choice_answer($data) {
        global $DB;

        $data = (object)$data;
        $oldid = $data->id;

        $data->choiceid = $this->get_new_parentid('choice');
        $data->optionid = $this->get_mappingid('choice_option', $oldid);
        $data->userid = $this->get_mappingid('user', $data->userid);
        $data->timemodified = $this->apply_date_offset($data->timemodified);

        $newitemid = $DB->insert_record('choice_answers', $data);
        // No need to save this mapping as far as nothing depend on it
        // (child paths, file areas nor links decoder)
    }

    protected function after_execute() {
        // Add choice related files, no need to match by itemname (just internally handled context)
        $this->add_related_files('mod_choice', 'intro', null);
    }
}
</code>

=== restore_choice_activity_task.class.php ===
<code php>
/**
 * choice restore task that provides all the settings and steps to perform one
 * complete restore of the activity
 */
class restore_choice_activity_task extends restore_activity_task {

    /**
     * Define (add) particular settings this activity can have
     */
    protected function define_my_settings() {
        // No particular settings for this activity
    }

    /**
     * Define (add) particular steps this activity can have
     */
    protected function define_my_steps() {
        // Choice only has one structure step
        $this->add_step(new restore_choice_activity_structure_step('choice_structure', 'choice.xml'));
    }

    /**
     * Define the contents in the activity that must be
     * processed by the link decoder
     */
    static public function define_decode_contents() {
        $contents = array();

        $contents[] = new restore_decode_content('choice', array('intro'), 'choice');

        return $contents;
    }

    /**
     * Define the decoding rules for links belonging
     * to the activity to be executed by the link decoder
     */
    static public function define_decode_rules() {
        $rules = array();

        $rules[] = new restore_decode_rule('CHOICEVIEWBYID', '/mod/choice/view.php?id=$1', 'course_module');
        $rules[] = new restore_decode_rule('CHOICEINDEX', '/mod/choice/index.php?id=$1', 'course');

        return $rules;

    }

    /**
     * Define the restore log rules that will be applied
     * by the {@link restore_logs_processor} when restoring
     * choice logs. It must return one array
     * of {@link restore_log_rule} objects
     */
    static public function define_restore_log_rules() {
        $rules = array();

        $rules[] = new restore_log_rule('choice', 'add', 'view.php?id={course_module}', '{choice}');
        $rules[] = new restore_log_rule('choice', 'update', 'view.php?id={course_module}', '{choice}');
        $rules[] = new restore_log_rule('choice', 'view', 'view.php?id={course_module}', '{choice}');
        $rules[] = new restore_log_rule('choice', 'choose', 'view.php?id={course_module}', '{choice}');
        $rules[] = new restore_log_rule('choice', 'choose again', 'view.php?id={course_module}', '{choice}');
        $rules[] = new restore_log_rule('choice', 'report', 'report.php?id={course_module}', '{choice}');

        return $rules;
    }

    /**
     * Define the restore log rules that will be applied
     * by the {@link restore_logs_processor} when restoring
     * course logs. It must return one array
     * of {@link restore_log_rule} objects
     *
     * Note this rules are applied when restoring course logs
     * by the restore final task, but are defined here at
     * activity level. All them are rules not linked to any module instance (cmid = 0)
     */
    static public function define_restore_log_rules_for_course() {
        $rules = array();

        // Fix old wrong uses (missing extension)
        $rules[] = new restore_log_rule('choice', 'view all', 'index?id={course}', null,
                                        null, null, 'index.php?id={course}');
        $rules[] = new restore_log_rule('choice', 'view all', 'index.php?id={course}', null);

        return $rules;
    }

}
</code>

'''define_restore_log_rules''': it covers all the "mandatory" log actions, performing {course_module} and {choice} mappings properly. Note that names between curly brackets instruct the log processor to look in the mapping tables for item = name between brackets. Of course, other modules like forum, has a lot of rules, with more complex mappings and so on. Choice is pretty basic.

'''define_restore_log_rules_for_course''': choice module has the 1st rule because, while implementing restore, we discovered one bug causing URLs to be written in the logs table WITHOUT the .php in the URL, hence choice has that extra rule (that uses the 5-8 params, to REWRITE the URL to be inserted on restore). But that was one problem with choices only, afaik, so you probably would not need it in your own module.

== Automatically triggering restore in code ==

As with backup it is possible to automatically trigger a restore for a course (or activity or anything else you can back up). Here is how to restore a course backup into a new course:

# Put the backup files in a specific folder: $CFG->dataroot/temp/backup/$folder, where $folder is a random or unused unique id.
# Decide on the course shortname, fullname, and category id for restore (course must not already exist).
# Run the following code:

<code php>
        // Transaction
        $transaction = $DB->start_delegated_transaction();
 
        // Create new course
        $courseid = restore_dbops::create_new_course($fullname, $shortname, $categoryid);
 
        // Restore backup into course
        $controller = new restore_controller($folder, $courseid, 
                backup::INTERACTIVE_NO, backup::MODE_SAMESITE, $USER->id,
                backup::TARGET_NEW_COURSE);
        $controller->execute_precheck();
        $controller->execute_plan();
 
        // Commit
        $transaction->allow_commit();
</code>

Note:

* The transaction is used so that if backup fails, the course isn't created.
* The MODE_SAMESITE option is used if restoring a backup which comes from the same site, otherwise MODE_GENERAL might be used.

== Code that runs after restore ==

If you are writing a restore task for an activity module, your code is all executed while the system is restoring that module. For example, the <tt>after_execute</tt>  method in your <tt>restore_mymodule_activity_structure_step</tt> class is called immediately after all the other restore functions in that step are finished.

=== The problem ===

Usually this is correct, but in some situations you may need to have an activity module restore that depends in some way on another activity module or on a course section other than the one the module belongs to. Depending on the order within the course, in some cases the other module or section has not yet been restored, so this is a problem.

The code that may not work as a result is code that tries to convert from an 'old' course-module ID or section ID into a 'new' one:

 $newcmid = $this->get_mappingid('course_module', $oldcmid);
 $newsectionid = $this->get_mappingid('course_section', $oldsectionid);

These functions will return false if the relevant course-module or section has not yet been restored.

=== The solution ===

You can have a method called <tt>after_restore</tt> inside your TASK (not step) class, <tt>restore_mymodule_activity_task</tt>.

 public function after_restore() {
     // Do something at end of restore
 }

In this method you can carry out necessary finishing tasks such as updating course-module and section IDs (using code like the above).

=== Warning ===

You should do as little as possible in this method, and be aware that using it may mean your activity module does not function correctly in some cases.

* It is possible to backup and restore a single module, or a section, rather than a whole course. 
* This function (backing up a single module) may also be used to support other upcoming features such as the 'copy activity' feature.

If somebody backs up your activity as a single activity, then obviously any such dependencies will not be included. There is currently no way to indicate that your module has any dependencies. So the backup and restore will go ahead but, once again, the <tt>get_mappingid</tt> function will return false.

At present the best way to handle this is to add a message to the restore log (which will not currently be displayed anywhere, but this might change):

 $this->get_logger()->process("Failed to restore dependency in mymodule '$name'. " .
         "Backup and restore will not work correctly unless you include the dependent module.",
         backup::LOG_ERROR);