MDL-21432 backup 2.0 - initial commit. util dir
authorEloy Lafuente <stronk7@moodle.org>
Wed, 21 Apr 2010 09:17:06 +0000 (09:17 +0000)
committerEloy Lafuente <stronk7@moodle.org>
Wed, 21 Apr 2010 09:17:06 +0000 (09:17 +0000)
77 files changed:
backup/util/checks/backup_check.class.php [new file with mode: 0644]
backup/util/checks/simpletest/testcheck.php [new file with mode: 0644]
backup/util/dbops/backup_controller_dbops.class.php [new file with mode: 0644]
backup/util/dbops/backup_dbops.class.php [new file with mode: 0644]
backup/util/dbops/backup_plan_dbops.class.php [new file with mode: 0644]
backup/util/dbops/backup_structure_dbops.class.php [new file with mode: 0644]
backup/util/dbops/simpletest/testdbops.php [new file with mode: 0644]
backup/util/destinations/simpletest/testdestination.php [new file with mode: 0644]
backup/util/factories/backup_factory.class.php [new file with mode: 0644]
backup/util/factories/simpletest/testfactory.php [new file with mode: 0644]
backup/util/helper/backup_anonymizer_helper.class.php [new file with mode: 0644]
backup/util/helper/backup_array_iterator.class.php [new file with mode: 0644]
backup/util/helper/backup_file_manager.class.php [new file with mode: 0644]
backup/util/helper/backup_general_helper.class.php [new file with mode: 0644]
backup/util/helper/backup_helper.class.php [new file with mode: 0644]
backup/util/helper/backup_null_iterator.class.php [new file with mode: 0644]
backup/util/helper/simpletest/testhelper.php [new file with mode: 0644]
backup/util/includes/backup_includes.php [new file with mode: 0644]
backup/util/interfaces/annotable.class.php [new file with mode: 0644]
backup/util/interfaces/checksumable.class.php [new file with mode: 0644]
backup/util/interfaces/executable.class.php [new file with mode: 0644]
backup/util/interfaces/loggable.class.php [new file with mode: 0644]
backup/util/interfaces/processable.class.php [new file with mode: 0644]
backup/util/loggers/base_logger.class.php [new file with mode: 0644]
backup/util/loggers/database_logger.class.php [new file with mode: 0644]
backup/util/loggers/error_log_logger.class.php [new file with mode: 0644]
backup/util/loggers/file_logger.class.php [new file with mode: 0644]
backup/util/loggers/output_indented_logger.class.php [new file with mode: 0644]
backup/util/loggers/output_text_logger.class.php [new file with mode: 0644]
backup/util/loggers/simpletest/testlogger.php [new file with mode: 0644]
backup/util/output/output_controller.class.php [new file with mode: 0644]
backup/util/plan/backup_execution_step.class.php [new file with mode: 0644]
backup/util/plan/backup_plan.class.php [new file with mode: 0644]
backup/util/plan/backup_step.class.php [new file with mode: 0644]
backup/util/plan/backup_structure_step.class.php [new file with mode: 0644]
backup/util/plan/backup_task.class.php [new file with mode: 0644]
backup/util/plan/base_plan.class.php [new file with mode: 0644]
backup/util/plan/base_step.class.php [new file with mode: 0644]
backup/util/plan/base_task.class.php [new file with mode: 0644]
backup/util/plan/simpletest/testplan.php [new file with mode: 0644]
backup/util/plan/simpletest/teststep.php [new file with mode: 0644]
backup/util/plan/simpletest/testtask.php [new file with mode: 0644]
backup/util/settings/activity/activity_backup_setting.class.php [new file with mode: 0644]
backup/util/settings/backup_setting.class.php [new file with mode: 0644]
backup/util/settings/base_setting.class.php [new file with mode: 0644]
backup/util/settings/course/course_backup_setting.class.php [new file with mode: 0644]
backup/util/settings/root/root_backup_setting.class.php [new file with mode: 0644]
backup/util/settings/section/section_backup_setting.class.php [new file with mode: 0644]
backup/util/settings/simpletest/testsettings.php [new file with mode: 0644]
backup/util/structure/backup_attribute.class.php [new file with mode: 0644]
backup/util/structure/backup_final_element.class.php [new file with mode: 0644]
backup/util/structure/backup_nested_element.class.php [new file with mode: 0644]
backup/util/structure/backup_optigroup.class.php [new file with mode: 0644]
backup/util/structure/backup_optigroup_element.class.php [new file with mode: 0644]
backup/util/structure/backup_structure_processor.class.php [new file with mode: 0644]
backup/util/structure/base_atom.class.php [new file with mode: 0644]
backup/util/structure/base_attribute.class.php [new file with mode: 0644]
backup/util/structure/base_final_element.class.php [new file with mode: 0644]
backup/util/structure/base_nested_element.class.php [new file with mode: 0644]
backup/util/structure/base_optigroup.class.php [new file with mode: 0644]
backup/util/structure/base_processor.class.php [new file with mode: 0644]
backup/util/structure/simpletest/fixtures/structuremocks.php [new file with mode: 0644]
backup/util/structure/simpletest/testbackupstructures.php [new file with mode: 0644]
backup/util/structure/simpletest/testbaseatom.php [new file with mode: 0644]
backup/util/structure/simpletest/testbaseattribute.php [new file with mode: 0644]
backup/util/structure/simpletest/testbasefinalelement.php [new file with mode: 0644]
backup/util/structure/simpletest/testbasenestedelement.php [new file with mode: 0644]
backup/util/structure/simpletest/testbaseoptigroup.php [new file with mode: 0644]
backup/util/ui/simpletest/testui.php [new file with mode: 0644]
backup/util/xml/contenttransformer/xml_contenttransformer.class.php [new file with mode: 0644]
backup/util/xml/output/file_xml_output.class.php [new file with mode: 0644]
backup/util/xml/output/memory_xml_output.class.php [new file with mode: 0644]
backup/util/xml/output/simpletest/testoutput.php [new file with mode: 0644]
backup/util/xml/output/xml_output.class.php [new file with mode: 0644]
backup/util/xml/simpletest/fixtures/test1.xml [new file with mode: 0644]
backup/util/xml/simpletest/testwriter.php [new file with mode: 0644]
backup/util/xml/xml_writer.class.php [new file with mode: 0644]

diff --git a/backup/util/checks/backup_check.class.php b/backup/util/checks/backup_check.class.php
new file mode 100644 (file)
index 0000000..276482f
--- /dev/null
@@ -0,0 +1,93 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-factories
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Non instantiable helper class providing different backup checks
+ *
+ * This class contains various static methods available in order to easily
+ * perform a bunch of backup architecture tests
+ *
+ * TODO: Finish phpdocs
+ */
+abstract class backup_check {
+
+    public static function check_format_and_type($format, $type) {
+        global $CFG;
+
+        $file = $CFG->dirroot . '/backup/' . $format . '/backup_plan_builder.class.php';
+        if (! file_exists($file)) {
+            throw new backup_controller_exception('backup_check_unsupported_format', $format);
+        }
+        require_once($file);
+        if (!in_array($type, backup_plan_builder::supported_backup_types())) {
+            throw new backup_controller_exception('backup_check_unsupported_type', $type);
+        }
+
+        require_once($CFG->dirroot . '/backup/moodle2/backup_plan_builder.class.php');
+    }
+
+    public static function check_id($type, $id) {
+        global $DB;
+        switch ($type) {
+            case backup::TYPE_1ACTIVITY:
+                // id must exist in course_modules table
+                if (! $DB->record_exists('course_modules', array('id' => $id))) {
+                    throw new backup_controller_exception('backup_check_module_not_exists', $id);
+                }
+                break;
+            case backup::TYPE_1SECTION:
+                // id must exist in course_sections table
+                if (! $DB->record_exists('course_sections', array('id' => $id))) {
+                    throw new backup_controller_exception('backup_check_section_not_exists', $id);
+                }
+                break;
+            case backup::TYPE_1COURSE:
+                // id must exist in course table
+                if (! $DB->record_exists('course', array('id' => $id))) {
+                    throw new backup_controller_exception('backup_check_course_not_exists', $id);
+                }
+                break;
+            default:
+                throw new backup_controller_exception('backup_check_incorrect_type', $type);
+        }
+        return true;
+    }
+
+    public static function check_user($userid) {
+        global $DB;
+        // userid must exist in user table
+        if (! $DB->record_exists('user', array('id' => $userid))) {
+            throw new backup_controller_exception('backup_check_user_not_exists', $userid);
+        }
+        return true;
+    }
+
+    public static function check_security($backup_controller, $apply) {
+        if (! $backup_controller instanceof backup_controller) {
+            throw new backup_controller_exception('backup_check_security_requires_backup_controller');
+        }
+        $backup_controller->log('checking plan security', backup::LOG_INFO);
+        return true;
+    }
+}
diff --git a/backup/util/checks/simpletest/testcheck.php b/backup/util/checks/simpletest/testcheck.php
new file mode 100644 (file)
index 0000000..4631db8
--- /dev/null
@@ -0,0 +1,228 @@
+<?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/>.
+
+/**
+ * @package moodlecore
+ * @subpackage backup-tests
+ * @copyright 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+// Prevent direct access to this file
+if (!defined('MOODLE_INTERNAL')) {
+    die('Direct access to this script is forbidden.');
+}
+
+// Include all the needed stuff
+require_once($CFG->dirroot . '/backup/util/includes/backup_includes.php');
+
+/*
+ * check tests (all)
+ */
+class backup_check_test extends UnitTestCase {
+
+    public static $includecoverage = array('backup/util/checks');
+    public static $excludecoverage = array('backup/util/checks/simpletest');
+
+    protected $moduleid;  // course_modules id used for testing
+    protected $sectionid; // course_sections id used for testing
+    protected $courseid;  // course id used for testing
+    protected $userid;    // user record id
+
+    protected $errorlogloggerlevel; // To store $CFG->backup_error_log_logger_level
+    protected $fileloggerlevel; // To store level $CFG->backup_file_logger_level
+    protected $databaseloggerlevel; // To store $CFG->backup_database_logger_level
+    protected $outputindentedloggerlevel; // To store $CFG->backup_output_indented_logger_level
+    protected $fileloggerextra; // To store $CFG->backup_file_logger_extra
+    protected $fileloggerlevelextra; // To store level $CFG->backup_file_logger_level_extra
+    protected $debugging; // To store $CFG->debug
+    protected $debugdisplay; // To store $CFG->debugdisplay
+
+    function __construct() {
+        global $DB, $USER, $CFG;
+
+        $this->moduleid  = 0;
+        $this->sectionid = 0;
+        $this->courseid  = 0;
+        $this->userid = $USER->id;
+
+        // Check we have (at least) one course_module
+        if ($coursemodule = $DB->get_record('course_modules', array(), '*', IGNORE_MULTIPLE)) {
+            $this->moduleid  = $coursemodule->id;
+            $this->sectionid = $coursemodule->section;
+            $this->courseid  = $coursemodule->course;
+        }
+        parent::__construct();
+    }
+
+    function skip() {
+        $this->skipIf(empty($this->moduleid), 'backup_check_test require at least one course module to exist');
+        $this->skipIf(empty($this->sectionid),'backup_check_test require at least one course section to exist');
+        $this->skipIf(empty($this->courseid), 'backup_check_test require at least one course to exist');
+        $this->skipIf(empty($this->userid),'backup_check_test require one valid user to exist');
+    }
+
+    function setUp() {
+        global $CFG;
+        parent::setUp();
+        // Avoid any file logger to be created, we'll restore original settings on tearDown()
+        // Fetch the rest of CFG variables to be able to restore them after tests
+        // and normalize default values
+        $this->errorlogloggerlevel = isset($CFG->backup_error_log_logger_level) ? $CFG->backup_error_log_logger_level : null;
+        $CFG->backup_error_log_logger_level = backup::LOG_NONE;
+
+        $this->outputindentedloggerlevel = isset($CFG->backup_output_indented_logger_level) ? $CFG->backup_output_indented_logger_level : null;
+        $CFG->backup_output_indented_logger_level = backup::LOG_NONE;
+
+        $this->fileloggerlevel = isset($CFG->backup_file_logger_level) ? $CFG->backup_file_logger_level : null;
+        $CFG->backup_file_logger_level = backup::LOG_NONE;
+
+        $this->databaseloggerlevel = isset($CFG->backup_database_logger_level) ? $CFG->backup_database_logger_level : null;
+        $CFG->backup_database_logger_level = backup::LOG_NONE;
+
+        $this->fileloggerextra = isset($CFG->backup_file_logger_extra) ? $CFG->backup_file_logger_extra : null;
+        unset($CFG->backup_file_logger_extra);
+        $this->fileloggerlevelextra = isset($CFG->backup_file_logger_level_extra) ? $CFG->backup_file_logger_level_extra : null;
+        $CFG->backup_file_logger_level_extra = backup::LOG_NONE;
+
+        $this->debugging = isset($CFG->debug) ? $CFG->debug : null;
+        $this->debugdisplay = isset($CFG->debugdisplay) ? $CFG->debugdisplay : null;
+    }
+
+    function tearDown() {
+        global $CFG;
+        // Restore original file_logger levels
+        if ($this->errorlogloggerlevel !== null) {
+            $CFG->backup_error_log_logger_level = $this->errorlogloggerlevel;
+        } else {
+            unset($CFG->backup_error_log_logger_level);
+        }
+
+        if ($this->outputindentedloggerlevel !== null) {
+            $CFG->backup_output_indented_logger_level = $this->outputindentedloggerlevel;
+        } else {
+            unset($CFG->backup_output_indented_logger_level);
+        }
+
+        if ($this->fileloggerlevel !== null) {
+            $CFG->backup_file_logger_level = $this->fileloggerlevel;
+        } else {
+            unset($CFG->backup_file_logger_level);
+        }
+
+        if ($this->databaseloggerlevel !== null) {
+            $CFG->backup_database_logger_level = $this->databaseloggerlevel;
+        } else {
+            unset($CFG->backup_database_logger_level);
+        }
+
+        if ($this->fileloggerextra !== null) {
+            $CFG->backup_file_logger_extra = $this->fileloggerextra;
+        } else {
+            unset($CFG->backup_file_logger_extra);
+        }
+        if ($this->fileloggerlevelextra !== null) {
+            $CFG->backup_file_logger_level_extra = $this->fileloggerlevelextra;
+        } else {
+            unset($CFG->backup_file_logger_level_extra);
+        }
+        // Restore the rest of $CFG settings
+        if ($this->debugging !== null) {
+            $CFG->debug = $this->debugging;
+        } else {
+            unset($CFG->debug);
+        }
+        if ($this->debugdisplay !== null) {
+            $CFG->debugdisplay = $this->debugdisplay;
+        } else {
+            unset($CFG->debugdisplay);
+        }
+        parent::tearDown();
+    }
+
+    /*
+     * test backup_check class
+     */
+    function test_backup_check() {
+
+        // Check against existing course module/section course or fail
+        $this->assertTrue(backup_check::check_id(backup::TYPE_1ACTIVITY, $this->moduleid));
+        $this->assertTrue(backup_check::check_id(backup::TYPE_1SECTION, $this->sectionid));
+        $this->assertTrue(backup_check::check_id(backup::TYPE_1COURSE, $this->courseid));
+        $this->assertTrue(backup_check::check_user($this->userid));
+
+        // Check agains non-existing course module/section/course (0)
+        try {
+            backup_check::check_id(backup::TYPE_1ACTIVITY, 0);
+            $this->assertTrue(false, 'backup_controller_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof backup_controller_exception);
+            $this->assertEqual($e->errorcode, 'backup_check_module_not_exists');
+        }
+        try {
+            backup_check::check_id(backup::TYPE_1SECTION, 0);
+            $this->assertTrue(false, 'backup_controller_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof backup_controller_exception);
+            $this->assertEqual($e->errorcode, 'backup_check_section_not_exists');
+        }
+        try {
+            backup_check::check_id(backup::TYPE_1COURSE, 0);
+            $this->assertTrue(false, 'backup_controller_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof backup_controller_exception);
+            $this->assertEqual($e->errorcode, 'backup_check_course_not_exists');
+        }
+
+        // Try wrong type
+        try {
+            backup_check::check_id(12345678,0);
+            $this->assertTrue(false, 'backup_controller_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof backup_controller_exception);
+            $this->assertEqual($e->errorcode, 'backup_check_incorrect_type');
+        }
+
+        // Test non-existing user
+        $userid = 0;
+        try {
+            backup_check::check_user($userid);
+            $this->assertTrue(false, 'backup_controller_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof backup_controller_exception);
+            $this->assertEqual($e->errorcode, 'backup_check_user_not_exists');
+        }
+
+        // Security check tests
+        // Try to pass wrong controller
+        try {
+            backup_check::check_security(new stdclass(), true);
+            $this->assertTrue(false, 'backup_controller_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof backup_controller_exception);
+            $this->assertEqual($e->errorcode, 'backup_check_security_requires_backup_controller');
+        }
+
+        // Pass correct controller, check must return true in any case with $apply enabled
+        // and $bc must continue being mock_backup_controller
+        $bc = new backup_controller(backup::TYPE_1ACTIVITY, $this->moduleid, backup::FORMAT_MOODLE,
+                                    backup::INTERACTIVE_NO, backup::MODE_GENERAL, $this->userid);
+        $this->assertTrue(backup_check::check_security($bc, true));
+        $this->assertTrue($bc instanceof backup_controller);
+
+    }
+}
diff --git a/backup/util/dbops/backup_controller_dbops.class.php b/backup/util/dbops/backup_controller_dbops.class.php
new file mode 100644 (file)
index 0000000..7ceabbe
--- /dev/null
@@ -0,0 +1,344 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-dbops
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Non instantiable helper class providing DB support to the @backup_controller
+ *
+ * This class contains various static methods available for all the DB operations
+ * performed by the backup_controller class
+ *
+ * TODO: Finish phpdocs
+ */
+abstract class backup_controller_dbops extends backup_dbops {
+
+    public static function save_controller($controller, $checksum) {
+        global $DB;
+        // Check we are going to save one backup_controller
+        if (! $controller instanceof backup_controller) {
+            throw new backup_controller_exception('backup_controller_expected');
+        }
+        // Check checksum is ok. Sounds silly but it isn't ;-)
+        if (!$controller->is_checksum_correct($checksum)) {
+            throw new backup_dbops_exception('backup_controller_dbops_saving_checksum_mismatch');
+        }
+        // Get all the columns
+        $rec = new stdclass();
+        $rec->backupid     = $controller->get_backupid();
+        $rec->type         = $controller->get_type();
+        $rec->itemid       = $controller->get_id();
+        $rec->format       = $controller->get_format();
+        $rec->interactive  = $controller->get_interactive();
+        $rec->purpose      = $controller->get_mode();
+        $rec->userid       = $controller->get_userid();
+        $rec->status       = $controller->get_status();
+        $rec->execution    = $controller->get_execution();
+        $rec->executiontime= $controller->get_executiontime();
+        $rec->checksum     = $checksum;
+        // Serialize information
+        $rec->controller = base64_encode(serialize($controller));
+        // Send it to DB
+        if ($recexists = $DB->get_record('backup_controllers', array('backupid' => $rec->backupid))) {
+            $rec->id = $recexists->id;
+            $rec->timemodified = time();
+            $DB->update_record('backup_controllers', $rec);
+        } else {
+            $rec->timecreated = time();
+            $rec->timemodified = 0;
+            $rec->id = $DB->insert_record('backup_controllers', $rec);
+        }
+        return $rec->id;
+    }
+
+    public static function load_controller($backupid) {
+        global $DB;
+        if (! $controllerrec = $DB->get_record('backup_controllers', array('backupid' => $backupid))) {
+            throw new backup_dbops_exception('backup_controller_dbops_nonexisting');
+        }
+        $controller = unserialize(base64_decode($controllerrec->controller));
+        // Check checksum is ok. Sounds silly but it isn't ;-)
+        if (!$controller->is_checksum_correct($controllerrec->checksum)) {
+            throw new backup_dbops_exception('backup_controller_dbops_loading_checksum_mismatch');
+        }
+        return $controller;
+    }
+
+    public static function create_backup_ids_temp_table($backupid) {
+        global $CFG, $DB;
+        $dbman = $DB->get_manager(); // We are going to use database_manager services
+
+        // Note: For now we are going to load the backup_ids_template from core lib/db/install.xml
+        // that way, any change in the "template" will be applied here automatically. If this causes
+        // too much slow, we can always forget about the template and keep maintained the xmldb_table
+        // structure inline - manually - here.
+        $templatetablename = 'backup_ids_template';
+        $targettablename = 'backup_ids_temp';
+        $xmldb_file = new xmldb_file($CFG->dirroot . '/lib/db/install.xml');
+        if (!$xmldb_file->fileExists()) {
+            throw new ddl_exception('ddlxmlfileerror', null, 'File does not exist');
+        }
+        $loaded = $xmldb_file->loadXMLStructure();
+        if (!$loaded || !$xmldb_file->isLoaded()) {
+            throw new ddl_exception('ddlxmlfileerror', null, 'not loaded??');
+        }
+        $xmldb_structure = $xmldb_file->getStructure();
+        $xmldb_table = $xmldb_structure->getTable($templatetablename);
+        if (is_null($xmldb_table)) {
+            throw new ddl_exception('ddlunknowntable', null, 'The table ' . $templatetablename . ' is not defined in file ' . $file);
+        }
+        // Set default backupid (not needed but this enforce any missing backupid). That's hackery in action!
+        $xmldb_table->getField('backupid')->setDefault($backupid);
+        // Clean prev & next, we are alone
+        $xmldb_table->setNext(null);
+        $xmldb_table->setPrevious(null);
+        // Rename
+        $xmldb_table->setName($targettablename);
+
+        $dbman->create_temp_table($xmldb_table); // And create it
+    }
+
+    public static function drop_backup_ids_temp_table($backupid) {
+        global $DB;
+        $dbman = $DB->get_manager(); // We are going to use database_manager services
+
+        $targettablename = 'backup_ids_temp';
+        $table = new xmldb_table($targettablename);
+        $dbman->drop_temp_table($table); // And drop it
+    }
+
+    /**
+     * Given one type and id from controller, return the corresponding courseid
+     */
+    public static function get_courseid_from_type_id($type, $id) {
+        global $DB;
+        if ($type == backup::TYPE_1COURSE) {
+            return $id; // id is the course id
+
+        } else if ($type == backup::TYPE_1SECTION) {
+            if (! $courseid = $DB->get_field('course_sections', 'course', array('id' => $id))) {
+                throw new backup_dbops_exception('course_not_found_for_section', $id);
+            }
+            return $courseid;
+        } else if ($type == backup::TYPE_1ACTIVITY) {
+            if (! $courseid = $DB->get_field('course_modules', 'course', array('id' => $id))) {
+                throw new backup_dbops_exception('course_not_found_for_moduleid', $id);
+            }
+            return $courseid;
+        }
+    }
+
+    /**
+     * Given one activity task, return the activity information and related settings
+     * Used by get_moodle_backup_information()
+     */
+    private static function get_activity_backup_information($task) {
+
+        $contentinfo = array(
+            'moduleid'   => $task->get_moduleid(),
+            'sectionid'  => $task->get_sectionid(),
+            'modulename' => $task->get_modulename(),
+            'title'      => $task->get_name(),
+            'directory'  => 'activities/' . $task->get_modulename() . '_' . $task->get_moduleid());
+
+        // Now get activity settings
+        // Calculate prefix to find valid settings
+        $prefix = basename($contentinfo['directory']);
+        $settingsinfo = array();
+        foreach ($task->get_settings() as $setting) {
+            // Discard ones without valid prefix
+            if (strpos($setting->get_name(), $prefix) !== 0) {
+                continue;
+            }
+            // Validate level is correct (activity)
+            if ($setting->get_level() != backup_setting::ACTIVITY_LEVEL) {
+                throw new backup_controller_exception('setting_not_activity_level', $setting);
+            }
+            $settinginfo = array(
+                'level'    => 'activity',
+                'activity' => $prefix,
+                'name'     => $setting->get_name(),
+                'value'    => $setting->get_value());
+            $settingsinfo[] = (object)$settinginfo;
+        }
+        return array($contentinfo, $settingsinfo);
+    }
+
+    /**
+     * Given one section task, return the section information and related settings
+     * Used by get_moodle_backup_information()
+     */
+    private static function get_section_backup_information($task) {
+
+        $contentinfo = array(
+            'sectionid'  => $task->get_sectionid(),
+            'title'      => $task->get_name(),
+            'directory'  => 'sections/' . 'section_' . $task->get_sectionid());
+
+        // Now get section settings
+        // Calculate prefix to find valid settings
+        $prefix = basename($contentinfo['directory']);
+        $settingsinfo = array();
+        foreach ($task->get_settings() as $setting) {
+            // Discard ones without valid prefix
+            if (strpos($setting->get_name(), $prefix) !== 0) {
+                continue;
+            }
+            // Validate level is correct (section)
+            if ($setting->get_level() != backup_setting::SECTION_LEVEL) {
+                throw new backup_controller_exception('setting_not_section_level', $setting);
+            }
+            $settinginfo = array(
+                'level'    => 'section',
+                'section ' => $prefix,
+                'name'     => $setting->get_name(),
+                'value'    => $setting->get_value());
+            $settingsinfo[] = (object)$settinginfo;
+        }
+        return array($contentinfo, $settingsinfo);
+    }
+
+    /**
+     * Given one course task, return the course information and related settings
+     * Used by get_moodle_backup_information()
+     */
+    private static function get_course_backup_information($task) {
+
+        $contentinfo = array(
+            'courseid'   => $task->get_courseid(),
+            'title'      => $task->get_name(),
+            'directory'  => 'course');
+
+        // Now get course settings
+        // Calculate prefix to find valid settings
+        $prefix = basename($contentinfo['directory']);
+        $settingsinfo = array();
+        foreach ($task->get_settings() as $setting) {
+            // Discard ones without valid prefix
+            if (strpos($setting->get_name(), $prefix) !== 0) {
+                continue;
+            }
+            // Validate level is correct (course)
+            if ($setting->get_level() != backup_setting::COURSE_LEVEL) {
+                throw new backup_controller_exception('setting_not_course_level', $setting);
+            }
+            $settinginfo = array(
+                'level'    => 'course',
+                'name'     => $setting->get_name(),
+                'value'    => $setting->get_value());
+            $settingsinfo[] = (object)$settinginfo;
+        }
+        return array($contentinfo, $settingsinfo);
+    }
+
+    /**
+     * Given one root task, return the course information and related settings
+     * Used by get_moodle_backup_information()
+     */
+    private static function get_root_backup_information($task) {
+
+        // Now get root settings
+        $settingsinfo = array();
+        foreach ($task->get_settings() as $setting) {
+            // Validate level is correct (root)
+            if ($setting->get_level() != backup_setting::ROOT_LEVEL) {
+                throw new backup_controller_exception('setting_not_root_level', $setting);
+            }
+            $settinginfo = array(
+                'level'    => 'root',
+                'name'     => $setting->get_name(),
+                'value'    => $setting->get_value());
+            $settingsinfo[] = (object)$settinginfo;
+        }
+        return array(null, $settingsinfo);
+    }
+
+    /**
+     * Get details information for main moodle_backup.xml file, extracting it from
+     * the specified controller
+     */
+    public static function get_moodle_backup_information($backupid) {
+
+        $detailsinfo = array(); // Information details
+        $contentsinfo= array(); // Information about backup contents
+        $settingsinfo= array(); // Information about backup settings
+        $bc = self::load_controller($backupid); // Load controller
+
+        // Details info
+        $detailsinfo['backup_id'] = $bc->get_backupid();
+        $detailsinfo['type'] = $bc->get_type();
+        $detailsinfo['format'] = $bc->get_format();
+        $detailsinfo['interactive'] = $bc->get_interactive();
+        $detailsinfo['mode'] = $bc->get_mode();
+        $detailsinfo['execution'] = $bc->get_execution();
+        $detailsinfo['executiontime'] = $bc->get_executiontime();
+
+
+        // Init content placeholders
+        $contentsinfo['activities'] = array();
+        $contentsinfo['sections']   = array();
+        $contentsinfo['course']     = array();
+
+        // Contents info (extract information from tasks)
+        foreach ($bc->get_plan()->get_tasks() as $task) {
+
+            if ($task instanceof backup_activity_task) { // Activity task
+
+                list($contentinfo, $settings) = self::get_activity_backup_information($task);
+                $contentsinfo['activities'][] = $contentinfo;
+                $settingsinfo = array_merge($settingsinfo, $settings);
+
+            } else if ($task instanceof backup_section_task) { // Section task
+
+                list($contentinfo, $settings) = self::get_section_backup_information($task);
+                $contentsinfo['sections'][] = $contentinfo;
+                $settingsinfo = array_merge($settingsinfo, $settings);
+
+            } else if ($task instanceof backup_course_task) { // Course task
+
+                list($contentinfo, $settings) = self::get_course_backup_information($task);
+                $contentsinfo['course'][] = $contentinfo;
+                $settingsinfo = array_merge($settingsinfo, $settings);
+
+            } else if ($task instanceof backup_root_task) { // Root task
+
+                list($contentinfo, $settings) = self::get_root_backup_information($task);
+                $settingsinfo = array_merge($settingsinfo, $settings);
+            }
+        }
+
+        return array(array((object)$detailsinfo), $contentsinfo, $settingsinfo);
+    }
+
+    /**
+     * Update CFG->backup_version and CFG->backup_release if change in
+     * version is detected.
+     */
+    public static function apply_version_and_release() {
+        global $CFG;
+
+        if ($CFG->backup_version < backup::VERSION) {
+            set_config('backup_version', backup::VERSION);
+            set_config('backup_release', backup::RELEASE);
+        }
+    }
+}
diff --git a/backup/util/dbops/backup_dbops.class.php b/backup/util/dbops/backup_dbops.class.php
new file mode 100644 (file)
index 0000000..76f531c
--- /dev/null
@@ -0,0 +1,40 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-dbops
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Base abstract class for all the helper classes providing DB operations
+ *
+ * TODO: Finish phpdocs
+ */
+abstract class backup_dbops { }
+
+/*
+ * Exception class used by all the @dbops stuff
+ */
+class backup_dbops_exception extends backup_exception {
+
+    public function __construct($errorcode, $a=NULL, $debuginfo=null) {
+        parent::__construct($errorcode, 'error', '', $a, null, $debuginfo);
+    }
+}
diff --git a/backup/util/dbops/backup_plan_dbops.class.php b/backup/util/dbops/backup_plan_dbops.class.php
new file mode 100644 (file)
index 0000000..f91c007
--- /dev/null
@@ -0,0 +1,124 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-dbops
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Non instantiable helper class providing DB support to the @backup_plan class
+ *
+ * This class contains various static methods available for all the DB operations
+ * performed by the @backup_plan (and builder) classes
+ *
+ * TODO: Finish phpdocs
+ */
+abstract class backup_plan_dbops extends backup_dbops {
+
+    /**
+     * Given one course module id, return one array with all the block intances that belong to it
+     */
+    public static function get_blockids_from_moduleid($moduleid) {
+        global $DB;
+
+        // Get the context of the module
+        $contextid = get_context_instance(CONTEXT_MODULE, $moduleid)->id;
+
+        // Get all the block instances which parentcontextid is the module contextid
+        $blockids = array();
+        $instances = $DB->get_records('block_instances', array('parentcontextid' => $contextid), '', 'id');
+        foreach ($instances as $instance) {
+            $blockids[] = $instance->id;
+        }
+        return $blockids;
+    }
+
+    /**
+     * Given one course id, return one array with all the block intances that belong to it
+     */
+    public static function get_blockids_from_courseid($courseid) {
+        global $DB;
+
+        // Get the context of the course
+        $contextid = get_context_instance(CONTEXT_COURSE, $courseid)->id;
+
+        // Get all the block instances which parentcontextid is the course contextid
+        $blockids = array();
+        $instances = $DB->get_records('block_instances', array('parentcontextid' => $contextid), '', 'id');
+        foreach ($instances as $instance) {
+            $blockids[] = $instance->id;
+        }
+        return $blockids;
+    }
+
+    /**
+     * Given one section id, return one array with all the course modules that belong to it
+     */
+    public static function get_modules_from_sectionid($sectionid) {
+        global $DB;
+
+        // Get the course of the section
+        $courseid = $DB->get_field('course_sections', 'course', array('id' => $sectionid));
+
+        // Get all course modules belonging to requested section
+        $modulesarr = array();
+        $modules = $DB->get_records_sql("
+            SELECT cm.id, m.name AS modname
+              FROM {course_modules} cm
+              JOIN {modules} m ON m.id = cm.module
+             WHERE cm.course = ?
+               AND cm.section = ?", array($courseid, $sectionid));
+        foreach ($modules as $module) {
+            $module = array('id' => $module->id, 'modname' => $module->modname);
+            $modulesarr[] = (object)$module;
+        }
+        return $modulesarr;
+    }
+
+    /**
+     * Given one course id, return one array with all the course_sections belonging to it
+     */
+    public static function get_sections_from_courseid($courseid) {
+        global $DB;
+
+        // Get all sections belonging to requested course
+        $sectionsarr = array();
+        $sections = $DB->get_records('course_sections', array('course' => $courseid));
+        foreach ($sections as $section) {
+            $sectionsarr[] = $section->id;
+        }
+        return $sectionsarr;
+    }
+
+    /**
+     * Return the wwwroot of the $CFG->mnet_localhost_id host
+     * caching it along the request
+     */
+    public static function get_mnet_localhost_wwwroot() {
+        global $CFG, $DB;
+
+        static $wwwroot = null;
+
+        if (is_null($wwwroot)) {
+            $wwwroot = $DB->get_field('mnet_host', 'wwwroot', array('id' => $CFG->mnet_localhost_id));
+        }
+        return $wwwroot;
+    }
+}
diff --git a/backup/util/dbops/backup_structure_dbops.class.php b/backup/util/dbops/backup_structure_dbops.class.php
new file mode 100644 (file)
index 0000000..4621385
--- /dev/null
@@ -0,0 +1,152 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-dbops
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Non instantiable helper class providing DB support to the backup_structure stuff
+ *
+ * This class contains various static methods available for all the DB operations
+ * performed by the backup_structure stuff (mainly @backup_nested_element class)
+ *
+ * TODO: Finish phpdocs
+ */
+abstract class backup_structure_dbops extends backup_dbops {
+
+    public static function get_iterator($element, $params, $processor) {
+        global $DB;
+        // Check we are going to get_iterator for one backup_nested_element
+        if (! $element instanceof backup_nested_element) {
+            throw new base_element_struct_exception('backup_nested_element_expected');
+        }
+        // If var_array, table and sql are null, and element has no final elements it is one nested element without source
+        // Just return one 1 element iterator without information
+        if ($element->get_source_array() === null && $element->get_source_table() === null &&
+            $element->get_source_sql() === null && count($element->get_final_elements()) == 0) {
+            return new backup_array_iterator(array(0 => null));
+
+        } else if ($element->get_source_array() !== null) { // It's one array, return array_iterator
+            return new backup_array_iterator($element->get_source_array());
+
+        } else if ($element->get_source_table() !== null) { // It's one table, return recordset iterator
+            return $DB->get_recordset($element->get_source_table(), self::convert_params_to_values($params, $processor));
+
+        } else if ($element->get_source_sql() !== null) { // It's one sql, return recordset iterator
+            return $DB->get_recordset_sql($element->get_source_sql(), self::convert_params_to_values($params, $processor));
+
+        } else { // No sources, supress completely, using null iterator
+            return new backup_null_iterator();
+        }
+    }
+
+    protected static function convert_params_to_values($params, $processor) {
+        $newparams = array();
+        foreach ($params as $key => $param) {
+            $newvalue = null;
+            // If we have a base element, get its current value, exception if not set
+            if ($param instanceof base_atom) {
+                if ($param->is_set()) {
+                    $newvalue = $param->get_value();
+                } else {
+                    throw new base_element_struct_exception('valueofparamelementnotset', $param->get_name());
+                }
+
+            } else if ($param < 0) { // Possibly one processor variable, let's process it
+                // See @backup class for all the VAR_XXX variables available.
+                // Note1: backup::VAR_PARENTID is handled by nested elements themselves
+                // Note2: trying to use one non-existing var will throw exception
+                $newvalue = $processor->get_var($param);
+
+            // Else we have one raw param value, use it
+            } else {
+                $newvalue = $param;
+            }
+
+            $newparams[$key] = $newvalue;
+        }
+        return $newparams;
+    }
+
+    public static function insert_backup_ids_record($backupid, $itemname, $itemid) {
+        global $DB;
+        // We need to do some magic with scales (that are stored in negative way)
+        if ($itemname == 'scale') {
+            $itemid = -($itemid);
+        }
+        // Now, we skip any annotation with negatives/zero/nulls, ids table only stores true id (always > 0)
+        if ($itemid <= 0 || is_null($itemid)) {
+            return;
+        }
+        // TODO: Analyze if some static (and limited) cache by the 3 params could save us a bunch of record_exists() calls
+        // Note: Sure it will!
+        if (!$DB->record_exists('backup_ids_temp', array('backupid' => $backupid, 'itemname' => $itemname, 'itemid' => $itemid))) {
+            $DB->insert_record('backup_ids_temp', array('backupid' => $backupid, 'itemname' => $itemname, 'itemid' => $itemid));
+        }
+    }
+
+    public static function annotate_files($backupid, $contextid, $filearea, $itemid) {
+        global $DB;
+        $sql = 'SELECT id
+                  FROM {files}
+                 WHERE contextid = ?
+                   AND filearea = ?';
+        $params = array($contextid, $filearea);
+
+        if (!is_null($itemid)) { // Add itemid to query and params if necessary
+            $sql .= ' AND itemid = ?';
+            $params[] = $itemid;
+        }
+        $rs = $DB->get_recordset_sql($sql, $params);
+        foreach ($rs as $record) {
+            self::insert_backup_ids_record($backupid, 'file', $record->id);
+        }
+        $rs->close();
+    }
+
+    /**
+     * Moves all the existing 'item' annotations to their final 'itemfinal' ones
+     * for a given backup.
+     */
+    public static function move_annotations_to_final($backupid, $itemname) {
+        global $DB;
+        $rs = $DB->get_recordset('backup_ids_temp', array('backupid' => $backupid, 'itemname' => $itemname));
+        foreach($rs as $annotation) {
+            // If corresponding 'itemfinal' annotation does not exist, update 'item' to 'itemfinal'
+            if (! $DB->record_exists('backup_ids_temp', array('backupid' => $backupid,
+                                                              'itemname' => $itemname . 'final',
+                                                              'itemid' => $annotation->itemid))) {
+                $DB->set_field('backup_ids_temp', 'itemname', $itemname . 'final', array('id' => $annotation->id));
+            }
+        }
+        $rs->close();
+        // All the remaining 'user' annotations can be safely deleted
+        $DB->delete_records('backup_ids_temp', array('backupid' => $backupid, 'itemname' => $itemname));
+    }
+
+    /**
+     * Returns true/false if there are annotations for a given item
+     */
+    public static function annotations_exist($backupid, $itemname) {
+        global $DB;
+        return (bool)$DB->count_records('backup_ids_temp', array('backupid' => $backupid, 'itemname' => $itemname));
+    }
+}
diff --git a/backup/util/dbops/simpletest/testdbops.php b/backup/util/dbops/simpletest/testdbops.php
new file mode 100644 (file)
index 0000000..9209905
--- /dev/null
@@ -0,0 +1,267 @@
+<?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/>.
+
+/**
+ * @package moodlecore
+ * @subpackage backup-tests
+ * @copyright 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+// Prevent direct access to this file
+if (!defined('MOODLE_INTERNAL')) {
+    die('Direct access to this script is forbidden.');
+}
+
+// Include all the needed stuff
+require_once($CFG->dirroot . '/backup/util/includes/backup_includes.php');
+
+/*
+ * dbops tests (all)
+ */
+class backup_dbops_test extends UnitTestCase {
+
+    public static $includecoverage = array('backup/util/dbops');
+    public static $excludecoverage = array('backup/util/dbops/simpletest');
+
+    protected $moduleid;  // course_modules id used for testing
+    protected $sectionid; // course_sections id used for testing
+    protected $courseid;  // course id used for testing
+    protected $user;      // user record used for testing
+
+    protected $todelete;  // array of records to be deleted after tests
+
+    protected $errorlogloggerlevel; // To store $CFG->backup_error_log_logger_level
+    protected $fileloggerlevel; // To store level $CFG->backup_file_logger_level
+    protected $databaseloggerlevel; // To store $CFG->backup_database_logger_level
+    protected $outputindentedloggerlevel; // To store $CFG->backup_output_indented_logger_level
+    protected $fileloggerextra; // To store $CFG->backup_file_logger_extra
+    protected $fileloggerlevelextra; // To store level $CFG->backup_file_logger_level_extra
+    protected $debugging; // To store $CFG->debug
+    protected $debugdisplay; // To store $CFG->debugdisplay
+
+    function __construct() {
+        global $DB, $USER, $CFG;
+
+        $this->moduleid  = 0;
+        $this->sectionid = 0;
+        $this->courseid  = 0;
+        $this->userid = $USER->id;
+        $this->todelete = array();
+
+        // Check we have (at least) one course_module
+        if ($coursemodule = $DB->get_record('course_modules', array(), '*', IGNORE_MULTIPLE)) {
+            $this->moduleid  = $coursemodule->id;
+            $this->sectionid = $coursemodule->section;
+            $this->courseid  = $coursemodule->course;
+        }
+        parent::__construct();
+    }
+
+    function setUp() {
+        global $CFG;
+        parent::setUp();
+        // Avoid any file logger to be created, we'll restore original settings on tearDown()
+        // Fetch the rest of CFG variables to be able to restore them after tests
+        // and normalize default values
+        $this->errorlogloggerlevel = isset($CFG->backup_error_log_logger_level) ? $CFG->backup_error_log_logger_level : null;
+        $CFG->backup_error_log_logger_level = backup::LOG_NONE;
+
+        $this->outputindentedloggerlevel = isset($CFG->backup_output_indented_logger_level) ? $CFG->backup_output_indented_logger_level : null;
+        $CFG->backup_output_indented_logger_level = backup::LOG_NONE;
+
+        $this->fileloggerlevel = isset($CFG->backup_file_logger_level) ? $CFG->backup_file_logger_level : null;
+        $CFG->backup_file_logger_level = backup::LOG_NONE;
+
+        $this->databaseloggerlevel = isset($CFG->backup_database_logger_level) ? $CFG->backup_database_logger_level : null;
+        $CFG->backup_database_logger_level = backup::LOG_NONE;
+
+        $this->fileloggerextra = isset($CFG->backup_file_logger_extra) ? $CFG->backup_file_logger_extra : null;
+        unset($CFG->backup_file_logger_extra);
+        $this->fileloggerlevelextra = isset($CFG->backup_file_logger_level_extra) ? $CFG->backup_file_logger_level_extra : null;
+        $CFG->backup_file_logger_level_extra = backup::LOG_NONE;
+
+        $this->debugging = isset($CFG->debug) ? $CFG->debug : null;
+        $this->debugdisplay = isset($CFG->debugdisplay) ? $CFG->debugdisplay : null;
+    }
+
+    function skip() {
+        $this->skipIf(empty($this->moduleid), 'backup_dbops_test require at least one course module to exist');
+        $this->skipIf(empty($this->sectionid),'backup_dbops_test require at least one course section to exist');
+        $this->skipIf(empty($this->courseid), 'backup_dbops_test require at least one course to exist');
+        $this->skipIf(empty($this->userid),'backup_dbops_test require one valid user to exist');
+    }
+
+    function tearDown() {
+        global $DB, $CFG;
+        // Delete all the records marked to
+        foreach ($this->todelete as $todelete) {
+            $DB->delete_records($todelete[0], array('id' => $todelete[1]));
+        }
+
+        // Restore original file_logger levels
+        if ($this->errorlogloggerlevel !== null) {
+            $CFG->backup_error_log_logger_level = $this->errorlogloggerlevel;
+        } else {
+            unset($CFG->backup_error_log_logger_level);
+        }
+
+        if ($this->outputindentedloggerlevel !== null) {
+            $CFG->backup_output_indented_logger_level = $this->outputindentedloggerlevel;
+        } else {
+            unset($CFG->backup_output_indented_logger_level);
+        }
+
+        if ($this->fileloggerlevel !== null) {
+            $CFG->backup_file_logger_level = $this->fileloggerlevel;
+        } else {
+            unset($CFG->backup_file_logger_level);
+        }
+
+        if ($this->databaseloggerlevel !== null) {
+            $CFG->backup_database_logger_level = $this->databaseloggerlevel;
+        } else {
+            unset($CFG->backup_database_logger_level);
+        }
+
+        if ($this->fileloggerextra !== null) {
+            $CFG->backup_file_logger_extra = $this->fileloggerextra;
+        } else {
+            unset($CFG->backup_file_logger_extra);
+        }
+        if ($this->fileloggerlevelextra !== null) {
+            $CFG->backup_file_logger_level_extra = $this->fileloggerlevelextra;
+        } else {
+            unset($CFG->backup_file_logger_level_extra);
+        }
+        // Restore the rest of $CFG settings
+        if ($this->debugging !== null) {
+            $CFG->debug = $this->debugging;
+        } else {
+            unset($CFG->debug);
+        }
+        if ($this->debugdisplay !== null) {
+            $CFG->debugdisplay = $this->debugdisplay;
+        } else {
+            unset($CFG->debugdisplay);
+        }
+        parent::tearDown();
+    }
+
+    /*
+     * test backup_ops class
+     */
+    function test_backup_dbops() {
+        // Nothing to do here, abstract class + exception, will be tested by the rest
+    }
+
+    /*
+     * test backup_controller_dbops class
+     */
+    function test_backup_controller_dbops() {
+        global $DB;
+
+        $dbman = $DB->get_manager(); // Going to use some database_manager services for testing
+
+        // Instantiate non interactive backup_controller
+        $bc = new mock_backup_controller4dbops(backup::TYPE_1ACTIVITY, $this->moduleid, backup::FORMAT_MOODLE,
+                                    backup::INTERACTIVE_NO, backup::MODE_GENERAL, $this->userid);
+        $this->assertTrue($bc instanceof backup_controller);
+        // Calculate checksum
+        $checksum = $bc->calculate_checksum();
+        $this->assertEqual(strlen($checksum), 32); // is one md5
+
+        // save controller
+        $recid = backup_controller_dbops::save_controller($bc, $checksum);
+        $this->assertTrue($recid);
+        $this->todelete[] = array('backup_controllers', $recid); // mark this record for deletion
+        // save it again (should cause update to happen)
+        $recid2 = backup_controller_dbops::save_controller($bc, $checksum);
+        $this->assertTrue($recid2);
+        $this->todelete[] = array('backup_controllers', $recid2); // mark this record for deletion
+        $this->assertEqual($recid, $recid2); // Same record in both save operations
+
+        // Try incorrect checksum
+        $bc = new mock_backup_controller4dbops(backup::TYPE_1ACTIVITY, $this->moduleid, backup::FORMAT_MOODLE,
+                                    backup::INTERACTIVE_NO, backup::MODE_GENERAL, $this->userid);
+        $checksum = $bc->calculate_checksum();
+        try {
+            $recid = backup_controller_dbops::save_controller($bc, 'lalala');
+            $this->assertTrue(false, 'backup_dbops_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof backup_dbops_exception);
+            $this->assertEqual($e->errorcode, 'backup_controller_dbops_saving_checksum_mismatch');
+        }
+
+        // Try to save non backup_controller object
+        $bc = new stdclass();
+        try {
+            $recid = backup_controller_dbops::save_controller($bc, 'lalala');
+            $this->assertTrue(false, 'backup_controller_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof backup_controller_exception);
+            $this->assertEqual($e->errorcode, 'backup_controller_expected');
+        }
+
+        // save and load controller (by backupid). Then compare
+        $bc = new mock_backup_controller4dbops(backup::TYPE_1ACTIVITY, $this->sectionid, backup::FORMAT_MOODLE,
+                                    backup::INTERACTIVE_NO, backup::MODE_GENERAL, $this->userid);
+        $checksum = $bc->calculate_checksum(); // Calculate checksum
+        $backupid = $bc->get_backupid();
+        $this->assertEqual(strlen($backupid), 32); // is one md5
+        $recid = backup_controller_dbops::save_controller($bc, $checksum); // save controller
+        $this->todelete[] = array('backup_controllers', $recid); // mark this record for deletion
+        $newbc = backup_controller_dbops::load_controller($backupid); // load controller
+        $this->assertTrue($newbc instanceof backup_controller);
+        $newchecksum = $newbc->calculate_checksum();
+        $this->assertEqual($newchecksum, $checksum);
+
+        // try to load non-existing controller
+        try {
+            $bc = backup_controller_dbops::load_controller('1234567890');
+            $this->assertTrue(false, 'backup_dbops_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof backup_dbops_exception);
+            $this->assertEqual($e->errorcode, 'backup_controller_dbops_nonexisting');
+        }
+
+        // backup_ids_temp table tests
+        // If, for any reason table exists, drop it
+        if ($dbman->table_exists('backup_ids_temp')) {
+            $dbman->drop_temp_table(new xmldb_table('backup_ids_temp'));
+        }
+        // Check backup_ids_temp table doesn't exist
+        $this->assertFalse($dbman->table_exists('backup_ids_temp'));
+        // Create and check it exists
+        backup_controller_dbops::create_backup_ids_temp_table('testingid');
+        $this->assertTrue($dbman->table_exists('backup_ids_temp'));
+        // Drop and check it doesn't exists anymore
+        backup_controller_dbops::drop_backup_ids_temp_table('testingid');
+        $this->assertFalse($dbman->table_exists('backup_ids_temp'));
+    }
+}
+
+class mock_backup_controller4dbops extends backup_controller {
+
+    /**
+     * Change standard behavior so the checksum is also stored and not onlt calculated
+     */
+    public function calculate_checksum() {
+        $this->checksum = parent::calculate_checksum();
+        return $this->checksum;
+    }
+}
diff --git a/backup/util/destinations/simpletest/testdestination.php b/backup/util/destinations/simpletest/testdestination.php
new file mode 100644 (file)
index 0000000..db95877
--- /dev/null
@@ -0,0 +1,52 @@
+<?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/>.
+
+/**
+ * @package moodlecore
+ * @subpackage backup-tests
+ * @copyright 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+// Prevent direct access to this file
+if (!defined('MOODLE_INTERNAL')) {
+    die('Direct access to this script is forbidden.');
+}
+
+// Include all the needed stuff
+//require_once($CFG->dirroot . '/backup/util/helper/backup_helper.class.php');
+
+/*
+ * dbops tests (all)
+ */
+class backup_destinations_test extends UnitTestCase {
+
+    public static $includecoverage = array('backup/util/destinations');
+    public static $excludecoverage = array('backup/util/destinations/simpletest');
+
+    /*
+     * test backup_destination class
+     */
+    function test_backup_destination() {
+    }
+
+    /*
+     * test backup_destination_osfs class
+     */
+    function test_backup_destination_osfs() {
+    }
+}
diff --git a/backup/util/factories/backup_factory.class.php b/backup/util/factories/backup_factory.class.php
new file mode 100644 (file)
index 0000000..fe15e0d
--- /dev/null
@@ -0,0 +1,162 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-factories
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Non instantiable factory class providing different backup object instances
+ *
+ * This class contains various methods available in order to easily
+ * create different parts of the backup architecture in an easy way
+ *
+ * TODO: Finish phpdocs
+ */
+abstract class backup_factory {
+
+    public static function get_destination_chain($type, $id, $mode, $execution) {
+        return null;
+    }
+
+    public static function get_logger_chain($interactive, $execution, $backupid) {
+        global $CFG;
+
+        $dfltloglevel = backup::LOG_WARNING; // Default logging level
+        if (debugging('', DEBUG_DEVELOPER)) { // Debug developer raises default logging level
+            $dfltloglevel = backup::LOG_DEBUG;
+        }
+
+        $enabledloggers = array(); // Array to store all enabled loggers
+
+        // Create error_log_logger, observing $CFG->backup_error_log_logger_level
+        $elllevel = isset($CFG->backup_error_log_logger_level) ? $CFG->backup_error_log_logger_level : $dfltloglevel;
+        $enabledloggers[] = new error_log_logger($elllevel);
+
+        // Create output_indented_logger, observing $CFG->backup_output_indented_logger_level and $CFG->debugdisplay,
+        // defaulting to LOG_WARNING. Only if interactive and inmediate
+        if ($CFG->debugdisplay && $interactive == backup::INTERACTIVE_YES && $execution == backup::EXECUTION_INMEDIATE) {
+            $oillevel = isset($CFG->backup_output_indented_logger_level) ? $CFG->backup_output_indented_logger_level : $dfltloglevel;;
+            $enabledloggers[] = new output_indented_logger($oillevel, false, false);
+        }
+
+        // Create file_logger, observing $CFG->backup_file_logger_level
+        check_dir_exists($CFG->dataroot . '/temp/backup', true, true); // need to ensure that temp/backup already exists
+        $fllevel = isset($CFG->backup_file_logger_level) ? $CFG->backup_file_logger_level : $dfltloglevel;
+        $enabledloggers[] = new file_logger($fllevel, true, true, $CFG->dataroot . '/temp/backup/' . $backupid . '.log.html');
+
+        // Create database_logger, observing $CFG->backup_database_logger_level and defaulting to LOG_WARNING
+        // and pointing to the backup_logs table
+        $dllevel = isset($CFG->backup_database_logger_level) ? $CFG->backup_database_logger_level : backup::LOG_WARNING;
+        $columns = array('backupid' => $backupid);
+        $enabledloggers[] = new database_logger($dllevel, 'timecreated', 'level', 'message', 'backup_logs', $columns);
+
+        // Create extra file_logger, observing $CFG->backup_file_logger_extra and $CFG->backup_file_logger_extra_level
+        if (isset($CFG->backup_file_logger_extra)) {
+            $flelevel = isset($CFG->backup_file_logger_extra_level) ? $CFG->backup_file_logger_extra_level : $fllevel;
+            $enabledloggers[] =  new file_logger($flelevel, true, true, $CFG->backup_file_logger_extra);
+        }
+
+        // Build the chain
+        $loggers = null;
+        foreach ($enabledloggers as $currentlogger) {
+            if ($loggers == null) {
+                $loggers = $currentlogger;
+            } else {
+                $lastlogger->set_next($currentlogger);
+            }
+            $lastlogger = $currentlogger;
+        }
+
+        return $loggers;
+    }
+
+
+    /**
+     * Given one format and one course module id, return the corresponding
+     * backup_xxxx_activity_task()
+     */
+    public static function get_backup_activity_task($format, $moduleid) {
+        global $CFG, $DB;
+
+        // Check moduleid exists
+        if (!$coursemodule = get_coursemodule_from_id(false, $moduleid)) {
+            throw new backup_task_exception('activity_task_coursemodule_not_found', $moduleid);
+        }
+        $classname = 'backup_' . $coursemodule->modname . '_activity_task';
+        return new $classname($coursemodule->name, $moduleid);
+    }
+
+    /**
+     * Given one format, one block id and, optionally, one moduleid, return the corresponding backup_xxx_block_task()
+     */
+    public static function get_backup_block_task($format, $blockid, $moduleid = null) {
+        global $CFG, $DB;
+
+        // Check blockid exists
+        if (!$block = $DB->get_record('block_instances', array('id' => $blockid))) {
+            throw new backup_task_exception('block_task_block_instance_not_found', $blockid);
+        }
+
+        // Set default block backup task
+        $classname = 'backup_default_block_task';
+        $testname  = 'backup_' . $block->blockname . '_block_task';
+        // If the block has custom backup/restore task class (testname), use it
+        if (class_exists($testname)) {
+            $classname = $testname;
+        }
+        return new $classname($block->blockname, $blockid, $moduleid);
+    }
+
+    /**
+     * Given one format and one section id, return the corresponding backup_section_task()
+     */
+    public static function get_backup_section_task($format, $sectionid) {
+        global $DB;
+
+        // Check section exists
+        if (!$section = $DB->get_record('course_sections', array('id' => $sectionid))) {
+            throw new backup_task_exception('section_task_section_not_found', $sectionid);
+        }
+
+        return new backup_section_task($section->section, $sectionid);
+    }
+
+    /**
+     * Given one format and one course id, return the corresponding backup_course_task()
+     */
+    public static function get_backup_course_task($format, $courseid) {
+        global $DB;
+
+        // Check course exists
+        if (!$course = $DB->get_record('course', array('id' => $courseid))) {
+            throw new backup_task_exception('course_task_course_not_found', $courseid);
+        }
+
+        return new backup_course_task($course->shortname, $courseid);
+    }
+
+    /**
+     * Dispatches the creation of the @backup_plan to the proper format builder
+     */
+    static public function build_plan($controller) {
+        backup_plan_builder::build_plan($controller);
+    }
+}
diff --git a/backup/util/factories/simpletest/testfactory.php b/backup/util/factories/simpletest/testfactory.php
new file mode 100644 (file)
index 0000000..1551fc0
--- /dev/null
@@ -0,0 +1,205 @@
+<?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/>.
+
+/**
+ * @package moodlecore
+ * @subpackage backup-tests
+ * @copyright 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+// Prevent direct access to this file
+if (!defined('MOODLE_INTERNAL')) {
+    die('Direct access to this script is forbidden.');
+}
+
+// Include all the needed stuff
+require_once($CFG->dirroot . '/backup/util/interfaces/checksumable.class.php');
+require_once($CFG->dirroot . '/backup/backup.class.php');
+require_once($CFG->dirroot . '/backup/util/loggers/base_logger.class.php');
+require_once($CFG->dirroot . '/backup/util/loggers/error_log_logger.class.php');
+require_once($CFG->dirroot . '/backup/util/loggers/output_indented_logger.class.php');
+require_once($CFG->dirroot . '/backup/util/loggers/database_logger.class.php');
+require_once($CFG->dirroot . '/backup/util/loggers/file_logger.class.php');
+require_once($CFG->dirroot . '/backup/util/factories/backup_factory.class.php');
+
+/*
+ * backup_factory tests (all)
+ */
+class backup_factories_test extends UnitTestCase {
+
+    public static $includecoverage = array('backup/util/factories');
+    public static $excludecoverage = array('backup/util/factories/simpletest');
+
+    protected $errorlogloggerlevel; // To store $CFG->backup_error_log_logger_level
+    protected $fileloggerlevel; // To store level $CFG->backup_file_logger_level
+    protected $databaseloggerlevel; // To store $CFG->backup_database_logger_level
+    protected $outputindentedloggerlevel; // To store $CFG->backup_output_indented_logger_level
+    protected $fileloggerextra; // To store $CFG->backup_file_logger_extra
+    protected $fileloggerlevelextra; // To store level $CFG->backup_file_logger_level_extra
+    protected $debugging; // To store $CFG->debug
+    protected $debugdisplay; // To store $CFG->debugdisplay
+
+    function setUp() {
+        global $CFG;
+        parent::setUp();
+        // Avoid any file logger to be created, we'll restore original settings on tearDown()
+        // Fetch the rest of CFG variables to be able to restore them after tests
+        // and normalize default values
+        $this->errorlogloggerlevel = isset($CFG->backup_error_log_logger_level) ? $CFG->backup_error_log_logger_level : null;
+        $CFG->backup_error_log_logger_level = backup::LOG_NONE;
+
+        $this->outputindentedloggerlevel = isset($CFG->backup_output_indented_logger_level) ? $CFG->backup_output_indented_logger_level : null;
+        $CFG->backup_output_indented_logger_level = backup::LOG_NONE;
+
+        $this->fileloggerlevel = isset($CFG->backup_file_logger_level) ? $CFG->backup_file_logger_level : null;
+        $CFG->backup_file_logger_level = backup::LOG_NONE;
+
+        $this->databaseloggerlevel = isset($CFG->backup_database_logger_level) ? $CFG->backup_database_logger_level : null;
+        $CFG->backup_database_logger_level = backup::LOG_NONE;
+
+        $this->fileloggerextra = isset($CFG->backup_file_logger_extra) ? $CFG->backup_file_logger_extra : null;
+        unset($CFG->backup_file_logger_extra);
+        $this->fileloggerlevelextra = isset($CFG->backup_file_logger_level_extra) ? $CFG->backup_file_logger_level_extra : null;
+        $CFG->backup_file_logger_level_extra = backup::LOG_NONE;
+
+        $this->debugging = isset($CFG->debug) ? $CFG->debug : null;
+        $this->debugdisplay = isset($CFG->debugdisplay) ? $CFG->debugdisplay : null;
+    }
+
+    function tearDown() {
+        global $CFG;
+        // Restore original file_logger levels
+        if ($this->errorlogloggerlevel !== null) {
+            $CFG->backup_error_log_logger_level = $this->errorlogloggerlevel;
+        } else {
+            unset($CFG->backup_error_log_logger_level);
+        }
+
+        if ($this->outputindentedloggerlevel !== null) {
+            $CFG->backup_output_indented_logger_level = $this->outputindentedloggerlevel;
+        } else {
+            unset($CFG->backup_output_indented_logger_level);
+        }
+
+        if ($this->fileloggerlevel !== null) {
+            $CFG->backup_file_logger_level = $this->fileloggerlevel;
+        } else {
+            unset($CFG->backup_file_logger_level);
+        }
+
+        if ($this->databaseloggerlevel !== null) {
+            $CFG->backup_database_logger_level = $this->databaseloggerlevel;
+        } else {
+            unset($CFG->backup_database_logger_level);
+        }
+
+        if ($this->fileloggerextra !== null) {
+            $CFG->backup_file_logger_extra = $this->fileloggerextra;
+        } else {
+            unset($CFG->backup_file_logger_extra);
+        }
+        if ($this->fileloggerlevelextra !== null) {
+            $CFG->backup_file_logger_level_extra = $this->fileloggerlevelextra;
+        } else {
+            unset($CFG->backup_file_logger_level_extra);
+        }
+        // Restore the rest of $CFG settings
+        if ($this->debugging !== null) {
+            $CFG->debug = $this->debugging;
+        } else {
+            unset($CFG->debug);
+        }
+        if ($this->debugdisplay !== null) {
+            $CFG->debugdisplay = $this->debugdisplay;
+        } else {
+            unset($CFG->debugdisplay);
+        }
+        parent::tearDown();
+    }
+
+
+    /*
+     * test get_logger_chain() method
+     */
+    function test_backup_factory() {
+        global $CFG;
+
+        // Default instantiate, all levels = backup::LOG_NONE
+        // With debugdisplay enabled
+        $CFG->debugdisplay = true;
+        $logger1 = backup_factory::get_logger_chain(backup::INTERACTIVE_YES, backup::EXECUTION_INMEDIATE, 'test');
+        $this->assertTrue($logger1 instanceof error_log_logger);  // 1st logger is error_log_logger
+        $this->assertEqual($logger1->get_level(), backup::LOG_NONE);
+        $logger2 = $logger1->get_next();
+        $this->assertTrue($logger2 instanceof output_indented_logger);  // 2nd logger is output_indented_logger
+        $this->assertEqual($logger2->get_level(), backup::LOG_NONE);
+        $logger3 = $logger2->get_next();
+        $this->assertTrue($logger3 instanceof file_logger);  // 3rd logger is file_logger
+        $this->assertEqual($logger3->get_level(), backup::LOG_NONE);
+        $logger4 = $logger3->get_next();
+        $this->assertTrue($logger4 instanceof database_logger);  // 4th logger is database_logger
+        $this->assertEqual($logger4->get_level(), backup::LOG_NONE);
+        $logger5 = $logger4->get_next();
+        $this->assertTrue($logger5 === null);
+
+        // With debugdisplay disabled
+        $CFG->debugdisplay = false;
+        $logger1 = backup_factory::get_logger_chain(backup::INTERACTIVE_YES, backup::EXECUTION_INMEDIATE, 'test');
+        $this->assertTrue($logger1 instanceof error_log_logger);  // 1st logger is error_log_logger
+        $this->assertEqual($logger1->get_level(), backup::LOG_NONE);
+        $logger2 = $logger1->get_next();
+        $this->assertTrue($logger2 instanceof file_logger);  // 2nd logger is file_logger
+        $this->assertEqual($logger2->get_level(), backup::LOG_NONE);
+        $logger3 = $logger2->get_next();
+        $this->assertTrue($logger3 instanceof database_logger);  // 3rd logger is database_logger
+        $this->assertEqual($logger3->get_level(), backup::LOG_NONE);
+        $logger4 = $logger3->get_next();
+        $this->assertTrue($logger4 === null);
+
+        // Instantiate with debugging enabled and $CFG->backup_error_log_logger_level not set
+        $CFG->debugdisplay = true;
+        $CFG->debug = DEBUG_DEVELOPER;
+        unset($CFG->backup_error_log_logger_level);
+        $logger1 = backup_factory::get_logger_chain(backup::INTERACTIVE_YES, backup::EXECUTION_INMEDIATE, 'test');
+        $this->assertTrue($logger1 instanceof error_log_logger);  // 1st logger is error_log_logger
+        $this->assertEqual($logger1->get_level(), backup::LOG_DEBUG); // and must have backup::LOG_DEBUG level
+        // Set $CFG->backup_error_log_logger_level to backup::LOG_WARNING and test again
+        $CFG->backup_error_log_logger_level = backup::LOG_WARNING;
+        $logger1 = backup_factory::get_logger_chain(backup::INTERACTIVE_YES, backup::EXECUTION_INMEDIATE, 'test');
+        $this->assertTrue($logger1 instanceof error_log_logger);  // 1st logger is error_log_logger
+        $this->assertEqual($logger1->get_level(), backup::LOG_WARNING); // and must have backup::LOG_WARNING level
+
+        // Instantiate in non-interactive mode, output_indented_logger must be out
+        $logger1 = backup_factory::get_logger_chain(backup::INTERACTIVE_NO, backup::EXECUTION_INMEDIATE, 'test');
+        $logger2 = $logger1->get_next();
+        $this->assertTrue($logger2 instanceof file_logger);  // 2nd logger is file_logger (output_indented_logger skiped)
+
+        // Define extra file logger and instantiate, should be 5th and last logger
+        $CFG->backup_file_logger_extra = '/tmp/test.html';
+        $CFG->backup_file_logger_level_extra = backup::LOG_NONE;
+        $logger1 = backup_factory::get_logger_chain(backup::INTERACTIVE_YES, backup::EXECUTION_INMEDIATE, 'test');
+        $logger2 = $logger1->get_next();
+        $logger3 = $logger2->get_next();
+        $logger4 = $logger3->get_next();
+        $logger5 = $logger4->get_next();
+        $this->assertTrue($logger5 instanceof file_logger);  // 5rd logger is file_logger (extra)
+        $this->assertEqual($logger3->get_level(), backup::LOG_NONE);
+        $logger6 = $logger5->get_next();
+        $this->assertTrue($logger6 === null);
+    }
+}
diff --git a/backup/util/helper/backup_anonymizer_helper.class.php b/backup/util/helper/backup_anonymizer_helper.class.php
new file mode 100644 (file)
index 0000000..c7201ef
--- /dev/null
@@ -0,0 +1,104 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-helper
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Helper class for anonymization of data
+ *
+ * This functions includes a collection of methods that are invoked
+ * from the backup process when anonymization services have been
+ * requested.
+ *
+ * The name of each method must be "process_parentname_name", as defined
+ * byt the @anonymizer_final_element final element class, where
+ * parentname is the name ob the parent tag and name the name of the tag
+ * contents to be anonymized (i.e. process_user_username) with one param
+ * being the value to anonymize.
+ *
+ * Note: current implementation of anonymization is pretty simple, just some
+ * sequential values are used. If we want more elaborated generation, it
+ * can be replaced later (using generators or wathever). Don't forget we must
+ * ensure some fields (username, idnumber, email) are unique always.
+ *
+ * TODO: Improve to use more advanced anonymization
+ *
+ * TODO: Finish phpdocs
+ */
+class backup_anonymizer_helper {
+
+    public static function process_user_auth($value) {
+        return 'manual'; // Set them to manual always
+    }
+
+    public static function process_user_username($value) {
+        static $counter = 0;
+        $counter++;
+        return 'anon' . $counter; // Just a counter
+    }
+
+    public static function process_user_idnumber($value) {
+        return ''; // Just blank it
+    }
+
+    public static function process_user_firstname($value) {
+        static $counter = 0;
+        $counter++;
+        return 'anonfirstname' . $counter; // Just a counter
+    }
+
+    public static function process_user_lastname($value) {
+        static $counter = 0;
+        $counter++;
+        return 'anonlastname' . $counter; // Just a counter
+    }
+
+    public static function process_user_email($value) {
+        static $counter = 0;
+        $counter++;
+        return 'anon' . $counter . '@doesntexist.com'; // Just a counter
+    }
+
+    public static function process_user_emailstop($value) {
+        return 1; // Stop email for anon users
+    }
+
+    public static function process_user_lastip($value) {
+        return '127.0.0.1'; // Set lastip to localhost
+    }
+
+    public static function process_user_picture($value) {
+        return 0; // No picture
+    }
+
+    public static function process_user_url($value) {
+        return ''; // No url
+    }
+
+    public static function process_user_description($value) {
+        return ''; // No user description
+    }
+
+    public static function process_user_imagealt($value) {
+        return ''; // No user imagealt
+    }
+}
diff --git a/backup/util/helper/backup_array_iterator.class.php b/backup/util/helper/backup_array_iterator.class.php
new file mode 100644 (file)
index 0000000..1fce832
--- /dev/null
@@ -0,0 +1,66 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-helper
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Implementation of iterator interface to work with common arrays
+ *
+ * This class implements the iterator interface in order to provide one
+ * common API to be used in backup and restore when, within the same code,
+ * both database recordsets (already iteratorors) and arrays of information
+ * are used.
+ *
+ * TODO: Finish phpdocs
+ */
+class backup_array_iterator implements iterator {
+
+    private $arr;
+
+    public function __construct(array $arr) {
+        $this->arr = $arr;
+    }
+
+    public function rewind() {
+        return reset($this->arr);
+    }
+
+    public function current() {
+        return current($this->arr);
+    }
+
+    public function key() {
+        return key($this->arr);
+    }
+
+    public function next() {
+        return next($this->arr);
+    }
+
+    public function valid() {
+        return key($this->arr) !== null;
+    }
+
+    public function close() { // Added to provide compatibility with recordset iterators
+        reset($this->arr); // Just reset the array
+    }
+}
diff --git a/backup/util/helper/backup_file_manager.class.php b/backup/util/helper/backup_file_manager.class.php
new file mode 100644 (file)
index 0000000..f8ff036
--- /dev/null
@@ -0,0 +1,136 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-helper
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Collection of helper functions to handle files
+ *
+ * This class implements various functions related with moodle storage
+ * handling (get file from storage, put it there...) and some others
+ * to use the zip/unzip facilities.
+ *
+ * Note: It's supposed that, some day, files implementation will offer
+ * those functions without needeing to know storage internals at all.
+ * That day, we'll move related functions here to proper file api ones.
+ *
+ * TODO: Unse File API facilities when available instead of har-coded
+ * storage access here.
+ *
+ * TODO: Finish phpdocs
+ */
+class backup_file_manager {
+
+    /**
+     * Returns the full path to the storage base dir
+     */
+    public static function get_moodle_storage_base_dir() {
+        global $CFG;
+
+        if (isset($CFG->filedir)) {
+            return $CFG->filedir;
+        } else {
+            return $CFG->dataroot.'/filedir';
+        }
+    }
+
+    /**
+     * Returns the full path to backup storage base dir
+     */
+    public static function get_backup_storage_base_dir($backupid) {
+        global $CFG;
+
+        return $CFG->dataroot . '/temp/backup/' . $backupid . '/files';
+    }
+
+    /**
+     * Given one file content hash, returns the path (relative to filedir)
+     * to the file.
+     */
+    public static function get_content_file_location($contenthash) {
+        $l1 = $contenthash[0].$contenthash[1];
+        $l2 = $contenthash[2].$contenthash[3];
+        $l3 = $contenthash[4].$contenthash[5];
+        return "$l1/$l2/$l3/$contenthash";
+    }
+
+    /**
+     * Copy one file from moodle storage to backup storage
+     */
+    public static function copy_file_moodle2backup($backupid, $filerecorid) {
+        global $DB;
+
+        // Normalise param
+        if (!is_object($filerecorid)) {
+            $filerecorid = $DB->get_record('files', array('id' => $filerecorid));
+        }
+
+        // Directory, nothing to do
+        if ($filerecorid->filename === '.') {
+            return;
+        }
+
+        // Calculate source and target paths (use same subdirs strategy for both)
+        $sourcefilepath = self::get_moodle_storage_base_dir() . '/' .
+                          self::get_content_file_location($filerecorid->contenthash);
+        $targetfilepath = self::get_backup_storage_base_dir($backupid) . '/' .
+                          self::get_content_file_location($filerecorid->contenthash);
+
+        // Check source exists and is readable
+        if (!file_exists($sourcefilepath) || !is_readable($sourcefilepath)) {
+            throw new backup_helper_exception('cannot_read_file_from_filepool', $sourcefilepath);
+        }
+
+        // Create target dir if necessary
+        if (!file_exists(dirname($targetfilepath))) {
+            if (!check_dir_exists(dirname($targetfilepath), true, true)) {
+                throw new backup_helper_exception('cannot_create_directory', dirname($targetfilepath));
+            }
+        }
+
+        // And copy the file (if doesn't exist already)
+        if (!file_exists($targetfilepath)) {
+            if (!copy($sourcefilepath, $targetfilepath)) {
+                throw new backup_helper_exception('cannot_copy_file', $sourcefilepath, $targetfilepath);
+            }
+        }
+    }
+
+    /**
+     * Copy one file from backup storage to moodle storage
+     */
+    public static function copy_file_backup2moodle($backupid, $filerecorid) {
+        global $DB;
+
+        // Normalise param
+        if (!is_object($filerecorid)) {
+            $filerecorid = $DB->get_record('files', array('id' => $filerecorid));
+        }
+
+        // Directory, nothing to do
+        if ($filerecorid->filename === '.') {
+            return;
+        }
+
+        // TODO: Finish this on restore
+    }
+}
diff --git a/backup/util/helper/backup_general_helper.class.php b/backup/util/helper/backup_general_helper.class.php
new file mode 100644 (file)
index 0000000..34b16c2
--- /dev/null
@@ -0,0 +1,58 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-helper
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Non instantiable helper class providing general helper methods for backup/restore
+ *
+ * This class contains various general helper static methods available for backup/restore
+ *
+ * TODO: Finish phpdocs
+ */
+abstract class backup_general_helper extends backup_helper {
+
+    /**
+     * Calculate one checksum for any array/object. Works recursively
+     */
+    public static function array_checksum_recursive($arr) {
+
+        $checksum = ''; // Init checksum
+
+        // Check we are going to process one array always, objects must be cast before
+        if (!is_array($arr)) {
+            throw new backup_helper_exception('array_expected');
+        }
+        foreach ($arr as $key => $value) {
+            if ($value instanceof checksumable) {
+                $checksum = md5($checksum . '-' . $key . '-' . $value->calculate_checksum());
+            } else if (is_object($value)) {
+                $checksum = md5($checksum . '-' . $key . '-' . self::array_checksum_recursive((array)$value));
+            } else if (is_array($value)) {
+                $checksum = md5($checksum . '-' . $key . '-' . self::array_checksum_recursive($value));
+            } else {
+                $checksum = md5($checksum . '-' . $key . '-' . $value);
+            }
+        }
+        return $checksum;
+    }
+}
diff --git a/backup/util/helper/backup_helper.class.php b/backup/util/helper/backup_helper.class.php
new file mode 100644 (file)
index 0000000..d770c06
--- /dev/null
@@ -0,0 +1,176 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-helper
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Base abstract class for all the helper classes providing various operations
+ *
+ * TODO: Finish phpdocs
+ */
+abstract class backup_helper {
+
+    /**
+     * Given one backupid, create all the needed dirs to have one backup temp dir available
+     */
+    static public function check_and_create_backup_dir($backupid) {
+        global $CFG;
+        if (!check_dir_exists($CFG->dataroot . '/temp/backup/' . $backupid, true, true)) {
+            throw new backup_helper_exception('cannot_create_backup_temp_dir');
+        }
+    }
+
+    /**
+     * Given one backupid, ensure its temp dir is completelly empty
+     */
+    static public function clear_backup_dir($backupid) {
+        global $CFG;
+        if (!self::delete_dir_contents($CFG->dataroot . '/temp/backup/' . $backupid)) {
+            throw new backup_helper_exception('cannot_empty_backup_temp_dir');
+        }
+    }
+
+    /**
+     * Given one fullpath to directory, delete its contents recursively
+     * Copied originally from somewhere in the net.
+     * TODO: Modernise this
+     */
+    static public function delete_dir_contents($dir, $excludeddir='') {
+        if (!is_dir($dir)) {
+            // if we've been given a directory that doesn't exist yet, return true.
+            // this happens when we're trying to clear out a course that has only just
+            // been created.
+            return true;
+        }
+        $slash = "/";
+
+        // Create arrays to store files and directories
+        $dir_files      = array();
+        $dir_subdirs    = array();
+
+        // Make sure we can delete it
+        chmod($dir, 0777);
+
+        if ((($handle = opendir($dir))) == false) {
+            // The directory could not be opened
+            return false;
+        }
+
+        // Loop through all directory entries, and construct two temporary arrays containing files and sub directories
+        while (false !== ($entry = readdir($handle))) {
+            if (is_dir($dir. $slash .$entry) && $entry != ".." && $entry != "." && $entry != $excludeddir) {
+                $dir_subdirs[] = $dir. $slash .$entry;
+
+            } else if ($entry != ".." && $entry != "." && $entry != $excludeddir) {
+                $dir_files[] = $dir. $slash .$entry;
+            }
+        }
+
+        // Delete all files in the curent directory return false and halt if a file cannot be removed
+        for ($i=0; $i<count($dir_files); $i++) {
+            chmod($dir_files[$i], 0777);
+            if (((unlink($dir_files[$i]))) == false) {
+                return false;
+            }
+        }
+
+        // Empty sub directories and then remove the directory
+        for ($i=0; $i<count($dir_subdirs); $i++) {
+            chmod($dir_subdirs[$i], 0777);
+            if (self::delete_dir_contents($dir_subdirs[$i]) == false) {
+                return false;
+            } else {
+                if (remove_dir($dir_subdirs[$i]) == false) {
+                    return false;
+                }
+            }
+        }
+
+        // Close directory
+        closedir($handle);
+
+        // Success, every thing is gone return true
+        return true;
+    }
+
+    /**
+     * Delete all the temp dirs older than the time specified
+     */
+    static public function delete_old_backup_dirs($deletefrom) {
+        global $CFG;
+
+        $status = true;
+        // Get files and directories in the temp backup dir witout descend
+        $list = get_directory_list($CFG->dataroot . '/temp/backup', '', false, true, true);
+        foreach ($list as $file) {
+            $file_path = $CFG->dataroot . '/temp/backup/' . $file;
+            $moddate = filemtime($file_path);
+            if ($status && $moddate < $deletefrom) {
+                //If directory, recurse
+                if (is_dir($file_path)) {
+                    $status = self::delete_dir_contents($file_path);
+                    //There is nothing, delete the directory itself
+                    if ($status) {
+                        $status = rmdir($file_path);
+                    }
+                //If file
+                } else {
+                    unlink($file_path);
+                }
+            }
+        }
+        if (!$status) {
+            throw new backup_helper_exception('problem_deleting_old_backup_temp_dirs');
+        }
+    }
+
+    /**
+     * This function will be invoked by any log() method in backup/restore, acting
+     * as a simple forwarder to the standard loggers but also, if the $display
+     * parameter is true, supporting translation via get_string() and sending to
+     * standard output.
+     */
+    static public function log($message, $level, $a, $depth, $display, $logger) {
+        // Send to standard loggers
+        $logmessage = $message;
+        $options = empty($depth) ? array() : array('depth' => $depth);
+        if (!empty($a)) {
+            $logmessage = $logmessage . ' ' . implode(', ', (array)$a);
+        }
+        $logger->process($logmessage, $level, $options);
+
+        // If $display specified, send translated string to output_controller
+        if ($display) {
+            output_controller::get_instance()->output($message, 'backup', $a, $depth);
+        }
+    }
+}
+
+/*
+ * Exception class used by all the @helper stuff
+ */
+class backup_helper_exception extends backup_exception {
+
+    public function __construct($errorcode, $a=NULL, $debuginfo=null) {
+        parent::__construct($errorcode, $a, $debuginfo);
+    }
+}
diff --git a/backup/util/helper/backup_null_iterator.class.php b/backup/util/helper/backup_null_iterator.class.php
new file mode 100644 (file)
index 0000000..80eb530
--- /dev/null
@@ -0,0 +1,55 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-helper
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Implementation of iterator interface to work without information
+ *
+ * This class implementes the iterator but does nothing (as far as it
+ * doesn't handle real data at all). It's here to provide one common
+ * API when we want to skip some elements from structure, while also
+ * working with array/db iterators at the same time.
+ *
+ * TODO: Finish phpdocs
+ */
+class backup_null_iterator implements iterator {
+
+    public function rewind() {
+    }
+
+    public function current() {
+    }
+
+    public function key() {
+    }
+
+    public function next() {
+    }
+
+    public function valid() {
+        return false;
+    }
+
+    public function close() { // Added to provide compatibility with recordset iterators
+    }
+}
diff --git a/backup/util/helper/simpletest/testhelper.php b/backup/util/helper/simpletest/testhelper.php
new file mode 100644 (file)
index 0000000..4610e97
--- /dev/null
@@ -0,0 +1,55 @@
+<?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/>.
+
+/**
+ * @package moodlecore
+ * @subpackage backup-tests
+ * @copyright 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+// Prevent direct access to this file
+if (!defined('MOODLE_INTERNAL')) {
+    die('Direct access to this script is forbidden.');
+}
+
+// Include all the needed stuff
+require_once($CFG->dirroot . '/backup/util/interfaces/checksumable.class.php');
+require_once($CFG->dirroot . '/backup/backup.class.php');
+require_once($CFG->dirroot . '/backup/util/helper/backup_helper.class.php');
+require_once($CFG->dirroot . '/backup/util/helper/backup_general_helper.class.php');
+
+/*
+ * backup_helper tests (all)
+ */
+class backup_helper_test extends UnitTestCase {
+
+    public static $includecoverage = array('backup/util/helper');
+    public static $excludecoverage = array('backup/util/helper/simpletest');
+
+    /*
+     * test backup_helper class
+     */
+    function test_backup_helper() {
+    }
+
+    /*
+     * test backup_general_helper class
+     */
+    function test_backup_general_helper() {
+    }
+}
diff --git a/backup/util/includes/backup_includes.php b/backup/util/includes/backup_includes.php
new file mode 100644 (file)
index 0000000..936d7e6
--- /dev/null
@@ -0,0 +1,88 @@
+<?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/>.
+
+/**
+ * @package moodlecore
+ * @subpackage backup-includes
+ * @copyright 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+// Prevent direct access to this file
+if (!defined('MOODLE_INTERNAL')) {
+    die('Direct access to this script is forbidden.');
+}
+
+// Include all the backup needed stuff
+require_once($CFG->dirroot . '/backup/util/interfaces/checksumable.class.php');
+require_once($CFG->dirroot . '/backup/util/interfaces/executable.class.php');
+require_once($CFG->dirroot . '/backup/util/interfaces/processable.class.php');
+require_once($CFG->dirroot . '/backup/util/interfaces/annotable.class.php');
+require_once($CFG->dirroot . '/backup/util/interfaces/loggable.class.php');
+require_once($CFG->dirroot . '/backup/backup.class.php');
+require_once($CFG->dirroot . '/backup/util/output/output_controller.class.php');
+require_once($CFG->dirroot . '/backup/util/factories/backup_factory.class.php');
+require_once($CFG->dirroot . '/backup/util/dbops/backup_dbops.class.php');
+require_once($CFG->dirroot . '/backup/util/dbops/backup_structure_dbops.class.php');
+require_once($CFG->dirroot . '/backup/util/dbops/backup_controller_dbops.class.php');
+require_once($CFG->dirroot . '/backup/util/dbops/backup_plan_dbops.class.php');
+require_once($CFG->dirroot . '/backup/util/checks/backup_check.class.php');
+require_once($CFG->dirroot . '/backup/util/structure/base_atom.class.php');
+require_once($CFG->dirroot . '/backup/util/structure/base_attribute.class.php');
+require_once($CFG->dirroot . '/backup/util/structure/base_final_element.class.php');
+require_once($CFG->dirroot . '/backup/util/structure/base_nested_element.class.php');
+require_once($CFG->dirroot . '/backup/util/structure/base_optigroup.class.php');
+require_once($CFG->dirroot . '/backup/util/structure/base_processor.class.php');
+require_once($CFG->dirroot . '/backup/util/structure/backup_attribute.class.php');
+require_once($CFG->dirroot . '/backup/util/structure/backup_final_element.class.php');
+require_once($CFG->dirroot . '/backup/util/structure/backup_nested_element.class.php');
+require_once($CFG->dirroot . '/backup/util/structure/backup_optigroup.class.php');
+require_once($CFG->dirroot . '/backup/util/structure/backup_optigroup_element.class.php');
+require_once($CFG->dirroot . '/backup/util/structure/backup_structure_processor.class.php');
+require_once($CFG->dirroot . '/backup/util/helper/backup_helper.class.php');
+require_once($CFG->dirroot . '/backup/util/helper/backup_general_helper.class.php');
+require_once($CFG->dirroot . '/backup/util/helper/backup_null_iterator.class.php');
+require_once($CFG->dirroot . '/backup/util/helper/backup_array_iterator.class.php');
+require_once($CFG->dirroot . '/backup/util/helper/backup_anonymizer_helper.class.php');
+require_once($CFG->dirroot . '/backup/util/helper/backup_file_manager.class.php');
+require_once($CFG->dirroot . '/backup/util/xml/xml_writer.class.php');
+require_once($CFG->dirroot . '/backup/util/xml/output/xml_output.class.php');
+require_once($CFG->dirroot . '/backup/util/xml/output/file_xml_output.class.php');
+require_once($CFG->dirroot . '/backup/util/xml/contenttransformer/xml_contenttransformer.class.php');
+require_once($CFG->dirroot . '/backup/util/loggers/base_logger.class.php');
+require_once($CFG->dirroot . '/backup/util/loggers/error_log_logger.class.php');
+require_once($CFG->dirroot . '/backup/util/loggers/file_logger.class.php');
+require_once($CFG->dirroot . '/backup/util/loggers/database_logger.class.php');
+require_once($CFG->dirroot . '/backup/util/loggers/output_indented_logger.class.php');
+require_once($CFG->dirroot . '/backup/util/settings/base_setting.class.php');
+require_once($CFG->dirroot . '/backup/util/settings/backup_setting.class.php');
+require_once($CFG->dirroot . '/backup/util/settings/root/root_backup_setting.class.php');
+require_once($CFG->dirroot . '/backup/util/settings/activity/activity_backup_setting.class.php');
+require_once($CFG->dirroot . '/backup/util/settings/section/section_backup_setting.class.php');
+require_once($CFG->dirroot . '/backup/util/settings/course/course_backup_setting.class.php');
+require_once($CFG->dirroot . '/backup/util/plan/base_plan.class.php');
+require_once($CFG->dirroot . '/backup/util/plan/backup_plan.class.php');
+require_once($CFG->dirroot . '/backup/util/plan/base_task.class.php');
+require_once($CFG->dirroot . '/backup/util/plan/backup_task.class.php');
+require_once($CFG->dirroot . '/backup/util/plan/base_step.class.php');
+require_once($CFG->dirroot . '/backup/util/plan/backup_step.class.php');
+require_once($CFG->dirroot . '/backup/util/plan/backup_structure_step.class.php');
+require_once($CFG->dirroot . '/backup/util/plan/backup_execution_step.class.php');
+require_once($CFG->dirroot . '/backup/controller/backup_controller.class.php');
+
+// And some moodle stuff too
+require_once($CFG->libdir.'/gradelib.php');
diff --git a/backup/util/interfaces/annotable.class.php b/backup/util/interfaces/annotable.class.php
new file mode 100644 (file)
index 0000000..c188050
--- /dev/null
@@ -0,0 +1,41 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-interfaces
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Interface to apply to all the classes we want to be annotable in the backup/restore process
+ *
+ * TODO: Finish phpdocs
+ */
+interface annotable {
+
+    /**
+     * This function implements the annotation of the current value associating it with $itemname
+     */
+    public function annotate($backupid);
+
+    /**
+     * This function sets the $itemname to be used when annotating
+     */
+    public function set_annotation_item($itemname);
+}
diff --git a/backup/util/interfaces/checksumable.class.php b/backup/util/interfaces/checksumable.class.php
new file mode 100644 (file)
index 0000000..94c7fb2
--- /dev/null
@@ -0,0 +1,49 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-interfaces
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Interface to apply to all the classes we want to calculate their checksum
+ *
+ * Each class being part of @backup_controller will implement this interface
+ * in order to be able to calculate one objective and unique checksum for
+ * the whole controller class.
+ *
+ * TODO: Finish phpdocs
+ */
+interface checksumable {
+
+    /**
+     * This function will return one unique and stable checksum for one instance
+     * of the class implementing it. It's each implementation responsibility to
+     * do it recursively if needed and use optional store (caching) of the checksum if
+     * necessary/possible
+     */
+    public function calculate_checksum();
+
+    /**
+     * Given one checksum, returns if matches object's checksum (true) or no (false)
+     */
+    public function is_checksum_correct($checksum);
+
+}
diff --git a/backup/util/interfaces/executable.class.php b/backup/util/interfaces/executable.class.php
new file mode 100644 (file)
index 0000000..bc102ad
--- /dev/null
@@ -0,0 +1,37 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-interfaces
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Interface to apply to all the classes we want to be executable (plan/part/task)
+ *
+ * TODO: Finish phpdocs
+ */
+interface executable {
+
+    /**
+     * This function will perform all the actions necessary to achieve the execution
+     * of the plan/part/task
+     */
+    public function execute();
+}
diff --git a/backup/util/interfaces/loggable.class.php b/backup/util/interfaces/loggable.class.php
new file mode 100644 (file)
index 0000000..ee6d67a
--- /dev/null
@@ -0,0 +1,42 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-interfaces
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Interface to apply to all the classes we want to be able to write to logs
+ *
+ * Any class being part of one backup/restore and needing to senf informatio
+ * to logs must implement this interface (and have access to the @logger
+ * instantiated object)
+ *
+ * TODO: Finish phpdocs
+ */
+interface loggable {
+
+    /**
+     * This function will be responsible for handling the params, and to call
+     * to the corresponding logger->process() once all modifications in params
+     * have been performed
+     */
+    public function log($message, $level, $a = null, $depth = null, $display = false);
+}
diff --git a/backup/util/interfaces/processable.class.php b/backup/util/interfaces/processable.class.php
new file mode 100644 (file)
index 0000000..9f3f263
--- /dev/null
@@ -0,0 +1,40 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-interfaces
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Interface to apply to all the classes we want to be processable by one @base_processor
+ *
+ * Any class being part of one backup/restore structure must implement this interface
+ * in order to be able to be processed by a given processor (visitor pattern)
+ *
+ * TODO: Finish phpdocs
+ */
+interface processable {
+
+    /**
+     * This function will call to the corresponding processor method in other to
+     * make them perform the desired tasks.
+     */
+    public function process($processor);
+}
diff --git a/backup/util/loggers/base_logger.class.php b/backup/util/loggers/base_logger.class.php
new file mode 100644 (file)
index 0000000..ed2125c
--- /dev/null
@@ -0,0 +1,166 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-logger
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Base abstract class for all the loggers to be used in backup/restore
+ *
+ * Any message passed will be processed by all the loggers in the defined chain
+ * (note some implementations may be not strictly "loggers" but classes performing
+ * other sort of tasks (avoiding browser/php timeouts, painters...). One simple 1-way
+ * basic chain of commands/responsibility pattern.
+ *
+ * TODO: Finish phpdocs
+ */
+abstract class base_logger implements checksumable {
+
+    protected $level;     // minimum level of logging this logger must handle (valid level from @backup class)
+    protected $showdate;  // flag to decide if the logger must output the date (true) or no (false)
+    protected $showlevel; // flag to decide if the logger must output the level (true) or no (false)
+    protected $next; // next logger in the chain
+
+    public function __construct($level, $showdate = false, $showlevel = false) {
+        // TODO: check level is correct
+        $this->level = $level;
+        $this->showdate = $showdate;
+        $this->showlevel = $showlevel;
+        $this->next = null;
+    }
+
+    public final function set_next($next) {
+        // TODO: Check is a base logger
+
+        // TODO: Check next hasn't been set already
+
+        // TODO: Avoid circular dependencies
+        if ($this->is_circular_reference($next)) {
+            $a = new stdclass();
+            $a->alreadyinchain = get_class($this);
+            $a->main = get_class($next);
+            throw new base_logger_exception('logger_circular_reference', $a);
+        }
+
+        $this->next = $next;
+    }
+
+    public function get_next() {
+        return $this->next;
+    }
+
+    public function get_level() {
+        return $this->level;
+    }
+
+// checksumable interface methods
+
+    public function calculate_checksum() {
+        // Checksum is a simple md5 hash of classname, level and
+        // on each specialised logger, its own atrributes
+        // Not following the chain at all.
+        return md5(get_class($this) . '-' . $this->level);
+    }
+
+    public function is_checksum_correct($checksum) {
+        return $this->calculate_checksum() === $checksum;
+    }
+
+// Protected API starts here
+
+    abstract protected function action($message, $level, $options = null); // To implement
+
+    public final function process($message, $level, $options = null) {
+        $result = true;
+        if ($this->level != backup::LOG_NONE && $this->level >= $level) { // Perform action conditionally
+            $result = $this->action($message, $level, $options);
+        }
+        if ($result === false) { // Something was wrong, stop the chain
+            return $result;
+        }
+        if ($this->next !== null) { // The chain continues being processed
+            $result = $this->next->process($message, $level, $options);
+        }
+        return $result;
+    }
+
+    protected function is_circular_reference($obj) {
+        // Get object all nexts recursively and check if $this is already there
+        $nexts = $obj->get_nexts();
+        if (array_key_exists($this->calculate_checksum(), $nexts) || $obj == $this) {
+            return true;
+        }
+        return false;
+    }
+
+    protected function get_nexts() {
+        $nexts = array();
+        if ($this->next !== null) {
+            $nexts[$this->next->calculate_checksum()] = $this->next->calculate_checksum();
+            $nexts = array_merge($nexts, $this->next->get_nexts());
+        }
+        return $nexts;
+    }
+
+    protected function get_datestr() {
+        return userdate(time(), '%c');
+    }
+
+    protected function get_levelstr($level) {
+        $result = 'undefined';
+        switch ($level) {
+            case backup::LOG_ERROR:
+                $result = 'error';
+                break;
+            case backup::LOG_WARNING:
+                $result = 'warn';
+                break;
+            case backup::LOG_INFO:
+                $result = 'info';
+                break;
+            case backup::LOG_DEBUG:
+                $result = 'debug';
+                break;
+        }
+        return $result;
+    }
+
+    protected function get_prefix($level, $options) {
+        $prefix = '';
+        if ($this->showdate) {
+            $prefix .= '[' . $this->get_datestr() . '] ';
+        }
+        if ($this->showlevel) {
+            $prefix .= '[' . $this->get_levelstr($level) . '] ';
+        }
+        return $prefix;
+    }
+}
+
+/*
+ * Exception class used by all the @base_logger stuff
+ */
+class base_logger_exception extends backup_exception {
+
+    public function __construct($errorcode, $a=NULL, $debuginfo=null) {
+        parent::__construct($errorcode, $a, $debuginfo);
+    }
+}
diff --git a/backup/util/loggers/database_logger.class.php b/backup/util/loggers/database_logger.class.php
new file mode 100644 (file)
index 0000000..dcfddec
--- /dev/null
@@ -0,0 +1,74 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-logger
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Logger implementation that sends messages to database
+ *
+ * TODO: Finish phpdocs
+ */
+class database_logger extends base_logger {
+
+    protected $datecol;    // Name of the field where the timestamp will be stored
+    protected $levelcol;   // Name of the field where the level of the message will be stored
+    protected $messagecol; // Name of the field where the message will be stored
+    protected $logtable;   // Table, without prefix where information must be logged
+    protected $columns;    // Array of columns and values to set in all actions logged
+
+// Protected API starts here
+
+    public function __construct($level, $datecol = false, $levelcol = false, $messagecol = null, $logtable = null, $columns = null) {
+        // TODO check $datecol exists
+        // TODO check $levelcol exists
+        // TODO check $logtable exists
+        // TODO check $messagecol exists
+        // TODO check all $columns exist
+        $this->datecol    = $datecol;
+        $this->levelcol   = $levelcol;
+        $this->messagecol = $messagecol;
+        $this->logtable   = $logtable;
+        $this->columns    = $columns;
+        parent::__construct($level, (bool)$datecol, (bool)$levelcol);
+    }
+
+    protected function action($message, $level, $options = null) {
+        $columns = $this->columns;
+        if ($this->datecol) {
+            $columns[$this->datecol] = time();
+        }
+        if ($this->levelcol) {
+            $columns[$this->levelcol] = $level;
+        }
+        $columns[$this->messagecol] = $message; //TODO: should this be cleaned?
+        return $this->insert_log_record($this->logtable, $columns);
+    }
+
+    protected function insert_log_record($table, $columns) {
+        // TODO: Allow to use an alternate connection (created in constructor)
+        // based in some CFG->backup_database_logger_newconn = true in order
+        // to preserve DB logs if the whole backup/restore transaction is
+        // rollback
+        global $DB;
+        return $DB->insert_record($this->logtable, $columns, false); // Don't return inserted id
+    }
+}
diff --git a/backup/util/loggers/error_log_logger.class.php b/backup/util/loggers/error_log_logger.class.php
new file mode 100644 (file)
index 0000000..a303cd1
--- /dev/null
@@ -0,0 +1,37 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-logger
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Logger implementation that sends messages to error_log()
+ *
+ * TODO: Finish phpdocs
+ */
+class error_log_logger extends base_logger {
+
+// Protected API starts here
+
+    protected function action($message, $level, $options = null) {
+        return error_log($message);
+    }
+}
diff --git a/backup/util/loggers/file_logger.class.php b/backup/util/loggers/file_logger.class.php
new file mode 100644 (file)
index 0000000..b183767
--- /dev/null
@@ -0,0 +1,85 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-logger
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Logger implementation that sends indented messages (depth option) to one file
+ *
+ * TODO: Finish phpdocs
+ */
+class file_logger extends base_logger {
+
+    protected $fullpath; // Full path to OS file where contents will be stored
+    protected $fhandle;  // File handle where all write operations happen
+
+    public function __construct($level, $showdate = false, $showlevel = false, $fullpath = null) {
+        if (empty($fullpath)) {
+            throw new base_logger_exception('missing_fullpath_parameter', $fullpath);
+        }
+        if (!is_writable(dirname($fullpath))) {
+            throw new base_logger_exception('file_not_writable', $fullpath);
+        }
+        // Open the OS file for writing (append)
+        $this->fullpath = $fullpath;
+        if ($level > backup::LOG_NONE) { // Only create the file if we are going to log something
+            if (! $this->fhandle = fopen($this->fullpath, 'a')) {
+                throw new base_logger_exception('error_opening_file', $fullpath);
+            }
+        }
+        parent::__construct($level, $showdate, $showlevel);
+    }
+
+    public function __destruct() {
+        @fclose($this->fhandle); // Blindy close the file handler (no exceptions in destruct)
+    }
+
+    public function __sleep() {
+        @fclose($this->fhandle); // Blindy close the file handler before serialization
+        return array('level', 'showdate', 'showlevel', 'next', 'fullpath');
+    }
+
+    public function __wakeup() {
+        if ($this->level > backup::LOG_NONE) { // Only create the file if we are going to log something
+            if (! $this->fhandle = fopen($this->fullpath, 'a')) {
+                throw new base_logger_exception('error_opening_file', $fullpath);
+            }
+        }
+    }
+
+// Protected API starts here
+
+    protected function action($message, $level, $options = null) {
+        $prefix = $this->get_prefix($level, $options);
+        $depth = isset($options['depth']) ? $options['depth'] : 0;
+        // Depending of the type (extension of the file), format differently
+        if (substr($this->fullpath, -5) !== '.html') {
+            $content = $prefix . str_repeat('  ', $depth) . $message . PHP_EOL;
+        } else {
+            $content = $prefix . str_repeat('&nbsp;&nbsp;', $depth) . htmlentities($message, ENT_QUOTES) . '<br/>' . PHP_EOL;
+        }
+        if (false === fwrite($this->fhandle, $content)) {
+            throw new base_logger_exception('error_writing_file', $this->fullpath);
+        }
+        return true;
+    }
+}
diff --git a/backup/util/loggers/output_indented_logger.class.php b/backup/util/loggers/output_indented_logger.class.php
new file mode 100644 (file)
index 0000000..8bb6811
--- /dev/null
@@ -0,0 +1,46 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-logger
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Logger implementation that sends indented messages (depth option) to output
+ *
+ * TODO: Finish phpdocs
+ */
+class output_indented_logger extends base_logger {
+
+// Protected API starts here
+
+    protected function action($message, $level, $options = null) {
+        $prefix = $this->get_prefix($level, $options);
+        $depth = isset($options['depth']) ? $options['depth'] : 0;
+        // Depending of running from browser/command line, format differently
+        if (defined('STDOUT')) {
+            echo $prefix . str_repeat('  ', $depth) . $message . PHP_EOL;
+        } else {
+            echo $prefix . str_repeat('&nbsp;&nbsp;', $depth) . htmlentities($message, ENT_QUOTES) . '<br/>' . PHP_EOL;
+        }
+        flush();
+        return true;
+    }
+}
diff --git a/backup/util/loggers/output_text_logger.class.php b/backup/util/loggers/output_text_logger.class.php
new file mode 100644 (file)
index 0000000..fe61536
--- /dev/null
@@ -0,0 +1,45 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-logger
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Logger implementation that sends text messages to output
+ *
+ * TODO: Finish phpdocs
+ */
+class output_text_logger extends base_logger {
+
+// Protected API starts here
+
+    protected function action($message, $level, $options = null) {
+        $prefix = $this->get_prefix($level, $options);
+        // Depending of running from browser/command line, format differently
+        if (defined('STDOUT')) {
+            echo $prefix . $message . PHP_EOL;
+        } else {
+            echo $prefix . htmlentities($message, ENT_QUOTES) . '<br/>' . PHP_EOL;
+        }
+        flush();
+        return true;
+    }
+}
diff --git a/backup/util/loggers/simpletest/testlogger.php b/backup/util/loggers/simpletest/testlogger.php
new file mode 100644 (file)
index 0000000..01e1d28
--- /dev/null
@@ -0,0 +1,393 @@
+<?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/>.
+
+/**
+ * @package moodlecore
+ * @subpackage backup-tests
+ * @copyright 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+// Prevent direct access to this file
+if (!defined('MOODLE_INTERNAL')) {
+    die('Direct access to this script is forbidden.');
+}
+
+// Include all the needed stuff
+require_once($CFG->dirroot . '/backup/util/interfaces/checksumable.class.php');
+require_once($CFG->dirroot . '/backup/backup.class.php');
+require_once($CFG->dirroot . '/backup/util/loggers/base_logger.class.php');
+require_once($CFG->dirroot . '/backup/util/loggers/error_log_logger.class.php');
+require_once($CFG->dirroot . '/backup/util/loggers/output_text_logger.class.php');
+require_once($CFG->dirroot . '/backup/util/loggers/output_indented_logger.class.php');
+require_once($CFG->dirroot . '/backup/util/loggers/database_logger.class.php');
+require_once($CFG->dirroot . '/backup/util/loggers/file_logger.class.php');
+
+/*
+ * logger tests (all)
+ */
+class logger_test extends UnitTestCase {
+
+    public static $includecoverage = array('backup/util/loggers');
+    public static $excludecoverage = array('backup/util/loggers/simpletest');
+
+    /*
+     * test base_logger class
+     */
+    function test_base_logger() {
+        // Test logger with simple action (message * level)
+        $lo = new mock_base_logger1(backup::LOG_ERROR);
+        $msg = 13;
+        $this->assertEqual($lo->process($msg, backup::LOG_ERROR), $msg * backup::LOG_ERROR);
+        // With lowest level must resturn true
+        $lo = new mock_base_logger1(backup::LOG_ERROR);
+        $msg = 13;
+        $this->assertTrue($lo->process($msg, backup::LOG_DEBUG));
+
+        // Chain 2 loggers, we must get as result the result of the ineer one
+        $lo1 = new mock_base_logger1(backup::LOG_ERROR);
+        $lo2 = new mock_base_logger2(backup::LOG_ERROR);
+        $lo1->set_next($lo2);
+        $msg = 13;
+        $this->assertEqual($lo1->process($msg, backup::LOG_ERROR), $msg + backup::LOG_ERROR);
+
+        // Try circular reference
+        $lo1 = new mock_base_logger1(backup::LOG_ERROR);
+        try {
+            $lo1->set_next($lo1); //self
+            $this->assertTrue(false, 'base_logger_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof base_logger_exception);
+            $this->assertEqual($e->errorcode, 'logger_circular_reference');
+            $this->assertTrue($e->a instanceof stdclass);
+            $this->assertEqual($e->a->main, get_class($lo1));
+            $this->assertEqual($e->a->alreadyinchain, get_class($lo1));
+        }
+
+        $lo1 = new mock_base_logger1(backup::LOG_ERROR);
+        $lo2 = new mock_base_logger2(backup::LOG_ERROR);
+        $lo3 = new mock_base_logger3(backup::LOG_ERROR);
+        $lo1->set_next($lo2);
+        $lo2->set_next($lo3);
+        try {
+            $lo3->set_next($lo1);
+            $this->assertTrue(false, 'base_logger_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof base_logger_exception);
+            $this->assertEqual($e->errorcode, 'logger_circular_reference');
+            $this->assertTrue($e->a instanceof stdclass);
+            $this->assertEqual($e->a->main, get_class($lo1));
+            $this->assertEqual($e->a->alreadyinchain, get_class($lo3));
+        }
+
+        // Test stopper logger
+        $lo1 = new mock_base_logger1(backup::LOG_ERROR);
+        $lo2 = new mock_base_logger2(backup::LOG_ERROR);
+        $lo3 = new mock_base_logger3(backup::LOG_ERROR);
+        $lo1->set_next($lo2);
+        $lo2->set_next($lo3);
+        $this->assertFalse($lo1->process('test', backup::LOG_ERROR));
+
+        // Test checksum correct
+        $lo1 = new mock_base_logger1(backup::LOG_ERROR);
+        $lo1->is_checksum_correct(get_class($lo1) . '-' . backup::LOG_ERROR);
+
+        // Test get_levelstr()
+        $lo1 = new mock_base_logger1(backup::LOG_ERROR);
+        $this->assertEqual($lo1->get_levelstr(backup::LOG_NONE), 'undefined');
+        $this->assertEqual($lo1->get_levelstr(backup::LOG_ERROR), 'error');
+        $this->assertEqual($lo1->get_levelstr(backup::LOG_WARNING), 'warn');
+        $this->assertEqual($lo1->get_levelstr(backup::LOG_INFO), 'info');
+        $this->assertEqual($lo1->get_levelstr(backup::LOG_DEBUG), 'debug');
+    }
+
+    /*
+     * test error_log_logger class
+     */
+    function test_error_log_logger() {
+        // Not much really to test, just intantiate and execute, should return true
+        $lo = new error_log_logger(backup::LOG_ERROR);
+        $this->assertTrue($lo instanceof error_log_logger);
+        $message = 'This log exists because you have run Moodle unit tests: Ignore it';
+        $result = $lo->process($message, backup::LOG_ERROR);
+        $this->assertTrue($result);
+    }
+
+    /*
+     * test output_text_logger class
+     */
+    function test_output_text_logger() {
+        // Instantiate without date nor level output
+        $lo = new output_text_logger(backup::LOG_ERROR);
+        $this->assertTrue($lo instanceof output_text_logger);
+        $message = 'testing output_text_logger';
+        ob_start(); // Capture output
+        $result = $lo->process($message, backup::LOG_ERROR);
+        $contents = ob_get_contents();
+        ob_end_clean(); // End capture and discard
+        $this->assertTrue($result);
+        $this->assertTrue(strpos($contents, $message) !== false);
+
+        // Instantiate with date and level output
+        $lo = new output_text_logger(backup::LOG_ERROR, true, true);
+        $this->assertTrue($lo instanceof output_text_logger);
+        $message = 'testing output_text_logger';
+        ob_start(); // Capture output
+        $result = $lo->process($message, backup::LOG_ERROR);
+        $contents = ob_get_contents();
+        ob_end_clean(); // End capture and discard
+        $this->assertTrue($result);
+        $this->assertTrue(strpos($contents,'[') === 0);
+        $this->assertTrue(strpos($contents,'[error]') !== false);
+        $this->assertTrue(strpos($contents, $message) !== false);
+        $this->assertTrue(substr_count($contents , '] ') >= 2);
+    }
+
+    /*
+     * test output_indented_logger class
+     */
+    function test_output_indented_logger() {
+        // Instantiate without date nor level output
+        $options = array('depth' => 2);
+        $lo = new output_indented_logger(backup::LOG_ERROR);
+        $this->assertTrue($lo instanceof output_indented_logger);
+        $message = 'testing output_indented_logger';
+        ob_start(); // Capture output
+        $result = $lo->process($message, backup::LOG_ERROR, $options);
+        $contents = ob_get_contents();
+        ob_end_clean(); // End capture and discard
+        $this->assertTrue($result);
+        if (defined('STDOUT')) {
+            $check = '  ';
+        } else {
+            $check = '&nbsp;&nbsp;';
+        }
+        $this->assertTrue(strpos($contents, str_repeat($check, $options['depth']) . $message) !== false);
+
+        // Instantiate with date and level output
+        $options = array('depth' => 3);
+        $lo = new output_indented_logger(backup::LOG_ERROR, true, true);
+        $this->assertTrue($lo instanceof output_indented_logger);
+        $message = 'testing output_indented_logger';
+        ob_start(); // Capture output
+        $result = $lo->process($message, backup::LOG_ERROR, $options);
+        $contents = ob_get_contents();
+        ob_end_clean(); // End capture and discard
+        $this->assertTrue($result);
+        $this->assertTrue(strpos($contents,'[') === 0);
+        $this->assertTrue(strpos($contents,'[error]') !== false);
+        $this->assertTrue(strpos($contents, $message) !== false);
+        $this->assertTrue(substr_count($contents , '] ') >= 2);
+        if (defined('STDOUT')) {
+            $check = '  ';
+        } else {
+            $check = '&nbsp;&nbsp;';
+        }
+        $this->assertTrue(strpos($contents, str_repeat($check, $options['depth']) . $message) !== false);
+    }
+
+    /*
+     * test database_logger class
+     */
+    function test_database_logger() {
+        // Instantiate with date and level output (and with specs from the global moodle "log" table so checks will pass
+        $now = time();
+        $datecol = 'time';
+        $levelcol = 'action';
+        $messagecol = 'info';
+        $logtable = 'log';
+        $columns = array('url' => 'http://127.0.0.1');
+        $loglevel = backup::LOG_ERROR;
+        $lo = new mock_database_logger(backup::LOG_ERROR, $datecol, $levelcol, $messagecol, $logtable, $columns);
+        $this->assertTrue($lo instanceof database_logger);
+        $message = 'testing database_logger';
+        $result = $lo->process($message, $loglevel);
+        // Check everything is ready to be inserted to DB
+        $this->assertEqual($result['table'], $logtable);
+        $this->assertTrue($result['columns'][$datecol] >= $now);
+        $this->assertEqual($result['columns'][$levelcol], $loglevel);
+        $this->assertEqual($result['columns'][$messagecol], $message);
+        $this->assertEqual($result['columns']['url'], $columns['url']);
+    }
+
+    /*
+     * test file_logger class
+     */
+    function test_file_logger() {
+        global $CFG;
+
+        $file = $CFG->dataroot . '/temp/test/test_file_logger.txt';
+        // Remove the test dir and any content
+        @remove_dir(dirname($file));
+        // Recreate test dir
+        if (!check_dir_exists(dirname($file), true, true)) {
+            throw moodle_exception('error_creating_temp_dir', 'error', dirname($file));
+        }
+
+        // Instantiate with date and level output, and also use the depth option
+        $options = array('depth' => 3);
+        $lo1 = new file_logger(backup::LOG_ERROR, true, true, $file);
+        $this->assertTrue($lo1 instanceof file_logger);
+        $message1 = 'testing file_logger';
+        $result = $lo1->process($message1, backup::LOG_ERROR, $options);
+        $this->assertTrue($result);
+
+        // Another file_logger is going towrite there too without closing
+        $options = array();
+        $lo2 = new file_logger(backup::LOG_WARNING, true, true, $file);
+        $this->assertTrue($lo2 instanceof file_logger);
+        $message2 = 'testing file_logger2';
+        $result = $lo2->process($message2, backup::LOG_WARNING, $options);
+        $this->assertTrue($result);
+
+        // Destruct loggers
+        $lo1 = null;
+        $lo2 = null;
+
+        // Load file results to analyze them
+        $fcontents = file_get_contents($file);
+        $acontents = explode(PHP_EOL, $fcontents); // Split by line
+        $this->assertTrue(strpos($acontents[0], $message1) !== false);
+        $this->assertTrue(strpos($acontents[0], '[error]') !== false);
+        $this->assertTrue(strpos($acontents[0], '      ') !== false);
+        $this->assertTrue(substr_count($acontents[0] , '] ') >= 2);
+        $this->assertTrue(strpos($acontents[1], $message2) !== false);
+        $this->assertTrue(strpos($acontents[1], '[warn]') !== false);
+        $this->assertTrue(strpos($acontents[1], '      ') === false);
+        $this->assertTrue(substr_count($acontents[1] , '] ') >= 2);
+        unlink($file); // delete file
+
+        // Try one html file
+        $file = $CFG->dataroot . '/temp/test/test_file_logger.html';
+        $options = array('depth' => 1);
+        $lo = new file_logger(backup::LOG_ERROR, true, true, $file);
+        $this->assertTrue($lo instanceof file_logger);
+        $this->assertTrue(file_exists($file));
+        $message = 'testing file_logger';
+        $result = $lo->process($message, backup::LOG_ERROR, $options);
+        // Get file contents and inspect them
+        $fcontents = file_get_contents($file);
+        $this->assertTrue($result);
+        $this->assertTrue(strpos($fcontents, $message) !== false);
+        $this->assertTrue(strpos($fcontents, '[error]') !== false);
+        $this->assertTrue(strpos($fcontents, '&nbsp;&nbsp;') !== false);
+        $this->assertTrue(substr_count($fcontents , '] ') >= 2);
+        unlink($file); // delete file
+
+        // Instantiate, write something, force deletion, try to write again
+        $file = $CFG->dataroot . '/temp/test/test_file_logger.html';
+        $lo = new mock_file_logger(backup::LOG_ERROR, true, true, $file);
+        $this->assertTrue(file_exists($file));
+        $message = 'testing file_logger';
+        $result = $lo->process($message, backup::LOG_ERROR);
+        fclose($lo->get_fhandle()); // close file
+        try {
+            $result = @$lo->process($message, backup::LOG_ERROR); // Try to write again
+            $this->assertTrue(false, 'base_logger_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof base_logger_exception);
+            $this->assertEqual($e->errorcode, 'error_writing_file');
+        }
+
+        // Instantiate without file
+        try {
+            $lo = new file_logger(backup::LOG_WARNING, true, true, '');
+            $this->assertTrue(false, 'base_logger_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof base_logger_exception);
+            $this->assertEqual($e->errorcode, 'missing_fullpath_parameter');
+        }
+
+        // Instantiate in (near) impossible path
+        $file =  $CFG->dataroot . '/temp/test_azby/test_file_logger.txt';
+        try {
+            $lo = new file_logger(backup::LOG_WARNING, true, true, $file);
+            $this->assertTrue(false, 'base_logger_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof base_logger_exception);
+            $this->assertEqual($e->errorcode, 'file_not_writable');
+            $this->assertEqual($e->a, $file);
+        }
+
+        // Instatiate one file logger with level = backup::LOG_NONE
+        $file =  $CFG->dataroot . '/temp/test/test_file_logger.txt';
+        $lo = new file_logger(backup::LOG_NONE, true, true, $file);
+        $this->assertTrue($lo instanceof file_logger);
+        $this->assertFalse(file_exists($file));
+
+        // Remove the test dir and any content
+        @remove_dir(dirname($file));
+    }
+}
+
+/*
+ * helper extended base_logger class that implements some methods for testing
+ * Simply return the product of message and level
+ */
+class mock_base_logger1 extends base_logger {
+
+    protected function action($message, $level, $options = null) {
+        return $message * $level; // Simply return that, for testing
+    }
+    public function get_levelstr($level) {
+        return parent::get_levelstr($level);
+    }
+}
+
+/*
+ * helper extended base_logger class that implements some methods for testing
+ * Simply return the sum of message and level
+ */
+class mock_base_logger2 extends base_logger {
+
+    protected function action($message, $level, $options = null) {
+        return $message + $level; // Simply return that, for testing
+    }
+}
+
+/*
+ * helper extended base_logger class that implements some methods for testing
+ * Simply return 8
+ */
+class mock_base_logger3 extends base_logger {
+
+    protected function action($message, $level, $options = null) {
+        return false; // Simply return false, for testing stopper
+    }
+}
+
+/*
+ * helper extended database_logger class that implements some methods for testing
+ * Returns the complete info that normally will be used by insert record calls
+ */
+class mock_database_logger extends database_logger {
+
+    protected function insert_log_record($table, $columns) {
+        return array('table' => $table, 'columns' => $columns);
+    }
+}
+
+/*
+ * helper extended file_logger class that implements some methods for testing
+ * Returns the, usually protected, fhandle
+ */
+class mock_file_logger extends file_logger {
+
+    function get_fhandle() {
+        return $this->fhandle;
+    }
+}
diff --git a/backup/util/output/output_controller.class.php b/backup/util/output/output_controller.class.php
new file mode 100644 (file)
index 0000000..62b52b7
--- /dev/null
@@ -0,0 +1,74 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-output
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ *
+ * TODO: Finish phpdocs
+ */
+
+/**
+ * This class decides, based in environment/backup controller settings about
+ * the best way to send information to output, independently of the process
+ * and the loggers. Instantiated/configured by @backup_controller constructor
+ *
+ * Mainly used by backup_helper::log() (that receives all the log requests from
+ * the rest of backup objects) to split messages both to loggers and to output.
+ *
+ * This class adopts the singleton pattern to be able to provide some persistency
+ * and global access.
+ */
+class output_controller {
+
+    private static $instance; // The unique instance of output_controller available along the request
+    private $list;            // progress_trace object we are going to use for output
+    private $active;          // To be able to stop output completely or active it again
+
+    private function __construct() { // Private constructor
+        if (defined('STDOUT')) { // text mode
+            $this->list = new text_progress_trace();
+        } else {
+            $this->list = new html_list_progress_trace();
+        }
+        $this->active = false; // Somebody has to active me before outputing anything
+    }
+
+    public static function get_instance() {
+        if (!isset(self::$instance)) {
+            self::$instance = new output_controller();
+        }
+        return self::$instance;
+    }
+
+    public function set_active($active) {
+        if ($this->active && (bool)$active == false) { // Stopping, call finished()
+            $this->list->finished();
+        }
+        $this->active = (bool)$active;
+    }
+
+    public function output($message, $langfile, $a, $depth) {
+        if ($this->active) {
+            $stringkey = preg_replace('/\s/', '', $message); // String key is message without whitespace
+            $message = get_string($stringkey, $langfile, $a);
+            $this->list->output($message, $depth);
+        }
+    }
+}
diff --git a/backup/util/plan/backup_execution_step.class.php b/backup/util/plan/backup_execution_step.class.php
new file mode 100644 (file)
index 0000000..20a4450
--- /dev/null
@@ -0,0 +1,43 @@
+<?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/>.
+
+/**
+ * @package moodlecore
+ * @subpackage backup-plan
+ * @copyright 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Abstract class defining the needed stuff to execute code on backup
+ *
+ * TODO: Finish phpdocs
+ */
+abstract class backup_execution_step extends backup_step {
+
+    public function execute() {
+        // Simple, for now
+        $this->define_execution();
+    }
+
+// Protected API starts here
+
+    /**
+     * Function that will contain all the code to be executed
+     */
+    abstract protected function define_execution();
+}
diff --git a/backup/util/plan/backup_plan.class.php b/backup/util/plan/backup_plan.class.php
new file mode 100644 (file)
index 0000000..39fb6f8
--- /dev/null
@@ -0,0 +1,95 @@
+<?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/>.
+
+/**
+ * @package moodlecore
+ * @subpackage backup-plan
+ * @copyright 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Implementable class defining the needed stuf for one backup plan
+ *
+ * TODO: Finish phpdocs
+ */
+class backup_plan extends base_plan implements loggable {
+
+    protected $controller; // The backup controller building/executing this plan
+    protected $basepath;   // Fullpath to dir where backup is created
+
+    /**
+     * Constructor - instantiates one object of this class
+     */
+    public function __construct($controller) {
+        global $CFG;
+
+        if (! $controller instanceof backup_controller) {
+            throw new backup_plan_exception('wrong_backup_controller_specified');
+        }
+        $this->controller = $controller;
+        $this->basepath   = $CFG->dataroot . '/temp/backup/' . $controller->get_backupid();
+        parent::__construct('backup_plan');
+    }
+
+    public function build() {
+        backup_factory::build_plan($this->controller); // Dispatch to correct format
+        $this->built = true;
+    }
+
+    public function get_backupid() {
+        return $this->controller->get_backupid();
+    }
+
+    public function get_courseid() {
+        return $this->controller->get_courseid();
+    }
+
+    public function get_basepath() {
+        return $this->basepath;
+    }
+
+    public function get_logger() {
+        return $this->controller->get_logger();
+    }
+
+    public function log($message, $level, $a = null, $depth = null, $display = false) {
+        backup_helper::log($message, $level, $a, $depth, $display, $this->get_logger());
+    }
+
+    /**
+     * Function responsible for executing the tasks of any plan
+     */
+    public function execute() {
+        if ($this->controller->get_status() != backup::STATUS_AWAITING) {
+            throw new backup_controller_exception('backup_not_executable_awaiting_required', $this->controller->get_status());
+        }
+        $this->controller->set_status(backup::STATUS_EXECUTING);
+        parent::execute();
+        $this->controller->set_status(backup::STATUS_FINISHED_OK);
+    }
+}
+
+/*
+ * Exception class used by all the @backup_plan stuff
+ */
+class backup_plan_exception extends base_plan_exception {
+
+    public function __construct($errorcode, $a=NULL, $debuginfo=null) {
+        parent::__construct($errorcode, $a, $debuginfo);
+    }
+}
diff --git a/backup/util/plan/backup_step.class.php b/backup/util/plan/backup_step.class.php
new file mode 100644 (file)
index 0000000..2604ddd
--- /dev/null
@@ -0,0 +1,51 @@
+<?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/>.
+
+/**
+ * @package moodlecore
+ * @subpackage backup-plan
+ * @copyright 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Abstract class defining the needed stuf for one backup step
+ *
+ * TODO: Finish phpdocs
+ */
+abstract class backup_step extends base_step {
+
+    /**
+     * Constructor - instantiates one object of this class
+     */
+    public function __construct($name, $task = null) {
+        if (!is_null($task) && !($task instanceof backup_task)) {
+            throw new backup_step_exception('wrong_backup_task_specified');
+        }
+        parent::__construct($name, $task);
+    }
+}
+
+/*
+ * Exception class used by all the @backup_step stuff
+ */
+class backup_step_exception extends base_step_exception {
+
+    public function __construct($errorcode, $a=NULL, $debuginfo=null) {
+        parent::__construct($errorcode, $a, $debuginfo);
+    }
+}
diff --git a/backup/util/plan/backup_structure_step.class.php b/backup/util/plan/backup_structure_step.class.php
new file mode 100644 (file)
index 0000000..223ab9e
--- /dev/null
@@ -0,0 +1,114 @@
+<?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/>.
+
+/**
+ * @package moodlecore
+ * @subpackage backup-plan
+ * @copyright 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Abstract class defining the needed stuff to backup one @backup_structure
+ *
+ * TODO: Finish phpdocs
+ */
+abstract class backup_structure_step extends backup_step {
+
+    protected $filename; // Name of the file to be generated
+    protected $contenttransformer; // xml content transformer being used
+                                   // (need it here, apart from xml_writer,
+                                   // thanks to serialized data to process -
+                                   // say thanks to blocks!)
+
+    /**
+     * Constructor - instantiates one object of this class
+     */
+    public function __construct($name, $filename, $task = null) {
+        if (!is_null($task) && !($task instanceof backup_task)) {
+            throw new backup_step_exception('wrong_backup_task_specified');
+        }
+        $this->filename = $filename;
+        parent::__construct($name, $task);
+    }
+
+    public function execute() {
+
+        $fullpath = $this->task->get_taskbasepath();
+
+        // We MUST have one fullpath here, else, error
+        if (empty($fullpath)) {
+            throw new backup_step_exception('backup_structure_step_undefined_fullpath');
+        }
+
+        // Append the filename to the fullpath
+        $fullpath = rtrim($fullpath, '/') . '/' . $this->filename;
+
+        // Create output, transformer, writer, processor
+        $xo = new file_xml_output($fullpath);
+        $xt = null;
+        if (class_exists('backup_xml_transformer')) {
+            $xt = new backup_xml_transformer($this->get_courseid());
+            $this->contenttransformer = $xt; // Save the reference to the transformer
+                                             // as far as we are going to need it out
+                                             // from xml_writer (blame serialized data!)
+        }
+        $xw = new xml_writer($xo, $xt);
+        $pr = new backup_structure_processor($xw);
+
+        // Set processor variables from settings
+        foreach ($this->get_settings() as $setting) {
+            $pr->set_var($setting->get_name(), $setting->get_value());
+        }
+        // Add backupid as one more var for processor
+        $pr->set_var(backup::VAR_BACKUPID, $this->get_backupid());
+
+        // Get structure definition
+        $structure = $this->define_structure();
+        if (! $structure instanceof backup_nested_element) {
+            throw new backup_step_exception('backup_structure_step_wrong_structure');
+        }
+
+        // Start writer
+        $xw->start();
+
+        // Process structure definition
+        $structure->process($pr);
+
+        // Close everything
+        $xw->stop();
+    }
+
+// Protected API starts here
+
+    /**
+     * This function simply marks one param to be considered as straight sql
+     * param, so it won't be searched in the structure tree nor converted at
+     * all. Useful for better integration of definition of sources in structure
+     * and DB stuff.
+     */
+    protected function is_sqlparam($value) {
+        return array('sqlparam' => $value);
+    }
+
+
+    /**
+     * Function that will return the structure to be processed by this backup_step.
+     * Must return one backup_nested_element
+     */
+    abstract protected function define_structure();
+}
diff --git a/backup/util/plan/backup_task.class.php b/backup/util/plan/backup_task.class.php
new file mode 100644 (file)
index 0000000..f5e620d
--- /dev/null
@@ -0,0 +1,51 @@
+<?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/>.
+
+/**
+ * @package moodlecore
+ * @subpackage backup-plan
+ * @copyright 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Abstract class defining the needed stuf for one backup task (a collection of steps)
+ *
+ * TODO: Finish phpdocs
+ */
+abstract class backup_task extends base_task {
+
+    /**
+     * Constructor - instantiates one object of this class
+     */
+    public function __construct($name, $plan = null) {
+        if (!is_null($plan) && !($plan instanceof backup_plan)) {
+            throw new backup_task_exception('wrong_backup_plan_specified');
+        }
+        parent::__construct($name, $plan);
+    }
+}
+
+/*
+ * Exception class used by all the @backup_task stuff
+ */
+class backup_task_exception extends base_task_exception {
+
+    public function __construct($errorcode, $a=NULL, $debuginfo=null) {
+        parent::__construct($errorcode, $a, $debuginfo);
+    }
+}
diff --git a/backup/util/plan/base_plan.class.php b/backup/util/plan/base_plan.class.php
new file mode 100644 (file)
index 0000000..b551dca
--- /dev/null
@@ -0,0 +1,139 @@
+<?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/>.
+
+/**
+ * @package moodlecore
+ * @subpackage backup-plan
+ * @copyright 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Abstract class defining the basis for one execution (backup/restore) plan
+ *
+ * TODO: Finish phpdocs
+ */
+abstract class base_plan implements checksumable, executable {
+
+    protected $name;      // One simple name for identification purposes
+    protected $settings;  // One array of (accumulated from tasks) base_setting elements
+    protected $tasks;     // One array of base_task elements
+
+    protected $built;     // Flag to know if one plan has been built
+
+    /**
+     * Constructor - instantiates one object of this class
+     */
+    public function __construct($name) {
+        $this->name = $name;
+        $this->settings = array();
+        $this->tasks    = array();
+        $this->built = false;
+    }
+
+    public function get_name() {
+        return $this->name;
+    }
+
+    public function add_task($task) {
+        if (! $task instanceof base_task) {
+            throw new base_plan_exception('wrong_base_task_specified');
+        }
+        $this->tasks[] = $task;
+        // link the task with the plan
+        $task->set_plan($this);
+        // Append task settings to plan array, if not present, for comodity
+        foreach ($task->get_settings() as $key => $setting) {
+            if (!in_array($setting, $this->settings)) {
+                $this->settings[] = $setting;
+            }
+        }
+    }
+
+    public function get_tasks() {
+        return $this->tasks;
+    }
+
+    public function get_settings() {
+        return $this->settings;
+    }
+
+    /**
+     * return one setting by name, useful to request root/course settings
+     * that are, by definition, unique by name. Throws exception if multiple
+     * are found
+     *
+     * TODO: Change this to string indexed array for quicker lookup. Not critical
+     */
+    public function get_setting($name) {
+        $result = null;
+        foreach ($this->settings as $key => $setting) {
+            if ($setting->get_name() == $name) {
+                if ($result != null) {
+                    throw new base_plan_exception('multiple_settings_by_name_found', $name);
+                } else {
+                    $result = $setting;
+                }
+            }
+        }
+        if (!$result) {
+            throw new base_plan_exception('setting_by_name_not_found', $name);
+        }
+        return $result;
+    }
+
+
+    /**
+     * Function responsible for building the tasks of any plan
+     * with their corresponding settings
+     * (must set the $built property to true)
+     */
+    public abstract function build();
+
+    public function is_checksum_correct($checksum) {
+        return $this->calculate_checksum() === $checksum;
+    }
+
+    public function calculate_checksum() {
+        // Let's do it using name and tasks (settings are part of tasks)
+        return md5($this->name . '-' . backup_general_helper::array_checksum_recursive($this->tasks));
+    }
+
+    /**
+     * Function responsible for executing the tasks of any plan
+     */
+    public function execute() {
+        if (!$this->built) {
+            throw new base_plan_exception('base_plan_not_built');
+        }
+        foreach ($this->tasks as $task) {
+            $task->build();
+            $task->execute();
+        }
+    }
+}
+
+
+/*
+ * Exception class used by all the @base_plan stuff
+ */
+class base_plan_exception extends moodle_exception {
+
+    public function __construct($errorcode, $a=NULL, $debuginfo=null) {
+        parent::__construct($errorcode, '', '', $a, $debuginfo);
+    }
+}
diff --git a/backup/util/plan/base_step.class.php b/backup/util/plan/base_step.class.php
new file mode 100644 (file)
index 0000000..efaa092
--- /dev/null
@@ -0,0 +1,122 @@
+<?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/>.
+
+/**
+ * @package moodlecore
+ * @subpackage backup-plan
+ * @copyright 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Abstract class defining the basis for one execution (backup/restore) step
+ *
+ * TODO: Finish phpdocs
+ */
+abstract class base_step implements executable, loggable {
+
+    protected $name;      // One simple name for identification purposes
+    protected $task;      // Task this is part of
+
+    /**
+     * Constructor - instantiates one object of this class
+     */
+    public function __construct($name, $task = null) {
+        if (!is_null($task) && !($task instanceof base_task)) {
+            throw new base_step_exception('wrong_base_task_specified');
+        }
+        $this->name = $name;
+        $this->task = $task;
+        if (!is_null($task)) { // Add the step to the task if specified
+            $task->add_step($this);
+        }
+    }
+
+    public function get_name() {
+        return $this->name;
+    }
+
+    public function set_task($task) {
+        if (! $task instanceof base_task) {
+            throw new base_step_exception('wrong_base_task_specified');
+        }
+        $this->task = $task;
+    }
+
+    public function log($message, $level, $a = null, $depth = null, $display = false) {
+        if (is_null($this->task)) {
+            throw new base_step_exception('not_specified_base_task');
+        }
+        backup_helper::log($message, $level, $a, $depth, $display, $this->get_logger());
+    }
+
+/// Protected API starts here
+
+    protected function get_settings() {
+        if (is_null($this->task)) {
+            throw new base_step_exception('not_specified_base_task');
+        }
+        return $this->task->get_settings();
+    }
+
+    protected function get_setting($name) {
+        if (is_null($this->task)) {
+            throw new base_step_exception('not_specified_base_task');
+        }
+        return $this->task->get_setting($name);
+    }
+
+    protected function get_setting_value($name) {
+        if (is_null($this->task)) {
+            throw new base_step_exception('not_specified_base_task');
+        }
+        return $this->task->get_setting_value($name);
+    }
+
+    protected function get_backupid() {
+        if (is_null($this->task)) {
+            throw new base_step_exception('not_specified_base_task');
+        }
+        return $this->task->get_backupid();
+    }
+
+    protected function get_courseid() {
+        if (is_null($this->task)) {
+            throw new base_step_exception('not_specified_base_task');
+        }
+        return $this->task->get_courseid();
+    }
+
+    protected function get_basepath() {
+        return $this->task->get_basepath();
+    }
+
+    protected function get_logger() {
+        return $this->task->get_logger();
+    }
+}
+
+
+/*
+ * Exception class used by all the @base_step stuff
+ */
+class base_step_exception extends moodle_exception {
+
+    public function __construct($errorcode, $a=NULL, $debuginfo=null) {
+        parent::__construct($errorcode, '', '', $a, $debuginfo);
+    }
+}
diff --git a/backup/util/plan/base_task.class.php b/backup/util/plan/base_task.class.php
new file mode 100644 (file)
index 0000000..0aafe72
--- /dev/null
@@ -0,0 +1,187 @@
+<?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/>.
+
+/**
+ * @package moodlecore
+ * @subpackage backup-plan
+ * @copyright 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Abstract class defining the basis for one execution (backup/restore) task
+ *
+ * TODO: Finish phpdocs
+ */
+abstract class base_task implements checksumable, executable, loggable {
+
+    protected $name;      // One simple name for identification purposes
+    protected $plan;      // Plan this is part of
+    protected $settings;  // One array of base_setting elements to define this task
+    protected $steps;     // One array of base_task elements
+
+    protected $built;     // Flag to know if one plan has been built
+
+    /**
+     * Constructor - instantiates one object of this class
+     */
+    public function __construct($name, $plan = null) {
+        if (!is_null($plan) && !($plan instanceof base_plan)) {
+            throw new base_task_exception('wrong_base_plan_specified');
+        }
+        $this->name = $name;
+        $this->plan = $plan;
+        $this->settings = array();
+        $this->steps    = array();
+        $this->built = false;
+        if (!is_null($plan)) { // Add the task to the plan if specified
+            $plan->add_task($this);
+        }
+    }
+
+    public function get_name() {
+        return $this->name;
+    }
+
+    public function get_steps() {
+        return $this->steps;
+    }
+
+    public function get_settings() {
+        return $this->settings;
+    }
+
+    public function get_setting($name) {
+        // First look in task settings
+        $result = null;
+        foreach ($this->settings as $key => $setting) {
+            if ($setting->get_name() == $name) {
+                if ($result != null) {
+                    throw new base_task_exception('multiple_settings_by_name_found', $name);
+                } else {
+                    $result = $setting;
+                }
+            }
+        }
+        if ($result) {
+            return $result;
+        } else {
+            // Fallback to plan settings
+            return $this->plan->get_setting($name);
+        }
+    }
+
+    public function get_setting_value($name) {
+        return $this->get_setting($name)->get_value();
+    }
+
+    public function get_backupid() {
+        return $this->plan->get_backupid();
+    }
+
+    public function get_courseid() {
+        return $this->plan->get_courseid();
+    }
+
+    public function get_basepath() {
+        return $this->plan->get_basepath();
+    }
+
+    public function get_taskbasepath() {
+        return $this->get_basepath();
+    }
+
+    public function get_logger() {
+        return $this->plan->get_logger();
+    }
+
+    public function log($message, $level, $a = null, $depth = null, $display = false) {
+        backup_helper::log($message, $level, $a, $depth, $display, $this->get_logger());
+    }
+
+    public function add_step($step) {
+        if (! $step instanceof base_step) {
+            throw new base_task_exception('wrong_base_step_specified');
+        }
+        // link the step with the task
+        $step->set_task($this);
+        $this->steps[] = $step;
+    }
+
+    public function set_plan($plan) {
+        if (! $plan instanceof base_plan) {
+            throw new base_task_exception('wrong_base_plan_specified');
+        }
+        $this->plan = $plan;
+        $this->define_settings(); // Settings are defined when plan & task are linked
+    }
+
+    /**
+     * Function responsible for building the steps of any task
+     * (must set the $built property to true)
+     */
+    public abstract function build();
+
+    /**
+     * Function responsible for executing the steps of any task
+     */
+    public function execute() {
+        if (!$this->built) {
+            throw new base_task_exception('base_task_not_built', $this->name);
+        }
+        foreach ($this->steps as $step) {
+            $step->execute();
+        }
+    }
+
+    public function is_checksum_correct($checksum) {
+        return $this->calculate_checksum() === $checksum;
+    }
+
+    public function calculate_checksum() {
+        // Let's do it using name and settings and steps
+        return md5($this->name . '-' .
+                   backup_general_helper::array_checksum_recursive($this->settings) .
+                   backup_general_helper::array_checksum_recursive($this->steps));
+    }
+
+// Protected API starts here
+
+    /**
+     * This function is invoked on activity creation in order to add all the settings
+     * that are associated with one task. The function will, directly, inject the settings
+     * in the task.
+     */
+    protected abstract function define_settings();
+
+    protected function add_setting($setting) {
+        if (! $setting instanceof base_setting) {
+            throw new base_setting_exception('wrong_base_setting_specified');
+        }
+        $this->settings[] = $setting;
+    }
+}
+
+/*
+ * Exception class used by all the @base_task stuff
+ */
+class base_task_exception extends moodle_exception {
+
+    public function __construct($errorcode, $a=NULL, $debuginfo=null) {
+        parent::__construct($errorcode, '', '', $a, $debuginfo);
+    }
+}
diff --git a/backup/util/plan/simpletest/testplan.php b/backup/util/plan/simpletest/testplan.php
new file mode 100644 (file)
index 0000000..d5b9708
--- /dev/null
@@ -0,0 +1,211 @@
+<?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/>.
+
+/**
+ * @package moodlecore
+ * @subpackage backup-tests
+ * @copyright 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+// Prevent direct access to this file
+if (!defined('MOODLE_INTERNAL')) {
+    die('Direct access to this script is forbidden.');
+}
+
+// Include all the needed stuff
+require_once($CFG->dirroot . '/backup/util/includes/backup_includes.php');
+
+/*
+ * plan tests (all)
+ */
+class backup_plan_test extends UnitTestCase {
+
+    public static $includecoverage = array('backup/util/plan');
+    public static $excludecoverage = array('backup/util/plan/simpletest');
+
+    protected $moduleid;  // course_modules id used for testing
+    protected $sectionid; // course_sections id used for testing
+    protected $courseid;  // course id used for testing
+    protected $user;      // user record used for testing
+
+    function __construct() {
+        global $DB, $USER, $CFG;
+
+        $this->moduleid  = 0;
+        $this->sectionid = 0;
+        $this->courseid  = 0;
+        $this->userid = $USER->id;
+        $this->todelete = array();
+
+        // Check we have (at least) one course_module
+        if ($coursemodule = $DB->get_record('course_modules', array(), '*', IGNORE_MULTIPLE)) {
+            $this->moduleid  = $coursemodule->id;
+            $this->sectionid = $coursemodule->section;
+            $this->courseid  = $coursemodule->course;
+        }
+
+        // Avoid any logger to be created, we'll restore original settings on tearDown()
+        $this->errorlogloggerlevel = isset($CFG->backup_error_log_logger_level) ? $CFG->backup_error_log_logger_level : null;
+        $this->fileloggerlevel = isset($CFG->backup_file_logger_level) ? $CFG->backup_file_logger_level : null;
+        $this->databaseloggerlevel = isset($CFG->backup_database_logger_level) ? $CFG->backup_database_logger_level : null;
+        $this->fileloggerlevelextra = isset($CFG->backup_file_logger_level_extra) ? $CFG->backup_file_logger_level_extra : null;
+
+        parent::__construct();
+    }
+
+    function skip() {
+        $this->skipIf(empty($this->moduleid), 'backup_plan_test require at least one course module to exist');
+        $this->skipIf(empty($this->sectionid),'backup_plan_test require at least one course section to exist');
+        $this->skipIf(empty($this->courseid), 'backup_plan_test require at least one course to exist');
+        $this->skipIf(empty($this->userid),'backup_plan_test require one valid user to exist');
+    }
+
+    function setUp() {
+        global $CFG;
+
+        // Disable all loggers
+        $CFG->backup_error_log_logger_level = backup::LOG_NONE;
+        $CFG->backup_file_logger_level = backup::LOG_NONE;
+        $CFG->backup_database_logger_level = backup::LOG_NONE;
+        $CFG->backup_file_logger_level_extra = backup::LOG_NONE;
+    }
+
+    function tearDown() {
+        global $DB, $CFG;
+        // Delete all the records marked to
+        foreach ($this->todelete as $todelete) {
+            $DB->delete_records($todelete[0], array('id' => $todelete[1]));
+        }
+        // Restore original file_logger levels
+        if ($this->errorlogloggerlevel !== null) {
+            $CFG->backup_error_log_logger_level = $this->errorlogloggerlevel;
+        } else {
+            unset($CFG->backup_error_log_logger_level);
+        }
+        if ($this->fileloggerlevel !== null) {
+            $CFG->backup_file_logger_level = $this->fileloggerlevel;
+        } else {
+            unset($CFG->backup_file_logger_level);
+        }
+        if ($this->databaseloggerlevel !== null) {
+            $CFG->backup_database_logger_level = $this->databaseloggerlevel;
+        } else {
+            unset($CFG->backup_database_logger_level);
+        }
+        if ($this->fileloggerlevelextra !== null) {
+            $CFG->backup_file_logger_level_extra = $this->fileloggerlevelextra;
+        } else {
+            unset($CFG->backup_file_logger_level_extra);
+        }
+    }
+
+    /**
+     * test base_plan class
+     */
+    function test_base_plan() {
+
+        // Instantiate
+        $bp = new mock_base_plan('name');
+        $this->assertTrue($bp instanceof base_plan);
+        $this->assertEqual($bp->get_name(), 'name');
+        $this->assertTrue(is_array($bp->get_settings()));
+        $this->assertEqual(count($bp->get_settings()), 0);
+        $this->assertTrue(is_array($bp->get_tasks()));
+        $this->assertEqual(count($bp->get_tasks()), 0);
+    }
+
+    /*
+     * test backup_plan class
+     */
+    function test_backup_plan() {
+
+        // We need one (non interactive) controller for instatiating plan
+        $bc = new backup_controller(backup::TYPE_1ACTIVITY, $this->moduleid, backup::FORMAT_MOODLE,
+                                    backup::INTERACTIVE_NO, backup::MODE_GENERAL, $this->userid);
+        // Instantiate one backup plan
+        $bp = new backup_plan($bc);
+        $this->assertTrue($bp instanceof backup_plan);
+        $this->assertEqual($bp->get_name(), 'backup_plan');
+
+        // Calculate checksum and check it
+        $checksum = $bp->calculate_checksum();
+        $this->assertTrue($bp->is_checksum_correct($checksum));
+    }
+
+    /**
+     * wrong base_plan class tests
+     */
+    function test_base_plan_wrong() {
+
+        // We need one (non interactive) controller for instatiating plan
+        $bc = new backup_controller(backup::TYPE_1ACTIVITY, $this->moduleid, backup::FORMAT_MOODLE,
+                                    backup::INTERACTIVE_NO, backup::MODE_GENERAL, $this->userid);
+        // Instantiate one backup plan
+        $bp = new backup_plan($bc);
+        // Add wrong task
+        try {
+            $bp->add_task(new stdclass());
+            $this->assertTrue(false, 'base_plan_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof base_plan_exception);
+            $this->assertEqual($e->errorcode, 'wrong_base_task_specified');
+        }
+    }
+
+    /**
+     * wrong backup_plan class tests
+     */
+    function test_backup_plan_wrong() {
+
+        // Try to pass one wrong controller
+        try {
+            $bp = new backup_plan(new stdclass());
+            $this->assertTrue(false, 'backup_plan_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof backup_plan_exception);
+            $this->assertEqual($e->errorcode, 'wrong_backup_controller_specified');
+        }
+        try {
+            $bp = new backup_plan(null);
+            $this->assertTrue(false, 'backup_plan_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof backup_plan_exception);
+            $this->assertEqual($e->errorcode, 'wrong_backup_controller_specified');
+        }
+
+        // Try to build one non-existent format plan (when creating the controller)
+        // We need one (non interactive) controller for instatiating plan
+        try {
+            $bc = new backup_controller(backup::TYPE_1ACTIVITY, $this->moduleid, 'non_existing_format',
+                                        backup::INTERACTIVE_NO, backup::MODE_GENERAL, $this->userid);
+            $this->assertTrue(false, 'backup_controller_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof backup_controller_exception);
+            $this->assertEqual($e->errorcode, 'backup_check_unsupported_format');
+            $this->assertEqual($e->a, 'non_existing_format');
+        }
+    }
+}
+
+/**
+ * Instantiable class extending base_plan in order to be able to perform tests
+ */
+class mock_base_plan extends base_plan {
+    public function build() {
+    }
+}
diff --git a/backup/util/plan/simpletest/teststep.php b/backup/util/plan/simpletest/teststep.php
new file mode 100644 (file)
index 0000000..e66aca6
--- /dev/null
@@ -0,0 +1,336 @@
+<?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/>.
+
+/**
+ * @package moodlecore
+ * @subpackage backup-tests
+ * @copyright 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+// Prevent direct access to this file
+if (!defined('MOODLE_INTERNAL')) {
+    die('Direct access to this script is forbidden.');
+}
+
+// Include all the needed stuff
+require_once($CFG->dirroot . '/backup/util/interfaces/checksumable.class.php');
+require_once($CFG->dirroot . '/backup/util/interfaces/processable.class.php');
+require_once($CFG->dirroot . '/backup/util/interfaces/annotable.class.php');
+require_once($CFG->dirroot . '/backup/util/interfaces/executable.class.php');
+require_once($CFG->dirroot . '/backup/backup.class.php');
+require_once($CFG->dirroot . '/backup/util/factories/backup_factory.class.php');
+require_once($CFG->dirroot . '/backup/util/helper/backup_array_iterator.class.php');
+require_once($CFG->dirroot . '/backup/util/dbops/backup_dbops.class.php');
+require_once($CFG->dirroot . '/backup/util/dbops/backup_controller_dbops.class.php');
+require_once($CFG->dirroot . '/backup/util/dbops/backup_structure_dbops.class.php');
+require_once($CFG->dirroot . '/backup/util/helper/backup_helper.class.php');
+require_once($CFG->dirroot . '/backup/util/helper/backup_general_helper.class.php');
+require_once($CFG->dirroot . '/backup/util/checks/backup_check.class.php');
+require_once($CFG->dirroot . '/backup/util/loggers/base_logger.class.php');
+require_once($CFG->dirroot . '/backup/util/loggers/error_log_logger.class.php');
+require_once($CFG->dirroot . '/backup/util/loggers/file_logger.class.php');
+require_once($CFG->dirroot . '/backup/util/loggers/database_logger.class.php');
+require_once($CFG->dirroot . '/backup/util/loggers/output_indented_logger.class.php');
+require_once($CFG->dirroot . '/backup/util/xml/output/xml_output.class.php');
+require_once($CFG->dirroot . '/backup/util/xml/output/file_xml_output.class.php');
+require_once($CFG->dirroot . '/backup/util/xml/xml_writer.class.php');
+require_once($CFG->dirroot . '/backup/util/structure/base_atom.class.php');
+require_once($CFG->dirroot . '/backup/util/structure/base_attribute.class.php');
+require_once($CFG->dirroot . '/backup/util/structure/base_final_element.class.php');
+require_once($CFG->dirroot . '/backup/util/structure/base_nested_element.class.php');
+require_once($CFG->dirroot . '/backup/util/structure/base_optigroup.class.php');
+require_once($CFG->dirroot . '/backup/util/structure/base_processor.class.php');
+require_once($CFG->dirroot . '/backup/util/structure/backup_attribute.class.php');
+require_once($CFG->dirroot . '/backup/util/structure/backup_final_element.class.php');
+require_once($CFG->dirroot . '/backup/util/structure/backup_nested_element.class.php');
+require_once($CFG->dirroot . '/backup/util/structure/backup_optigroup.class.php');
+require_once($CFG->dirroot . '/backup/util/structure/backup_optigroup_element.class.php');
+require_once($CFG->dirroot . '/backup/util/structure/backup_structure_processor.class.php');
+require_once($CFG->dirroot . '/backup/controller/backup_controller.class.php');
+require_once($CFG->dirroot . '/backup/util/settings/base_setting.class.php');
+require_once($CFG->dirroot . '/backup/util/settings/backup_setting.class.php');
+require_once($CFG->dirroot . '/backup/util/settings/activity/activity_backup_setting.class.php');
+require_once($CFG->dirroot . '/backup/util/plan/base_plan.class.php');
+require_once($CFG->dirroot . '/backup/util/plan/backup_plan.class.php');
+require_once($CFG->dirroot . '/backup/util/plan/base_task.class.php');
+require_once($CFG->dirroot . '/backup/util/plan/backup_task.class.php');
+require_once($CFG->dirroot . '/backup/util/plan/base_step.class.php');
+require_once($CFG->dirroot . '/backup/util/plan/backup_step.class.php');
+require_once($CFG->dirroot . '/backup/util/plan/backup_structure_step.class.php');
+
+/*
+ * step tests (all)
+ */
+class backup_step_test extends UnitTestCase {
+
+    public static $includecoverage = array('backup/util/plan');
+    public static $excludecoverage = array('backup/util/plan/simpletest');
+
+    protected $moduleid;  // course_modules id used for testing
+    protected $sectionid; // course_sections id used for testing
+    protected $courseid;  // course id used for testing
+    protected $user;      // user record used for testing
+
+    function __construct() {
+        global $DB, $USER, $CFG;
+
+        $this->moduleid  = 0;
+        $this->sectionid = 0;
+        $this->courseid  = 0;
+        $this->userid = $USER->id;
+        $this->todelete = array();
+
+        // Check we have (at least) one course_module
+        if ($coursemodule = $DB->get_record('course_modules', array(), '*', IGNORE_MULTIPLE)) {
+            $this->moduleid  = $coursemodule->id;
+            $this->sectionid = $coursemodule->section;
+            $this->courseid  = $coursemodule->course;
+        }
+
+        // Avoid any logger to be created, we'll restore original settings on tearDown()
+        $this->errorlogloggerlevel = isset($CFG->backup_error_log_logger_level) ? $CFG->backup_error_log_logger_level : null;
+        $this->fileloggerlevel = isset($CFG->backup_file_logger_level) ? $CFG->backup_file_logger_level : null;
+        $this->databaseloggerlevel = isset($CFG->backup_database_logger_level) ? $CFG->backup_database_logger_level : null;
+        $this->fileloggerlevelextra = isset($CFG->backup_file_logger_level_extra) ? $CFG->backup_file_logger_level_extra : null;
+
+        parent::__construct();
+    }
+
+    function skip() {
+        $this->skipIf(empty($this->moduleid), 'backup_step_test require at least one course module to exist');
+        $this->skipIf(empty($this->sectionid),'backup_step_test require at least one course section to exist');
+        $this->skipIf(empty($this->courseid), 'backup_step_test require at least one course to exist');
+        $this->skipIf(empty($this->userid),'backup_step_test require one valid user to exist');
+    }
+
+    function setUp() {
+        global $CFG;
+
+        // Disable all loggers
+        $CFG->backup_error_log_logger_level = backup::LOG_NONE;
+        $CFG->backup_file_logger_level = backup::LOG_NONE;
+        $CFG->backup_database_logger_level = backup::LOG_NONE;
+        $CFG->backup_file_logger_level_extra = backup::LOG_NONE;
+    }
+
+    function tearDown() {
+        global $DB, $CFG;
+        // Delete all the records marked to
+        foreach ($this->todelete as $todelete) {
+            $DB->delete_records($todelete[0], array('id' => $todelete[1]));
+        }
+        // Restore original file_logger levels
+        if ($this->errorlogloggerlevel !== null) {
+            $CFG->backup_error_log_logger_level = $this->errorlogloggerlevel;
+        } else {
+            unset($CFG->backup_error_log_logger_level);
+        }
+        if ($this->fileloggerlevel !== null) {
+            $CFG->backup_file_logger_level = $this->fileloggerlevel;
+        } else {
+            unset($CFG->backup_file_logger_level);
+        }
+        if ($this->databaseloggerlevel !== null) {
+            $CFG->backup_database_logger_level = $this->databaseloggerlevel;
+        } else {
+            unset($CFG->backup_database_logger_level);
+        }
+        if ($this->fileloggerlevelextra !== null) {
+            $CFG->backup_file_logger_level_extra = $this->fileloggerlevelextra;
+        } else {
+            unset($CFG->backup_file_logger_level_extra);
+        }
+    }
+
+    /**
+     * test base_step class
+     */
+    function test_base_step() {
+
+        $bp = new mock_base_plan('planname'); // We need one plan
+        $bt = new mock_base_task('taskname', $bp); // We need one task
+        // Instantiate
+        $bs = new mock_base_step('stepname', $bt);
+        $this->assertTrue($bs instanceof base_step);
+        $this->assertEqual($bs->get_name(), 'stepname');
+    }
+
+    /*
+     * test backup_step class
+     */
+    function test_backup_step() {
+
+        // We need one (non interactive) controller for instatiating plan
+        $bc = new backup_controller(backup::TYPE_1ACTIVITY, $this->moduleid, backup::FORMAT_MOODLE,
+                                    backup::INTERACTIVE_NO, backup::MODE_GENERAL, $this->userid);
+        // We need one plan
+        $bp = new backup_plan($bc);
+        // We need one task
+        $bt = new mock_backup_task('taskname', $bp);
+        // Instantiate step
+        $bs = new mock_backup_step('stepname', $bt);
+        $this->assertTrue($bs instanceof backup_step);
+        $this->assertEqual($bs->get_name(), 'stepname');
+
+    }
+
+    /**
+     * test backup_structure_step class
+     */
+    function test_backup_structure_step() {
+        global $CFG;
+
+        $file = $CFG->dataroot . '/temp/test/test_backup_structure_step.txt';
+        // Remove the test dir and any content
+        @remove_dir(dirname($file));
+        // Recreate test dir
+        if (!check_dir_exists(dirname($file), true, true)) {
+            throw moodle_exception('error_creating_temp_dir', 'error', dirname($file));
+        }
+
+        // We need one (non interactive) controller for instatiating plan
+        $bc = new backup_controller(backup::TYPE_1ACTIVITY, $this->moduleid, backup::FORMAT_MOODLE,
+                                    backup::INTERACTIVE_NO, backup::MODE_GENERAL, $this->userid);
+        // We need one plan
+        $bp = new backup_plan($bc);
+        // We need one task with mocked basepath
+        $bt = new mock_backup_task_basepath('taskname');
+        $bp->add_task($bt);
+        // Instantiate backup_structure_step (and add it to task)
+        $bs = new mock_backup_structure_step('steptest', basename($file), $bt);
+        // Execute backup_structure_step
+        $bs->execute();
+
+        // Test file has been created
+        $this->assertTrue(file_exists($file));
+
+        // Some simple tests with contents
+        $contents = file_get_contents($file);
+        $this->assertTrue(strpos($contents, '<?xml version="1.0"') !== false);
+        $this->assertTrue(strpos($contents, '<test id="1">') !== false);
+        $this->assertTrue(strpos($contents, '<field1>value1</field1>') !== false);
+        $this->assertTrue(strpos($contents, '<field2>value2</field2>') !== false);
+        $this->assertTrue(strpos($contents, '</test>') !== false);
+
+        unlink($file); // delete file
+
+        // Remove the test dir and any content
+        @remove_dir(dirname($file));
+    }
+
+    /**
+     * wrong base_step class tests
+     */
+    function test_base_step_wrong() {
+
+        // Try to pass one wrong task
+        try {
+            $bt = new mock_base_step('teststep', new stdclass());
+            $this->assertTrue(false, 'base_step_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof base_step_exception);
+            $this->assertEqual($e->errorcode, 'wrong_base_task_specified');
+        }
+    }
+
+    /**
+     * wrong backup_step class tests
+     */
+    function test_backup_test_wrong() {
+
+        // Try to pass one wrong task
+        try {
+            $bt = new mock_backup_step('teststep', new stdclass());
+            $this->assertTrue(false, 'backup_step_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof backup_step_exception);
+            $this->assertEqual($e->errorcode, 'wrong_backup_task_specified');
+        }
+    }
+}
+
+/**
+ * Instantiable class extending base_step in order to be able to perform tests
+ */
+class mock_base_step extends base_step {
+    public function execute() {
+    }
+}
+
+/**
+ * Instantiable class extending backup_step in order to be able to perform tests
+ */
+class mock_backup_step extends backup_step {
+    public function execute() {
+    }
+}
+
+/**
+ * Instantiable class extending backup_task in order to mockup get_taskbasepath()
+ */
+class mock_backup_task_basepath extends backup_task {
+
+    public function build() {
+        // Nothing to do
+    }
+
+    public function define_settings() {
+        // Nothing to do
+    }
+
+    public function get_taskbasepath() {
+        global $CFG;
+        return $CFG->dataroot . '/temp/test';
+    }
+}
+
+/**
+ * Instantiable class extending backup_structure_step in order to be able to perform tests
+ */
+class mock_backup_structure_step extends backup_structure_step {
+
+    protected function define_structure() {
+
+        // Create really simple structure (1 nested with 1 attr and 2 fields)
+        $test = new backup_nested_element('test',
+                                          array('id'),
+                                          array('field1', 'field2')
+                                         );
+        $test->set_source_array(array(array('id' => 1, 'field1' => 'value1', 'field2' => 'value2')));
+
+        return $test;
+    }
+}
+
+/**
+ * Instantiable class extending activity_backup_setting to be added to task and perform tests
+ */
+class mock_fullpath_activity_setting extends activity_backup_setting {
+    public function process_change($setting, $ctype, $oldv) {
+        // Nothing to do
+    }
+}
+
+/**
+ * Instantiable class extending activity_backup_setting to be added to task and perform tests
+ */
+class mock_backupid_activity_setting extends activity_backup_setting {
+    public function process_change($setting, $ctype, $oldv) {
+        // Nothing to do
+    }
+}
diff --git a/backup/util/plan/simpletest/testtask.php b/backup/util/plan/simpletest/testtask.php
new file mode 100644 (file)
index 0000000..4580a70
--- /dev/null
@@ -0,0 +1,236 @@
+<?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/>.
+
+/**
+ * @package moodlecore
+ * @subpackage backup-tests
+ * @copyright 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+// Prevent direct access to this file
+if (!defined('MOODLE_INTERNAL')) {
+    die('Direct access to this script is forbidden.');
+}
+
+// Include all the needed stuff
+require_once($CFG->dirroot . '/backup/util/interfaces/checksumable.class.php');
+require_once($CFG->dirroot . '/backup/util/interfaces/executable.class.php');
+require_once($CFG->dirroot . '/backup/backup.class.php');
+require_once($CFG->dirroot . '/backup/util/factories/backup_factory.class.php');
+require_once($CFG->dirroot . '/backup/util/dbops/backup_dbops.class.php');
+require_once($CFG->dirroot . '/backup/util/dbops/backup_controller_dbops.class.php');
+require_once($CFG->dirroot . '/backup/util/helper/backup_helper.class.php');
+require_once($CFG->dirroot . '/backup/util/helper/backup_general_helper.class.php');
+require_once($CFG->dirroot . '/backup/util/checks/backup_check.class.php');
+require_once($CFG->dirroot . '/backup/util/loggers/base_logger.class.php');
+require_once($CFG->dirroot . '/backup/util/loggers/error_log_logger.class.php');
+require_once($CFG->dirroot . '/backup/util/loggers/file_logger.class.php');
+require_once($CFG->dirroot . '/backup/util/loggers/database_logger.class.php');
+require_once($CFG->dirroot . '/backup/util/loggers/output_indented_logger.class.php');
+require_once($CFG->dirroot . '/backup/controller/backup_controller.class.php');
+require_once($CFG->dirroot . '/backup/util/plan/base_plan.class.php');
+require_once($CFG->dirroot . '/backup/util/plan/backup_plan.class.php');
+require_once($CFG->dirroot . '/backup/util/plan/base_task.class.php');
+require_once($CFG->dirroot . '/backup/util/plan/backup_task.class.php');
+
+/*
+ * task tests (all)
+ */
+class backup_task_test extends UnitTestCase {
+
+    public static $includecoverage = array('backup/util/plan');
+    public static $excludecoverage = array('backup/util/plan/simpletest');
+
+    protected $moduleid;  // course_modules id used for testing
+    protected $sectionid; // course_sections id used for testing
+    protected $courseid;  // course id used for testing
+    protected $user;      // user record used for testing
+
+    function __construct() {
+        global $DB, $USER, $CFG;
+
+        $this->moduleid  = 0;
+        $this->sectionid = 0;
+        $this->courseid  = 0;
+        $this->userid = $USER->id;
+        $this->todelete = array();
+
+        // Check we have (at least) one course_module
+        if ($coursemodule = $DB->get_record('course_modules', array(), '*', IGNORE_MULTIPLE)) {
+            $this->moduleid  = $coursemodule->id;
+            $this->sectionid = $coursemodule->section;
+            $this->courseid  = $coursemodule->course;
+        }
+
+        // Avoid any logger to be created, we'll restore original settings on tearDown()
+        $this->errorlogloggerlevel = isset($CFG->backup_error_log_logger_level) ? $CFG->backup_error_log_logger_level : null;
+        $this->fileloggerlevel = isset($CFG->backup_file_logger_level) ? $CFG->backup_file_logger_level : null;
+        $this->databaseloggerlevel = isset($CFG->backup_database_logger_level) ? $CFG->backup_database_logger_level : null;
+        $this->fileloggerlevelextra = isset($CFG->backup_file_logger_level_extra) ? $CFG->backup_file_logger_level_extra : null;
+
+        parent::__construct();
+    }
+
+    function skip() {
+        $this->skipIf(empty($this->moduleid), 'backup_task_test require at least one course module to exist');
+        $this->skipIf(empty($this->sectionid),'backup_task_test require at least one course section to exist');
+        $this->skipIf(empty($this->courseid), 'backup_task_test require at least one course to exist');
+        $this->skipIf(empty($this->userid),'backup_task_test require one valid user to exist');
+    }
+
+    function setUp() {
+        global $CFG;
+
+        // Disable all loggers
+        $CFG->backup_error_log_logger_level = backup::LOG_NONE;
+        $CFG->backup_file_logger_level = backup::LOG_NONE;
+        $CFG->backup_database_logger_level = backup::LOG_NONE;
+        $CFG->backup_file_logger_level_extra = backup::LOG_NONE;
+    }
+
+    function tearDown() {
+        global $DB, $CFG;
+        // Delete all the records marked to
+        foreach ($this->todelete as $todelete) {
+            $DB->delete_records($todelete[0], array('id' => $todelete[1]));
+        }
+        // Restore original file_logger levels
+        if ($this->errorlogloggerlevel !== null) {
+            $CFG->backup_error_log_logger_level = $this->errorlogloggerlevel;
+        } else {
+            unset($CFG->backup_error_log_logger_level);
+        }
+        if ($this->fileloggerlevel !== null) {
+            $CFG->backup_file_logger_level = $this->fileloggerlevel;
+        } else {
+            unset($CFG->backup_file_logger_level);
+        }
+        if ($this->databaseloggerlevel !== null) {
+            $CFG->backup_database_logger_level = $this->databaseloggerlevel;
+        } else {
+            unset($CFG->backup_database_logger_level);
+        }
+        if ($this->fileloggerlevelextra !== null) {
+            $CFG->backup_file_logger_level_extra = $this->fileloggerlevelextra;
+        } else {
+            unset($CFG->backup_file_logger_level_extra);
+        }
+    }
+
+    /**
+     * test base_task class
+     */
+    function test_base_task() {
+
+        $bp = new mock_base_plan('planname'); // We need one plan
+        // Instantiate
+        $bt = new mock_base_task('taskname', $bp);
+        $this->assertTrue($bt instanceof base_task);
+        $this->assertEqual($bt->get_name(), 'taskname');
+        $this->assertTrue(is_array($bt->get_settings()));
+        $this->assertEqual(count($bt->get_settings()), 0);
+        $this->assertTrue(is_array($bt->get_steps()));
+        $this->assertEqual(count($bt->get_steps()), 0);
+    }
+
+    /*
+     * test backup_task class
+     */
+    function test_backup_task() {
+
+        // We need one (non interactive) controller for instatiating plan
+        $bc = new backup_controller(backup::TYPE_1ACTIVITY, $this->moduleid, backup::FORMAT_MOODLE,
+                                    backup::INTERACTIVE_NO, backup::MODE_GENERAL, $this->userid);
+        // We need one plan
+        $bp = new backup_plan($bc);
+        // Instantiate task
+        $bt = new mock_backup_task('taskname', $bp);
+        $this->assertTrue($bt instanceof backup_task);
+        $this->assertEqual($bt->get_name(), 'taskname');
+
+        // Calculate checksum and check it
+        $checksum = $bt->calculate_checksum();
+        $this->assertTrue($bt->is_checksum_correct($checksum));
+
+    }
+
+    /**
+     * wrong base_task class tests
+     */
+    function test_base_task_wrong() {
+
+        // Try to pass one wrong plan
+        try {
+            $bt = new mock_base_task('tasktest', new stdclass());
+            $this->assertTrue(false, 'base_task_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof base_task_exception);
+            $this->assertEqual($e->errorcode, 'wrong_base_plan_specified');
+        }
+
+        // Add wrong step to task
+        $bp = new mock_base_plan('planname'); // We need one plan
+        // Instantiate
+        $bt = new mock_base_task('taskname', $bp);
+        try {
+            $bt->add_step(new stdclass());
+            $this->assertTrue(false, 'base_task_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof base_task_exception);
+            $this->assertEqual($e->errorcode, 'wrong_base_step_specified');
+        }
+
+    }
+
+    /**
+     * wrong backup_task class tests
+     */
+    function test_backup_task_wrong() {
+
+        // Try to pass one wrong plan
+        try {
+            $bt = new mock_backup_task('tasktest', new stdclass());
+            $this->assertTrue(false, 'backup_task_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof backup_task_exception);
+            $this->assertEqual($e->errorcode, 'wrong_backup_plan_specified');
+        }
+    }
+}
+
+/**
+ * Instantiable class extending base_task in order to be able to perform tests
+ */
+class mock_base_task extends base_task {
+    public function build() {
+    }
+
+    public function define_settings() {
+    }
+}
+
+/**
+ * Instantiable class extending backup_task in order to be able to perform tests
+ */
+class mock_backup_task extends backup_task {
+    public function build() {
+    }
+
+    public function define_settings() {
+    }
+}
diff --git a/backup/util/settings/activity/activity_backup_setting.class.php b/backup/util/settings/activity/activity_backup_setting.class.php
new file mode 100644 (file)
index 0000000..2e76058
--- /dev/null
@@ -0,0 +1,36 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-settings
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Abstract class containing all the common stuff for activity backup settings
+ *
+ * TODO: Finish phpdocs
+ */
+abstract class activity_backup_setting extends backup_setting {
+
+    public function __construct($name, $vtype, $value = null, $visibility = self::VISIBLE, $status = self::NOT_LOCKED) {
+        $this->level = self::ACTIVITY_LEVEL;
+        parent::__construct($name, $vtype, $value, $visibility, $status);
+    }
+}
diff --git a/backup/util/settings/backup_setting.class.php b/backup/util/settings/backup_setting.class.php
new file mode 100644 (file)
index 0000000..3eef5d4
--- /dev/null
@@ -0,0 +1,73 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-settings
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * This abstract class defines one backup_setting
+ *
+ * TODO: Finish phpdocs
+ */
+abstract class backup_setting extends base_setting implements checksumable {
+
+    // Some constants defining levels of setting
+    const ROOT_LEVEL     = 1;
+    const COURSE_LEVEL   = 5;
+    const SECTION_LEVEL  = 9;
+    const ACTIVITY_LEVEL = 13;
+
+    protected $level;  // level of the setting
+
+    public function get_level() {
+        return $this->level;
+    }
+
+    public function add_dependency($obj) {
+        if (! $obj instanceof backup_setting) {
+            throw new backup_setting_exception('dependency_is_not_backkup_setting');
+        }
+        // Check the dependency level is >= current level
+        if ($obj->get_level() < $this->level) {
+            throw new backup_setting_exception('cannot_add_upper_level_dependency');
+        }
+        parent::add_dependency($obj);
+    }
+
+// checksumable interface methods
+
+    public function calculate_checksum() {
+        // Checksum is a simple md5 hash of name, value, level
+        // Not following dependencies at all. Each setting will
+        // calculate its own checksum
+        return md5($this->name . '-' . $this->value . '-' . $this->level);
+    }
+
+    public function is_checksum_correct($checksum) {
+        return $this->calculate_checksum() === $checksum;
+    }
+}
+
+/*
+ * Exception class used by all the @backup_setting stuff
+ */
+class backup_setting_exception extends base_setting_exception {
+}
diff --git a/backup/util/settings/base_setting.class.php b/backup/util/settings/base_setting.class.php
new file mode 100644 (file)
index 0000000..ae06436
--- /dev/null
@@ -0,0 +1,298 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-settings
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * This abstract class defines one basic setting
+ *
+ * Each setting will be able to control its name, value (from a list), ui
+ * representation (check box, drop down, text field...), visibility, status
+ * (editable/locked...) and its hierarchy with other settings (using one
+ * like-observer pattern.
+ *
+ * TODO: Finish phpdocs
+ */
+abstract class base_setting {
+
+    // Some constants defining different ui representations for the setting
+    const UI_NONE             = 0;
+    const UI_HTML_CHECKBOX    = 10;
+    const UI_HTML_RADIOBUTTON = 20;
+    const UI_HTML_DROPDOWN    = 30;
+    const UI_HTML_TEXTFIELD   = 40;
+
+    // Type of validation to perform against the value (relaying in PARAM_XXX validations)
+    const IS_BOOLEAN = 'bool';
+    const IS_INTEGER = 'int';
+    const IS_FILENAME= 'file';
+    const IS_PATH    = 'path';
+
+    // Visible/hidden
+    const VISIBLE = 1;
+    const HIDDEN  = 0;
+
+    // Editable/locked (by different causes)
+    const NOT_LOCKED           = 5;
+    const LOCKED_BY_PERMISSION = 6;
+    const LOCKED_BY_HIERARCHY  = 7;
+
+    // Type of change to inform dependencies
+    const CHANGED_VALUE      = 1;
+    const CHANGED_VISIBILITY = 2;
+    const CHANGED_STATUS     = 3;
+
+    protected $name;  // name of the setting
+    protected $value; // value of the setting
+    protected $vtype; // type of value (setting_base::IS_BOOLEAN/setting_base::IS_INTEGER...)
+
+    protected $visibility; // visibility of the setting (setting_base::VISIBLE/setting_base::HIDDEN)
+    protected $status; // setting_base::NOT_LOCKED/setting_base::LOCKED_BY_PERMISSION...
+
+    protected $dependencies; // array of dependent (observer) objects (usually setting_base ones)
+
+    // Note: all the UI stuff could go to independent classes in the future...
+    protected $ui_type;   // setting_base::UI_HTML_CHECKBOX/setting_base::UI_HTML_RADIOBUTTON...
+    protected $ui_label;  // UI label of the setting
+    protected $ui_values; // array of value => ui value of the setting
+    protected $ui_options;// array of custom ui options
+
+    public function __construct($name, $vtype, $value = null, $visibility = self::VISIBLE, $status = self::NOT_LOCKED) {
+        // Check vtype
+        if ($vtype !== self::IS_BOOLEAN && $vtype !== self::IS_INTEGER &&
+            $vtype !== self::IS_FILENAME && $vtype !== self::IS_PATH) {
+            throw new base_setting_exception('setting_invalid_type');
+        }
+
+        // Validate value
+        $value = $this->validate_value($vtype, $value);
+
+        // Check visibility
+        $visibility = $this->validate_visibility($visibility);
+
+        // Check status
+        $status = $this->validate_status($status);
+
+        $this->name        = $name;
+        $this->vtype       = $vtype;
+        $this->value       = $value;
+        $this->visibility  = $visibility;
+        $this->status      = $status;
+        $this->dependencies= array();
+
+        // Apply these defaults
+        $this->ui_type    = self::UI_HTML_DROPDOWN;
+        $this->ui_label   = $name;
+        $this->ui_values  = array();
+        $this->ui_options = array();
+    }
+
+    public function get_name() {
+        return $this->name;
+    }
+
+    public function get_value() {
+        return $this->value;
+    }
+
+    public function get_visibility() {
+        return $this->visibility;
+    }
+
+    public function get_status() {
+        return $this->status;
+    }
+
+    public function set_value($value) {
+        // Validate value
+        $value = $this->validate_value($this->vtype, $value);
+        // Only can change value if setting is not locked
+        if ($this->status != self::NOT_LOCKED) {
+            switch ($this->status) {
+                case self::LOCKED_BY_PERMISSION:
+                    throw new base_setting_exception('setting_locked_by_permission');
+                case self::LOCKED_BY_HIERARCHY:
+                    throw new base_setting_exception('setting_locked_by_hierarchy');
+            }
+        }
+        $oldvalue = $this->value;
+        $this->value = $value;
+        if ($value !== $oldvalue) { // Value has changed, let's inform dependencies
+            $this->inform_dependencies(self::CHANGED_VALUE, $oldvalue);
+        }
+    }
+
+    public function set_visibility($visibility) {
+        $visibility = $this->validate_visibility($visibility);
+        $oldvisibility = $this->visibility;
+        $this->visibility = $visibility;
+        if ($visibility !== $oldvisibility) { // Visibility has changed, let's inform dependencies
+            $this->inform_dependencies(self::CHANGED_VISIBILITY, $oldvisibility);
+        }
+    }
+
+    public function set_status($status) {
+        $status = $this->validate_status($status);
+        $oldstatus = $this->status;
+        $this->status = $status;
+        if ($status !== $oldstatus) { // Status has changed, let's inform dependencies
+            $this->inform_dependencies(self::CHANGED_STATUS, $oldstatus);
+        }
+    }
+
+    public function set_ui($type, $label, $values, $options) {
+        $type = $this->validate_ui_type($type);
+        $label =$this->validate_ui_label($label);
+        $this->ui_type    = $type;
+        $this->ui_label   = $label;
+        $this->set_ui_values($values);
+        $this->set_ui_options($options);
+    }
+
+    public function set_ui_values($values) {
+        $this->ui_values = $values;
+    }
+
+    public function set_ui_options($options) {
+        $this->ui_options = $options;
+    }
+
+    public function add_dependency($obj) {
+        if ($this->is_circular_reference($obj)) {
+            $a = new stdclass();
+            $a->alreadydependent = $this->name;
+            $a->main = $obj->get_name();
+            throw new base_setting_exception('setting_circular_reference', $a);
+        }
+        // Check the settings hasn't been already added
+        if (array_key_exists($obj->get_name(), $this->dependencies)) {
+            throw new base_setting_exception('setting_already_added');
+        }
+        $this->dependencies[$obj->get_name()] = $obj;
+    }
+
+// Protected API starts here
+
+    protected function validate_value($vtype, $value) {
+        if (is_null($value)) { // Nulls aren't validated
+            return null;
+        }
+        $oldvalue = $value;
+        switch ($vtype) {
+            case self::IS_BOOLEAN:
+                $value = clean_param($oldvalue, PARAM_BOOL); // Just clean
+                break;
+            case self::IS_INTEGER:
+                $value = clean_param($oldvalue, PARAM_INT);
+                if ($value != $oldvalue) {
+                    throw new base_setting_exception('setting_invalid_integer', $oldvalue);
+                }
+                break;
+            case self::IS_FILENAME:
+                $value = clean_param($oldvalue, PARAM_FILE);
+                if ($value != $oldvalue) {
+                    throw new base_setting_exception('setting_invalid_filename', $oldvalue);
+                }
+                break;
+            case self::IS_PATH:
+                $value = clean_param($oldvalue, PARAM_PATH);
+                if ($value != $oldvalue) {
+                    throw new base_setting_exception('setting_invalid_path', $oldvalue);
+                }
+                break;
+        }
+        return $value;
+    }
+
+    protected function validate_visibility($visibility) {
+        if (is_null($visibility)) {
+            $visibility = self::VISIBLE;
+        }
+        if ($visibility !== self::VISIBLE && $visibility !== self::HIDDEN) {
+            throw new base_setting_exception('setting_invalid_visibility');
+        }
+        return $visibility;
+    }
+
+    protected function validate_status($status) {
+        if (is_null($status)) {
+            $status = self::NOT_LOCKED;
+        }
+        if ($status !== self::NOT_LOCKED && $status !== self::LOCKED_BY_PERMISSION && $status !== self::LOCKED_BY_HIERARCHY) {
+            throw new base_setting_exception('setting_invalid_status');
+        }
+        return $status;
+    }
+
+    protected function validate_ui_type($type) {
+        if ($type !== self::UI_HTML_CHECKBOX && $type !== self::UI_HTML_RADIOBUTTON &&
+            $type !== self::UI_HTML_DROPDOWN && $type !== self::UI_HTML_TEXTFIELD) {
+            throw new base_setting_exception('setting_invalid_ui_type');
+        }
+        return $type;
+    }
+
+    protected function validate_ui_label($label) {
+        if (empty($label) || $label !== clean_param($label, PARAM_ALPHAEXT)) {
+            throw new base_setting_exception('setting_invalid_ui_label');
+        }
+        return $label;
+    }
+
+    protected function inform_dependencies($ctype, $oldv) {
+        foreach ($this->dependencies as $dependency) {
+            $dependency->process_change($this, $ctype, $oldv);
+        }
+    }
+
+    protected function is_circular_reference($obj) {
+        // Get object dependencies recursively and check (by name) if $this is already there
+        $dependencies = $obj->get_dependencies();
+        if (array_key_exists($this->name, $dependencies) || $obj == $this) {
+            return true;
+        }
+        return false;
+    }
+
+    protected function get_dependencies() {
+        $dependencies = array();
+        foreach ($this->dependencies as $dependency) {
+            $dependencies[$dependency->get_name()] = $dependency->get_name();
+            $dependencies = array_merge($dependencies, $dependency->get_dependencies());
+        }
+        return $dependencies;
+    }
+
+// Implementable API starts here
+
+    abstract public function process_change($setting, $ctype, $oldv);
+}
+
+/*
+ * Exception class used by all the @setting_base stuff
+ */
+class base_setting_exception extends backup_exception {
+
+    public function __construct($errorcode, $a=NULL, $debuginfo=null) {
+        parent::__construct($errorcode, $a, $debuginfo);
+    }
+}
diff --git a/backup/util/settings/course/course_backup_setting.class.php b/backup/util/settings/course/course_backup_setting.class.php
new file mode 100644 (file)
index 0000000..0e46875
--- /dev/null
@@ -0,0 +1,36 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-settings
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Abstract class containing all the common stuff for course backup settings
+ *
+ * TODO: Finish phpdocs
+ */
+abstract class course_backup_setting extends backup_setting {
+
+    public function __construct($name, $vtype, $value = null, $visibility = self::VISIBLE, $status = self::NOT_LOCKED) {
+        $this->level = self::COURSE_LEVEL;
+        parent::__construct($name, $vtype, $value, $visibility, $status);
+    }
+}
diff --git a/backup/util/settings/root/root_backup_setting.class.php b/backup/util/settings/root/root_backup_setting.class.php
new file mode 100644 (file)
index 0000000..62a0f17
--- /dev/null
@@ -0,0 +1,36 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-settings
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Abstract class containing all the common stuff for root backup settings
+ *
+ * TODO: Finish phpdocs
+ */
+abstract class root_backup_setting extends backup_setting {
+
+    public function __construct($name, $vtype, $value = null, $visibility = self::VISIBLE, $status = self::NOT_LOCKED) {
+        $this->level = self::ROOT_LEVEL;
+        parent::__construct($name, $vtype, $value, $visibility, $status);
+    }
+}
diff --git a/backup/util/settings/section/section_backup_setting.class.php b/backup/util/settings/section/section_backup_setting.class.php
new file mode 100644 (file)
index 0000000..c75f202
--- /dev/null
@@ -0,0 +1,36 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-settings
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Abstract class containing all the common stuff for section backup settings
+ *
+ * TODO: Finish phpdocs
+ */
+abstract class section_backup_setting extends backup_setting {
+
+    public function __construct($name, $vtype, $value = null, $visibility = self::VISIBLE, $status = self::NOT_LOCKED) {
+        $this->level = self::SECTION_LEVEL;
+        parent::__construct($name, $vtype, $value, $visibility, $status);
+    }
+}
diff --git a/backup/util/settings/simpletest/testsettings.php b/backup/util/settings/simpletest/testsettings.php
new file mode 100644 (file)
index 0000000..de29021
--- /dev/null
@@ -0,0 +1,427 @@
+<?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/>.
+
+/**
+ * @package moodlecore
+ * @subpackage backup-tests
+ * @copyright 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+// Prevent direct access to this file
+if (!defined('MOODLE_INTERNAL')) {
+    die('Direct access to this script is forbidden.');
+}
+
+// Include all the needed stuff
+require_once($CFG->dirroot . '/backup/util/interfaces/checksumable.class.php');
+require_once($CFG->dirroot . '/backup/backup.class.php');
+require_once($CFG->dirroot . '/backup/util/settings/base_setting.class.php');
+require_once($CFG->dirroot . '/backup/util/settings/backup_setting.class.php');
+require_once($CFG->dirroot . '/backup/util/settings/root/root_backup_setting.class.php');
+require_once($CFG->dirroot . '/backup/util/settings/activity/activity_backup_setting.class.php');
+require_once($CFG->dirroot . '/backup/util/settings/section/section_backup_setting.class.php');
+require_once($CFG->dirroot . '/backup/util/settings/course/course_backup_setting.class.php');
+
+/*
+ * setting tests (all)
+ */
+class setting_test extends UnitTestCase {
+
+    public static $includecoverage = array('backup/util/settings');
+    public static $excludecoverage = array('backup/util/settings/simpletest');
+
+    /*
+     * test base_setting class
+     */
+    function test_base_setting() {
+        // Instantiate base_setting and check everything
+        $bs = new mock_base_setting('test', base_setting::IS_BOOLEAN);
+        $this->assertTrue($bs instanceof base_setting);
+        $this->assertEqual($bs->get_name(), 'test');
+        $this->assertEqual($bs->get_vtype(), base_setting::IS_BOOLEAN);
+        $this->assertTrue(is_null($bs->get_value()));
+        $this->assertEqual($bs->get_visibility(), base_setting::VISIBLE);
+        $this->assertEqual($bs->get_status(), base_setting::NOT_LOCKED);
+
+        // Instantiate base_setting with explicit nulls
+        $bs = new mock_base_setting('test', base_setting::IS_FILENAME, 'filename.txt', null, null);
+        $this->assertEqual($bs->get_value() , 'filename.txt');
+        $this->assertEqual($bs->get_visibility(), base_setting::VISIBLE);
+        $this->assertEqual($bs->get_status(), base_setting::NOT_LOCKED);
+
+        // Instantiate base_setting and set value, visibility and status
+        $bs = new mock_base_setting('test', base_setting::IS_BOOLEAN);
+        $bs->set_value(true);
+        $this->assertTrue($bs->get_value());
+        $bs->set_visibility(base_setting::HIDDEN);
+        $this->assertEqual($bs->get_visibility(), base_setting::HIDDEN);
+        $bs->set_status(base_setting::LOCKED_BY_HIERARCHY);
+        $this->assertEqual($bs->get_status(), base_setting::LOCKED_BY_HIERARCHY);
+
+        // Instantiate with wrong vtype
+        try {
+            $bs = new mock_base_setting('test', 'one_wrong_type');
+            $this->assertTrue(false, 'base_setting_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof base_setting_exception);
+            $this->assertEqual($e->errorcode, 'setting_invalid_type');
+        }
+
+        // Instantiate with wrong integer value
+        try {
+            $bs = new mock_base_setting('test', base_setting::IS_INTEGER, 99.99);
+            $this->assertTrue(false, 'base_setting_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof base_setting_exception);
+            $this->assertEqual($e->errorcode, 'setting_invalid_integer');
+        }
+
+        // Instantiate with wrong filename value
+        try {
+            $bs = new mock_base_setting('test', base_setting::IS_FILENAME, '../../filename.txt');
+            $this->assertTrue(false, 'base_setting_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof base_setting_exception);
+            $this->assertEqual($e->errorcode, 'setting_invalid_filename');
+        }
+
+        // Instantiate with wrong visibility
+        try {
+            $bs = new mock_base_setting('test', base_setting::IS_BOOLEAN, null, 'one_wrong_visibility');
+            $this->assertTrue(false, 'base_setting_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof base_setting_exception);
+            $this->assertEqual($e->errorcode, 'setting_invalid_visibility');
+        }
+
+        // Instantiate with wrong status
+        try {
+            $bs = new mock_base_setting('test', base_setting::IS_BOOLEAN, null, null, 'one_wrong_status');
+            $this->assertTrue(false, 'base_setting_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof base_setting_exception);
+            $this->assertEqual($e->errorcode, 'setting_invalid_status');
+        }
+
+        // Instantiate base_setting and try to set wrong ui_type
+        $bs = new mock_base_setting('test', base_setting::IS_BOOLEAN);
+        try {
+            $bs->set_ui('one_wrong_ui_type', 'label', array(), array());
+            $this->assertTrue(false, 'base_setting_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof base_setting_exception);
+            $this->assertEqual($e->errorcode, 'setting_invalid_ui_type');
+        }
+
+        // Instantiate base_setting and try to set wrong ui_label
+        $bs = new mock_base_setting('test', base_setting::IS_BOOLEAN);
+        try {
+            $bs->set_ui(base_setting::UI_HTML_CHECKBOX, 'one/wrong/label', array(), array());
+            $this->assertTrue(false, 'base_setting_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof base_setting_exception);
+            $this->assertEqual($e->errorcode, 'setting_invalid_ui_label');
+        }
+        // Try to change value of locked setting by permission
+        $bs = new mock_base_setting('test', base_setting::IS_BOOLEAN, null, null, base_setting::LOCKED_BY_PERMISSION);
+        try {
+            $bs->set_value(true);
+            $this->assertTrue(false, 'base_setting_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof base_setting_exception);
+            $this->assertEqual($e->errorcode, 'setting_locked_by_permission');
+        }
+
+        // Try to change value of locked setting by permission
+        $bs = new mock_base_setting('test', base_setting::IS_BOOLEAN, null, null, base_setting::LOCKED_BY_HIERARCHY);
+        try {
+            $bs->set_value(true);
+            $this->assertTrue(false, 'base_setting_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof base_setting_exception);
+            $this->assertEqual($e->errorcode, 'setting_locked_by_hierarchy');
+        }
+
+        // Try to add same setting twice
+        $bs1 = new mock_base_setting('test1', base_setting::IS_INTEGER, null);
+        $bs2 = new mock_base_setting('test2', base_setting::IS_INTEGER, null);
+        $bs1->add_dependency($bs2);
+        try {
+            $bs1->add_dependency($bs2);
+            $this->assertTrue(false, 'base_setting_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof base_setting_exception);
+            $this->assertEqual($e->errorcode, 'setting_already_added');
+        }
+
+        // Try to create one circular reference
+        $bs1 = new mock_base_setting('test1', base_setting::IS_INTEGER, null);
+        try {
+            $bs1->add_dependency($bs1); // self
+            $this->assertTrue(false, 'base_setting_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof base_setting_exception);
+            $this->assertEqual($e->errorcode, 'setting_circular_reference');
+            $this->assertTrue($e->a instanceof stdclass);
+            $this->assertEqual($e->a->main, 'test1');
+            $this->assertEqual($e->a->alreadydependent, 'test1');
+        }
+
+        $bs1 = new mock_base_setting('test1', base_setting::IS_INTEGER, null);
+        $bs2 = new mock_base_setting('test2', base_setting::IS_INTEGER, null);
+        $bs3 = new mock_base_setting('test3', base_setting::IS_INTEGER, null);
+        $bs4 = new mock_base_setting('test4', base_setting::IS_INTEGER, null);
+        $bs1->add_dependency($bs2);
+        $bs2->add_dependency($bs3);
+        $bs3->add_dependency($bs4);
+        try {
+            $bs4->add_dependency($bs1);
+            $this->assertTrue(false, 'base_setting_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof base_setting_exception);
+            $this->assertEqual($e->errorcode, 'setting_circular_reference');
+            $this->assertTrue($e->a instanceof stdclass);
+            $this->assertEqual($e->a->main, 'test1');
+            $this->assertEqual($e->a->alreadydependent, 'test4');
+        }
+
+        // Create 3 settings and observe between them, last one must
+        // automatically inherit all the settings defined in the main one
+        $bs1 = new mock_base_setting('test1', base_setting::IS_INTEGER, null);
+        $bs2 = new mock_base_setting('test2', base_setting::IS_INTEGER, null);
+        $bs3 = new mock_base_setting('test3', base_setting::IS_INTEGER, null);
+        $bs1->add_dependency($bs2);
+        $bs2->add_dependency($bs3);
+        // Check values are spreaded ok
+        $bs1->set_value(123);
+        $this->assertEqual($bs1->get_value(), 123);
+        $this->assertEqual($bs2->get_value(), $bs1->get_value());
+        $this->assertEqual($bs3->get_value(), $bs1->get_value());
+
+        // Add one more setting and set value again
+        $bs4 = new mock_base_setting('test4', base_setting::IS_INTEGER, null);
+        $bs2->add_dependency($bs4);
+        $bs2->set_value(321);
+        $this->assertEqual($bs2->get_value(), 321);
+        $this->assertEqual($bs3->get_value(), $bs2->get_value());
+        $this->assertEqual($bs4->get_value(), $bs3->get_value());
+
+        // Check visibility is spreaded ok
+        $bs1->set_visibility(base_setting::HIDDEN);
+        $this->assertEqual($bs2->get_visibility(), $bs1->get_visibility());
+        $this->assertEqual($bs3->get_visibility(), $bs1->get_visibility());
+        // Check status is spreaded ok
+        $bs1->set_status(base_setting::LOCKED_BY_HIERARCHY);
+        $this->assertEqual($bs2->get_status(), $bs1->get_status());
+        $this->assertEqual($bs3->get_status(), $bs1->get_status());
+
+        // Create 3 settings and observe between them, put them in one array,
+        // force serialize/deserialize to check the observable pattern continues
+        // working after that
+        $bs1 = new mock_base_setting('test1', base_setting::IS_INTEGER, null);
+        $bs2 = new mock_base_setting('test2', base_setting::IS_INTEGER, null);
+        $bs3 = new mock_base_setting('test3', base_setting::IS_INTEGER, null);
+        $bs1->add_dependency($bs2);
+        $bs2->add_dependency($bs3);
+        // Serialize
+        $arr = array($bs1, $bs2, $bs3);
+        $ser = base64_encode(serialize($arr));
+        // Unserialize and copy to new objects
+        $newarr = unserialize(base64_decode($ser));
+        $ubs1 = $newarr[0];
+        $ubs2 = $newarr[1];
+        $ubs3 = $newarr[2];
+        // Must continue being base settings
+        $this->assertTrue($ubs1 instanceof base_setting);
+        $this->assertTrue($ubs2 instanceof base_setting);
+        $this->assertTrue($ubs3 instanceof base_setting);
+        // Set parent setting
+        $ubs1->set_value(1234);
+        $ubs1->set_visibility(base_setting::HIDDEN);
+        $ubs1->set_status(base_setting::LOCKED_BY_HIERARCHY);
+        // Check changes have been spreaded
+        $this->assertEqual($ubs2->get_visibility(), $ubs1->get_visibility());
+        $this->assertEqual($ubs3->get_visibility(), $ubs1->get_visibility());
+        $this->assertEqual($ubs2->get_status(), $ubs1->get_status());
+        $this->assertEqual($ubs3->get_status(), $ubs1->get_status());
+
+        // Check ui_attributes
+        $bs1 = new mock_base_setting('test1', base_setting::IS_INTEGER, null);
+        $bs1->set_ui(base_setting::UI_HTML_DROPDOWN, 'dropdown', array(1 => 'One', 2 => 'Two'), array('opt1' => 1, 'opt2' => 2));
+        list($type, $label, $values, $options) = $bs1->get_ui_info();
+        $this->assertEqual($type, base_setting::UI_HTML_DROPDOWN);
+        $this->assertEqual($label, 'dropdown');
+        $this->assertEqual(count($values), 2);
+        $this->assertEqual($values[1], 'One');
+        $this->assertEqual($values[2], 'Two');
+        $this->assertEqual(count($options), 2);
+        $this->assertEqual($options['opt1'], 1);
+        $this->assertEqual($options['opt2'], 2);
+    }
+
+    /*
+     * test backup_setting class
+     */
+    function test_backup_setting() {
+        // Instantiate backup_setting class and set level
+        $bs = new mock_backup_setting('test', base_setting::IS_INTEGER, null);
+        $bs->set_level(1);
+        $this->assertEqual($bs->get_level(), 1);
+
+        // Instantiate backup setting class and try to add one non backup_setting dependency
+        $bs = new mock_backup_setting('test', base_setting::IS_INTEGER, null);
+        try {
+            $bs->add_dependency(new stdclass());
+            $this->assertTrue(false, 'backup_setting_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof backup_setting_exception);
+            $this->assertEqual($e->errorcode, 'dependency_is_not_backkup_setting');
+        }
+
+        // Try to assing upper level dependency
+        $bs1 = new mock_backup_setting('test1', base_setting::IS_INTEGER, null);
+        $bs1->set_level(1);
+        $bs2 = new mock_backup_setting('test2', base_setting::IS_INTEGER, null);
+        $bs2->set_level(2);
+        try {
+            $bs2->add_dependency($bs1);
+            $this->assertTrue(false, 'backup_setting_exception expected');
+        } catch (exception $e) {
+            $this->assertTrue($e instanceof backup_setting_exception);
+            $this->assertEqual($e->errorcode, 'cannot_add_upper_level_dependency');
+        }
+
+        // Check dependencies are working ok
+        $bs1 = new mock_backup_setting('test1', base_setting::IS_INTEGER, null);
+        $bs1->set_level(1);
+        $bs2 = new mock_backup_setting('test2', base_setting::IS_INTEGER, null);
+        $bs2->set_level(1); // Same level *must* work
+        $bs1->add_dependency($bs2);
+        $bs1->set_value(123456);
+        $this->assertEqual($bs2->get_value(), $bs1->get_value());
+    }
+
+    /*
+     * test activity_backup_setting class
+     */
+    function test_activity_backup_setting() {
+        $bs = new mock_activity_backup_setting('test', base_setting::IS_INTEGER, null);
+        $this->assertEqual($bs->get_level(), backup_setting::ACTIVITY_LEVEL);
+
+        // Check checksum implementation is working
+        $bs1 = new mock_activity_backup_setting('test', base_setting::IS_INTEGER, null);
+        $bs1->set_value(123);
+        $checksum = $bs1->calculate_checksum();
+        $this->assertTrue($checksum);
+        $this->assertTrue($bs1->is_checksum_correct($checksum));
+    }
+
+    /*
+     * test section_backup_setting class
+     */
+    function test_section_backup_setting() {
+        $bs = new mock_section_backup_setting('test', base_setting::IS_INTEGER, null);
+        $this->assertEqual($bs->get_level(), backup_setting::SECTION_LEVEL);
+
+        // Check checksum implementation is working
+        $bs1 = new mock_section_backup_setting('test', base_setting::IS_INTEGER, null);
+        $bs1->set_value(123);
+        $checksum = $bs1->calculate_checksum();
+        $this->assertTrue($checksum);
+        $this->assertTrue($bs1->is_checksum_correct($checksum));
+    }
+
+    /*
+     * test course_backup_setting class
+     */
+    function test_course_backup_setting() {
+        $bs = new mock_course_backup_setting('test', base_setting::IS_INTEGER, null);
+        $this->assertEqual($bs->get_level(), backup_setting::COURSE_LEVEL);
+
+        // Check checksum implementation is working
+        $bs1 = new mock_course_backup_setting('test', base_setting::IS_INTEGER, null);
+        $bs1->set_value(123);
+        $checksum = $bs1->calculate_checksum();
+        $this->assertTrue($checksum);
+        $this->assertTrue($bs1->is_checksum_correct($checksum));
+    }
+}
+
+/*
+ * helper extended base_setting class that makes some methods public for testing
+ */
+class mock_base_setting extends base_setting {
+    public function get_vtype() {
+        return $this->vtype;
+    }
+
+    public function process_change($setting, $ctype, $oldv) {
+        // Simply, inherit from the main object
+        $this->set_value($setting->get_value());
+        $this->set_visibility($setting->get_visibility());
+        $this->set_status($setting->get_status());
+    }
+
+    public function get_ui_info() {
+        // Return an array with all the ui info to be tested
+        return array($this->ui_type, $this->ui_label, $this->ui_values, $this->ui_options);
+    }
+}
+
+/*
+ * helper extended backup_setting class that makes some methods public for testing
+ */
+class mock_backup_setting extends backup_setting {
+    public function set_level($level) {
+        $this->level = $level;
+    }
+
+    public function process_change($setting, $ctype, $oldv) {
+        // Simply, inherit from the main object
+        $this->set_value($setting->get_value());
+        $this->set_visibility($setting->get_visibility());
+        $this->set_status($setting->get_status());
+    }
+}
+
+/*
+ * helper extended activity_backup_setting class that makes some methods public for testing
+ */
+class mock_activity_backup_setting extends activity_backup_setting {
+    public function process_change($setting, $ctype, $oldv) {
+        // Do nothing
+    }
+}
+
+/*
+ * helper extended section_backup_setting class that makes some methods public for testing
+ */
+class mock_section_backup_setting extends section_backup_setting {
+    public function process_change($setting, $ctype, $oldv) {
+        // Do nothing
+    }
+}
+
+/*
+ * helper extended course_backup_setting class that makes some methods public for testing
+ */
+class mock_course_backup_setting extends course_backup_setting {
+    public function process_change($setting, $ctype, $oldv) {
+        // Do nothing
+    }
+}
diff --git a/backup/util/structure/backup_attribute.class.php b/backup/util/structure/backup_attribute.class.php
new file mode 100644 (file)
index 0000000..3a28489
--- /dev/null
@@ -0,0 +1,61 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-structure
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ *
+ * TODO: Finish phpdocs
+ */
+
+/**
+ * Instantiable class representing one attribute atom (name/value) piece of information on backup
+ */
+class backup_attribute extends base_attribute implements processable, annotable {
+
+    protected $annotationitem; // To store the item this element will be responsible to annotate
+
+    public function process($processor) {
+        if (!$processor instanceof base_processor) { // No correct processor, throw exception
+            throw new base_element_struct_exception('incorrect_processor');
+        }
+        $processor->process_attribute($this);
+    }
+
+    public function set_annotation_item($itemname) {
+        if (!empty($this->annotationitem)) {
+            $a = new stdclass();
+            $a->attribute = $this->get_name();
+            $a->annotating= $this->annotationitem;
+            throw new base_element_struct_exception('attribute_already_used_for_annotation', $a);
+        }
+        $this->annotationitem = $itemname;
+    }
+
+    public function annotate($backupid) {
+        if (empty($this->annotationitem)) { // We aren't annotating this item
+            return;
+        }
+        if (!$this->is_set()) {
+            throw new base_element_struct_exception('attribute_has_not_value', $this->get_name());
+        }
+        backup_structure_dbops::insert_backup_ids_record($backupid, $this->annotationitem, $this->get_value());
+    }
+
+}
diff --git a/backup/util/structure/backup_final_element.class.php b/backup/util/structure/backup_final_element.class.php
new file mode 100644 (file)
index 0000000..f62d417
--- /dev/null
@@ -0,0 +1,70 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-structure
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ *
+ * TODO: Finish phpdocs
+ */
+
+/**
+ * Instantiable class representing one final element atom (name/value/parent) piece of information on backup
+ */
+class backup_final_element extends base_final_element implements processable, annotable {
+
+    protected $annotationitem; // To store the item this element will be responsible to annotate
+
+    public function process($processor) {
+        if (!$processor instanceof base_processor) { // No correct processor, throw exception
+            throw new base_element_struct_exception('incorrect_processor');
+        }
+        $processor->process_final_element($this);
+    }
+
+    public function set_annotation_item($itemname) {
+        if (!empty($this->annotationitem)) {
+            $a = new stdclass();
+            $a->attribute = $this->get_name();
+            $a->annotating= $this->annotationitem;
+            throw new base_element_struct_exception('element_already_used_for_annotation', $a);
+        }
+        $this->annotationitem = $itemname;
+    }
+
+    public function annotate($backupid) {
+        if (empty($this->annotationitem)) { // We aren't annotating this item
+            return;
+        }
+        if (!$this->is_set()) {
+            throw new base_element_struct_exception('element_has_not_value', $this->get_name());
+        }
+        backup_structure_dbops::insert_backup_ids_record($backupid, $this->annotationitem, $this->get_value());
+    }
+
+// Protected API starts here
+
+    /**
+     * Returns one instace of the @base_attribute class to work with
+     * when attributes are added simply by name
+     */
+    protected function get_new_attribute($name) {
+        return new backup_attribute($name);
+    }
+}
diff --git a/backup/util/structure/backup_nested_element.class.php b/backup/util/structure/backup_nested_element.class.php
new file mode 100644 (file)
index 0000000..274b6e6
--- /dev/null
@@ -0,0 +1,282 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-structure
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ *
+ * TODO: Finish phpdocs
+ */
+
+/**
+ * Instantiable class representing one nestable element (non final) piece of information on backup
+ */
+class backup_nested_element extends base_nested_element implements processable {
+
+    protected $var_array; // To be used in case we pass one in-memory structure
+    protected $table;     // Table (without prefix) to fetch records from
+    protected $sql;       // Raw SQL to fetch records from
+    protected $params;    // Unprocessed params as specified in the set_source() call
+    protected $procparams;// Processed (path resolved) params array
+    protected $aliases;   // Define DB->final element aliases
+    protected $fileannotelement; // Element to be used as itemid for file annotations
+    protected $fileannotareas;   // array of file areas to be searched by file annotations
+    protected $counter;   // Number of instances of this element that have been processed
+
+    /**
+     * Constructor - instantiates one backup_nested_element, specifying its basic info.
+     *
+     * @param string $name name of the element
+     * @param array  $attributes attributes this element will handle (optional, defaults to null)
+     * @param array  $final_elements this element will handle (optional, defaults to null)
+     */
+    public function __construct($name, $attributes = null, $final_elements = null) {
+        parent::__construct($name, $attributes, $final_elements);
+        $this->var_array = null;
+        $this->table     = null;
+        $this->sql       = null;
+        $this->params    = null;
+        $this->procparams= null;
+        $this->aliases   = array();
+        $this->fileannotelement = null;
+        $this->fileannotareas   = array();
+        $this->counter   = 0;
+    }
+
+    public function process($processor) {
+        if (!$processor instanceof base_processor) { // No correct processor, throw exception
+            throw new base_element_struct_exception('incorrect_processor');
+        }
+
+        $iterator = $this->get_iterator($processor); // Get the iterator over backup-able data
+
+        foreach ($iterator as $key => $values) { // Process each "ocurrrence" of the nested element (recordset or array)
+
+            // Fill the values of the attributes and final elements with the $values from the iterator
+            $this->fill_values($values);
+
+            // Perform pre-process tasks for the nested_element
+            $processor->pre_process_nested_element($this);
+
+            // Delegate the process of each attribute
+            foreach ($this->get_attributes() as $attribute) {
+                $attribute->process($processor);
+            }
+
+            // Main process tasks for the nested element, once its attributes have been processed
+            $processor->process_nested_element($this);
+
+            // Delegate the process of each final_element
+            foreach ($this->get_final_elements() as $final_element) {
+                $final_element->process($processor);
+            }
+
+            // Delegate the process to the optigroup
+            if ($this->get_optigroup()) {
+                $this->get_optigroup()->process($processor);
+            }
+
+            // Delegate the process to each child nested_element
+            foreach ($this->get_children() as $child) {
+                $child->process($processor);
+            }
+
+            // Perform post-process tasks for the nested element
+            $processor->post_process_nested_element($this);
+
+            // Everything processed, clean values before next iteration
+            $this->clean_values();
+
+            // Increment counter for this element
+            $this->counter++;
+
+            // For root element, check we only have 1 element
+            if ($this->get_parent() === null && $this->counter > 1) {
+                throw new base_element_struct_exception('root_only_one_ocurrence', $this->get_name());
+            }
+        }
+        // Close the iterator (DB recordset / array iterator)
+        $iterator->close();
+    }
+
+    public function set_source_array($arr) {
+        // TODO: Only elements having final elements can set source
+        $this->var_array = $arr;
+    }
+
+    public function set_source_table($table, $params) {
+        if (!is_array($params)) { // Check we are passing array
+            throw new base_element_struct_exception('setsourcerequiresarrayofparams');
+        }
+        // TODO: Only elements having final elements can set source
+        $this->table = $table;
+        $this->procparams = $this->convert_table_params($params);
+    }
+
+    public function set_source_sql($sql, $params) {
+        if (!is_array($params)) { // Check we are passing array
+            throw new base_element_struct_exception('setsourcerequiresarrayofparams');
+        }
+        // TODO: Only elements having final elements can set source
+        $this->sql = $sql;
+        $this->procparams = $this->convert_sql_params($params);
+    }
+
+    public function set_source_alias($dbname, $finalelementname) {
+        // Get final element
+        $finalelement = $this->get_final_element($finalelementname);
+        if (!$finalelement) { // Final element incorrect, throw exception
+            throw new base_element_struct_exception('incorrectaliasfinalnamenotfound', $finalelementname);
+        } else {
+            $this->aliases[$dbname] = $finalelement;
+        }
+    }
+
+    public function annotate_files($areas, $elementname) {
+        if (!is_array($areas)) { // Check we are passing array
+            throw new base_element_struct_exception('annotate_files_requires_array_of_areas', $areas);
+        }
+        $annotations = $this->get_file_annotations();
+        if (!empty($annotations[0])) { // Check we haven't defined file annotations already
+            throw new base_element_struct_exception('annotate_files_already_defined', $this->get_name());
+        }
+        if ($elementname !== null) { // Check elementname is valid
+            $element = $this->find_element($elementname);
+            // Annotate the element
+            $this->fileannotelement= $element;
+        }
+        // Annotate the areas
+        $this->fileannotareas  = $areas;
+    }
+
+    public function annotate_ids($itemname, $elementname) {
+        $element = $this->find_element($elementname);
+        $element->set_annotation_item($itemname);
+    }
+
+    /**
+     * Returns one array containing the element in the
+     * @backup_structure and the areas to be searched
+     */
+    public function get_file_annotations() {
+        if (empty($this->fileannotareas)) {
+            return array(null, null);
+        }
+        return array($this->fileannotareas, $this->fileannotelement);
+    }
+
+    public function get_source_array() {
+        return $this->var_array;
+    }
+
+    public function get_source_table() {
+        return $this->table;
+    }
+
+    public function get_source_sql() {
+        return $this->sql;
+    }
+
+    public function get_counter() {
+        return $this->counter;
+    }
+
+    /**
+     * Simple filler that, matching by name, will fill both attributes and final elements
+     * depending of this nested element, debugging info about non-matching elements and/or
+     * elements present in both places. Accept both arrays and objects.
+     */
+    public function fill_values($values) {
+        $values = (array)$values;
+
+        foreach ($values as $key => $value) {
+            $found = 0;
+            if ($attribute = $this->get_attribute($key)) { // Set value for attributes
+                $attribute->set_value($value);
+                $found++;
+            }
+            if ($final = $this->get_final_element($key)) { // Set value for final elements
+                $final->set_value($value);
+                $found++;
+            }
+            if (isset($this->aliases[$key])) { // Last chance, set value by processing final element aliases
+                $this->aliases[$key]->set_value($value);
+                $found++;
+            }
+            // Found more than once, notice
+                // TODO: Route this through backup loggers
+            if ($found > 1) {
+                debugging('Key found more than once ' . $key, DEBUG_DEVELOPER);
+            }
+        }
+
+    }
+
+// Protected API starts here
+
+    protected function convert_table_params($params) {
+        return $this->convert_sql_params($params);
+    }
+
+    protected function convert_sql_params($params) {
+        $procparams = array(); // Reset processed params
+        foreach ($params as $key => $param) {
+            $procparams[$key] = $this->find_element($param);
+        }
+        return $procparams;
+    }
+
+    protected function find_element($param) {
+        if ($param == backup::VAR_PARENTID) { // Look for first parent having id attribute/final_element
+            $param = $this->find_first_parent_by_name('id');
+
+        // If the param is array, with key 'sqlparam', return the value without modifications
+        } else if (is_array($param) && isset($param['sqlparam'])) {
+            return $param['sqlparam'];
+
+        } else if (((int)$param) >= 0) {  // Search by path if param isn't a backup::XXX candidate
+            $param = $this->find_element_by_path($param);
+        }
+        return $param; // Return the param unmodified
+    }
+
+    /**
+     * Returns one instace of the @base_attribute class to work with
+     * when attributes are added simply by name
+     */
+    protected function get_new_attribute($name) {
+        return new backup_attribute($name);
+    }
+
+    /**
+     * Returns one instace of the @final_element class to work with
+     * when final_elements are added simply by name
+     */
+    protected function get_new_final_element($name) {
+        return new backup_final_element($name);
+    }
+
+    /**
+     * Returns one PHP iterator over each "ocurrence" of this nested
+     * element (array or DB recordset). Delegated to backup_structure_dbops class
+     */
+    protected function get_iterator($processor) {
+        return backup_structure_dbops::get_iterator($this, $this->procparams, $processor);
+    }
+}
diff --git a/backup/util/structure/backup_optigroup.class.php b/backup/util/structure/backup_optigroup.class.php
new file mode 100644 (file)
index 0000000..6d7b3ef
--- /dev/null
@@ -0,0 +1,85 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-structure
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ *
+ * TODO: Finish phpdocs
+ */
+
+/**
+ * Instantiable class representing one optigroup element for conditional branching
+ *
+ * Objects of this class are internally nested elements, so they support having both
+ * final elements and children (more nested elements) and are able to have one source
+ * and all the stuff supported by nested elements. Their main differences are:
+ *
+ * - Support for conditional execution, using simple equality checks with outer values.
+ * - Don't have representation in the hierarchy, so:
+ *     - Their level is the level of the parent of their enclosing optigroup.
+ *     - Act as one "path bridge" when looking for parent path values
+ *     - They don't support attributes
+ *
+ * Their main use is to allow conditional branching, basically for optional submodules
+ * like question types, assignment subtypes... where different subtrees of information
+ * must be exported. It's correct to assume that each submodule will define its own
+ * optigroup_element for backup purposes.
+ */
+class backup_optigroup extends base_optigroup implements processable {
+
+    public function add_child($element) {
+        if (!($element instanceof backup_optigroup_element)) { // parameter must be backup_optigroup_element
+            if (!$found = get_class($element)) {
+                $found = 'non object';
+            }
+            throw new base_optigroup_exception('optigroup_element_incorrect', $found);
+        }
+        parent::add_child($element);
+    }
+
+    public function process($processor) {
+        if (!$processor instanceof base_processor) { // No correct processor, throw exception
+            throw new base_element_struct_exception('incorrect_processor');
+        }
+        // Iterate over all the children backup_optigroup_elements, delegating the process
+        // an knowing it only handles final elements, so we'll delegate process of nested
+        // elements below. Tricky but we need to priorize finals BEFORE nested always.
+        foreach ($this->get_children() as $child) {
+            if ($child->condition_matches()) { // Only if the optigroup_element condition matches
+                $child->process($processor);
+                if (!$this->is_multiple()) {
+                    break; // one match found and this optigroup is not multiple => break loop
+                }
+            }
+        }
+        // Now iterate again, but looking for nested elements what will go AFTER all the finals
+        // that have been processed above
+        foreach ($this->get_children() as $child) {
+            if ($child->condition_matches()) { // Only if the optigroup_element condition matches
+                foreach ($child->get_children() as $nested_element) {
+                     $nested_element->process($processor);
+                }
+                if (!$this->is_multiple()) {
+                    break; // one match found and this optigroup is not multiple => break loop
+                }
+            }
+        }
+    }
+}
diff --git a/backup/util/structure/backup_optigroup_element.class.php b/backup/util/structure/backup_optigroup_element.class.php
new file mode 100644 (file)
index 0000000..101c68c
--- /dev/null
@@ -0,0 +1,194 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-structure
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ *
+ * TODO: Finish phpdocs
+ */
+
+/**
+ * Instantiable class representing one optigroup element for conditional branching
+ *
+ * Objects of this class are internally nested elements, so they support having both
+ * final elements and children (more nested elements) and are able to have one source
+ * and all the stuff supported by nested elements. Their main differences are:
+ *
+ * - Support for conditional execution, using simple equality checks with outer values.
+ * - Don't have representation in the hierarchy, so:
+ *     - Their level is the level of the parent of their enclosing optigroup.
+ *     - Act as one "path bridge" when looking for parent path values
+ *     - They don't support attributes
+ *
+ * Their main use is to allow conditional branching, basically for optional submodules
+ * like question types, assignment subtypes... where different subtrees of information
+ * must be exported. It's correct to assume that each submodule will define its own
+ * optigroup_element for backup purposes.
+ */
+class backup_optigroup_element extends backup_nested_element {
+
+    private $conditionparam;     // Unprocessed param representing on path to look for value
+    private $procconditionparam; // Processed base_element param to look for value
+    private $conditionvalue;     // Value to compare the the param value with
+
+    /**
+     * Constructor - instantiates one backup_optigroup_element
+     *
+     * @param string $name of the element
+     * @param array $final_elements this element will handle (optional, defaults to null)
+     * @param string $condition_param param (path) we are using as source for comparing (optional, defaults to null)
+     * @param string $condition_value   value we are comparing to (optional, defaults to null)
+     */
+    public function __construct($name, $final_elements = null, $conditionparam = null, $conditionvalue = null) {
+        parent::__construct($name, null, $final_elements);
+        $this->set_condition($conditionparam, $conditionvalue);
+    }
+
+// Public API starts here
+
+    /**
+     * Sets the condition for this optigroup
+     */
+    public function set_condition($conditionparam, $conditionvalue) {
+        // We only resolve the condition if the parent of the element (optigroup) already has parent
+        // else, we'll resolve it once the optigroup parent is defined
+        if ($this->get_parent() && $this->get_parent()->get_parent() && $conditionparam !== null) {
+            $this->procconditionparam = $this->find_element($conditionparam);
+        }
+        $this->conditionparam = $conditionparam;
+        $this->conditionvalue = $conditionvalue;
+    }
+
+    public function get_condition_param() {
+        return $this->conditionparam;
+    }
+
+    public function get_condition_value() {
+        return $this->conditionvalue;
+    }
+
+    /**
+     * Evaluate the condition, returning if matches (true) or no (false)
+     */
+    public function condition_matches() {
+        $match = false; // By default no match
+        $param = $this->procconditionparam;
+        if ($param instanceof base_atom && $param->is_set()) {
+            $match = ($param->get_value() == $this->conditionvalue); // blame $DB for not having === !
+        } else {
+            $match = ($param == $this->conditionvalue);
+        }
+        return $match;
+    }
+
+    /**
+     * Return the level of this element, that will be, the level of the parent (doesn't consume level)
+     * (note this os only a "cosmetic" effect (to_string) as fact as the real responsible for this
+     * is the corresponding structure_processor for the final output.
+     */
+    public function get_level() {
+        return $this->get_parent() == null ? 1 : $this->get_parent()->get_level();
+    }
+
+    /**
+     * process one optigroup_element
+     *
+     * Note that this ONLY processes the final elements in order to get all them
+     * before processing any nested element. Pending nested elements are processed
+     * by the optigroup caller.
+     */
+    public function process($processor) {
+        if (!$processor instanceof base_processor) { // No correct processor, throw exception
+            throw new base_element_struct_exception('incorrect_processor');
+        }
+
+        $iterator = $this->get_iterator($processor); // Get the iterator over backup-able data
+
+        $itcounter = 0; // To check that the iterator only has 1 ocurrence
+        foreach ($iterator as $key => $values) { // Process each "ocurrrence" of the nested element (recordset or array)
+
+            // Fill the values of the attributes and final elements with the $values from the iterator
+            $this->fill_values($values);
+
+            // Delegate the process of each final_element
+            foreach ($this->get_final_elements() as $final_element) {
+                $final_element->process($processor);
+            }
+
+            // Everything processed, clean values before next iteration
+            $this->clean_values();
+
+            // Increment counters for this element
+            $this->counter++;
+            $itcounter++;
+
+            // optigroup_element, check we only have 1 element always
+            if ($itcounter > 1) {
+                throw new base_element_struct_exception('optigroup_element_only_one_ocurrence', $this->get_name());
+            }
+        }
+        // Close the iterator (DB recordset / array iterator)
+        $iterator->close();
+    }
+
+// Forbidden API starts here
+
+    /**
+     * Adding optigroups is forbidden
+     */
+    public function add_add_optigroup($optigroup) {
+        throw new base_element_struct_exception('optigroup_element_not_optigroup');
+    }
+
+    /**
+     * Adding attributes is forbidden
+     */
+    public function add_attributes($attributes) {
+        throw new base_element_struct_exception('optigroup_element_not_attributes');
+    }
+
+    /**
+     * Instantiating attributes is forbidden
+     */
+    protected function get_new_attribute($name) {
+        throw new base_element_struct_exception('optigroup_element_not_attributes');
+    }
+
+// Protected API starts here
+
+    /**
+     * Returns one instace of the @final_element class to work with
+     * when final_elements are added simply by name
+     */
+    protected function get_new_final_element($name) {
+        return new backup_final_element($name);
+    }
+
+    /**
+     * Set the parent of the optigroup_element and, at the same time,
+     * process the condition param
+     */
+    protected function set_parent($element) {
+        parent::set_parent($element);
+        // Force condition param calculation
+        $this->set_condition($this->conditionparam, $this->conditionvalue);
+    }
+
+}
diff --git a/backup/util/structure/backup_structure_processor.class.php b/backup/util/structure/backup_structure_processor.class.php
new file mode 100644 (file)
index 0000000..3504d91
--- /dev/null
@@ -0,0 +1,123 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-structure
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ *
+ * TODO: Finish phpdocs
+ */
+
+/**
+ * Instantiable class defining the process of backup structures
+ *
+ * This class will process the given backup structure (nested/final/attribute)
+ * based on its definition, triggering as many actions as necessary (pre/post
+ * triggers, ids annotations, deciding based on settings, xml output...). Somehow
+ * one visitor pattern to allow backup structures to work with nice decoupling
+ */
+class backup_structure_processor extends base_processor {
+
+    protected $writer; // xml_writer where the processor is going to output data
+    protected $vars;   // array of backup::VAR_XXX => helper value pairs to be used by source specifications
+
+    public function __construct(xml_writer $writer) {
+        $this->writer = $writer;
+        $this->vars   = array();
+    }
+
+    public function set_var($key, $value) {
+        if (isset($this->vars[$key])) {
+            throw new backup_processor_exception('processorvariablealreadyset', $key);
+        }
+        $this->vars[$key] = $value;
+    }
+
+    public function get_var($key) {
+        if (!isset($this->vars[$key])) {
+            throw new backup_processor_exception('processorvariablenotfound', $key);
+        }
+        return $this->vars[$key];
+    }
+
+    public function pre_process_nested_element(base_nested_element $nested) {
+        // Send open tag to xml_writer
+        $attrarr = array();
+        foreach ($nested->get_attributes() as $attribute) {
+            $attrarr[$attribute->get_name()] = $attribute->get_value();
+        }
+        $this->writer->begin_tag($nested->get_name(), $attrarr);
+    }
+
+    public function process_nested_element(base_nested_element $nested) {
+        // Proceed with all the file annotations for this element
+        list($fileareas, $element) = $nested->get_file_annotations();
+        if ($fileareas) { // If there are areas to search
+            $backupid = $this->get_var(backup::VAR_BACKUPID);
+            $contextid= $this->get_var(backup::VAR_CONTEXTID);
+            $itemid   = !is_null($element) ? $element->get_value() : null;
+            foreach ($fileareas as $filearea) {
+                backup_structure_dbops::annotate_files($backupid, $contextid, $filearea, $itemid);
+            }
+        }
+    }
+
+    public function post_process_nested_element(base_nested_element $nested) {
+        // Send close tag to xml_writer
+        $this->writer->end_tag($nested->get_name());
+    }
+
+    public function process_final_element(base_final_element $final) {
+        // Send full tag to xml_writer and annotations (only if has value)
+        if ($final->is_set()) {
+            $attrarr = array();
+            foreach ($final->get_attributes() as $attribute) {
+                $attrarr[$attribute->get_name()] = $attribute->get_value();
+            }
+            $this->writer->full_tag($final->get_name(), $final->get_value(), $attrarr);
+            // Annotate current value if configured to do so
+            $final->annotate($this->get_var(backup::VAR_BACKUPID));
+        }
+    }
+
+    public function process_attribute(base_attribute $attribute) {
+        // Annotate current value if configured to do so
+        $attribute->annotate($this->get_var(backup::VAR_BACKUPID));
+    }
+}
+
+/**
+ * backup_processor exception to control all the errors while working with backup_processors
+ *
+ * This exception will be thrown each time the backup_processors detects some
+ * inconsistency related with the elements to process or its configuration
+ */
+class backup_processor_exception extends base_processor_exception {
+
+    /**
+     * Constructor - instantiates one backup_processor_exception
+     *
+     * @param string $errorcode key for the corresponding error string
+     * @param object $a extra words and phrases that might be required in the error string
+     * @param string $debuginfo optional debugging information
+     */
+    public function __construct($errorcode, $a = null, $debuginfo = null) {
+        parent::__construct($errorcode, $a, $debuginfo);
+    }
+}
diff --git a/backup/util/structure/base_atom.class.php b/backup/util/structure/base_atom.class.php
new file mode 100644 (file)
index 0000000..0295c11
--- /dev/null
@@ -0,0 +1,166 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-structure
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ *
+ * TODO: Finish phpdocs
+ */
+
+/**
+ * Abstract class representing one atom (name/value) piece of information
+ */
+abstract class base_atom {
+
+    /** @var string name of the element (maps to XML name) */
+    private $name;
+
+    /** @var string value of the element (maps to XML content) */
+    private $value;
+
+    /** @var bool flag to indicate when one value has been set (true) or no (false) */
+    private $is_set;
+
+    /**
+     * Constructor - instantiates one base_atom, specifying its basic info.
+     *
+     * @param string $name name of the element
+     * @param string $value optional value of the element
+     */
+    public function __construct($name) {
+
+        $this->validate_name($name); // Check name
+
+        $this->name  = $name;
+        $this->value = null;
+        $this->is_set= false;
+    }
+
+    protected function validate_name($name) {
+        // Validate various name constraints, throwing exception if needed
+        if (empty($name)) {
+            throw new base_atom_struct_exception('backupatomemptyname', $name);
+        }
+        if (preg_replace('/\s/', '', $name) != $name) {
+            throw new base_atom_struct_exception('backupatomwhitespacename', $name);
+        }
+        if (preg_replace('/[^\x30-\x39\x41-\x5a\x5f\x61-\x7a]/', '', $name) != $name) {
+            throw new base_atom_struct_exception('backupatomnotasciiname', $name);
+        }
+    }
+
+/// Public API starts here
+
+    public function get_name() {
+        return $this->name;
+    }
+
+    public function get_value() {
+        return $this->value;
+    }
+
+    public function set_value($value) {
+        if ($this->is_set) {
+            throw new base_atom_content_exception('backupatomalreadysetvalue', $value);
+        }
+        $this->value = $value;
+        $this->is_set= true;
+    }
+
+    public function clean_value() {
+        $this->value = null;
+        $this->is_set= false;
+    }
+
+    public function is_set() {
+        return $this->is_set;
+    }
+
+    public function to_string($showvalue = false) {
+        $output = $this->name;
+        if ($showvalue) {
+            $value = $this->is_set ? $this->value : 'not set';
+            $output .= ' => ' . $value;
+        }
+        return $output;
+    }
+}
+
+/**
+ * base_atom abstract exception class
+ *
+ * This exceptions will be used by all the base_atom classes
+ * in order to detect any problem or miss-configuration
+ */
+abstract class base_atom_exception extends moodle_exception {
+
+    /**
+     * Constructor - instantiates one base_atom_exception.
+     *
+     * @param string $errorcode key for the corresponding error string
+     * @param object $a extra words and phrases that might be required in the error string
+     * @param string $debuginfo optional debugging information
+     */
+    public function __construct($errorcode, $a = null, $debuginfo = null) {
+        parent::__construct($errorcode, '', '', $a, $debuginfo);
+    }
+}
+
+/**
+ * base_atom exception to control all the errors while creating the objects
+ *
+ * This exception will be thrown each time the base_atom class detects some
+ * inconsistency related with the creation of objects and their attributes
+ * (wrong names)
+ */
+class base_atom_struct_exception extends base_atom_exception {
+
+    /**
+     * Constructor - instantiates one base_atom_struct_exception
+     *
+     * @param string $errorcode key for the corresponding error string
+     * @param object $a extra words and phrases that might be required in the error string
+     * @param string $debuginfo optional debugging information
+     */
+    public function __construct($errorcode, $a = null, $debuginfo = null) {
+        parent::__construct($errorcode, $a, $debuginfo);
+    }
+}
+
+/**
+ * base_atom exception to control all the errors while setting the values
+ *
+ * This exception will be thrown each time the base_atom class detects some
+ * inconsistency related with the creation of contents (values) of the objects
+ * (bad contents, setting without cleaning...)
+ */
+class base_atom_content_exception extends base_atom_exception {
+
+    /**
+     * Constructor - instantiates one base_atom_content_exception
+     *
+     * @param string $errorcode key for the corresponding error string
+     * @param object $a extra words and phrases that might be required in the error string
+     * @param string $debuginfo optional debugging information
+     */
+    public function __construct($errorcode, $a = null, $debuginfo = null) {
+        parent::__construct($errorcode, $a, $debuginfo);
+    }
+}
diff --git a/backup/util/structure/base_attribute.class.php b/backup/util/structure/base_attribute.class.php
new file mode 100644 (file)
index 0000000..568aa82
--- /dev/null
@@ -0,0 +1,35 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-structure
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ *
+ * TODO: Finish phpdocs
+ */
+
+/**
+ * Abstract class representing one attribute atom (name/value) piece of information
+ */
+abstract class base_attribute extends base_atom {
+
+    public function to_string($showvalue = false) {
+        return '@' . parent::to_string($showvalue);
+    }
+}
diff --git a/backup/util/structure/base_final_element.class.php b/backup/util/structure/base_final_element.class.php
new file mode 100644 (file)
index 0000000..35f4fbf
--- /dev/null
@@ -0,0 +1,257 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-structure
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ *
+ * TODO: Finish phpdocs
+ */
+
+/**
+ * Abstract class representing one final element atom (name/value/parent) piece of information
+ */
+abstract class base_final_element extends base_atom {
+
+    /** @var array base_attributes of the element (maps to XML attributes of the tag) */
+        private $attributes;
+
+    /** @var base_nested_element parent of this element (describes structure of the XML file) */
+        private $parent;
+
+    /**
+     * Constructor - instantiates one base_final_element, specifying its basic info.
+     *
+     * @param string $name name of the element
+     * @param array  $attributes attributes this element will handle (optional, defaults to null)
+     */
+    public function __construct($name, $attributes = null) {
+        parent::__construct($name);
+        $this->attributes = array();
+        if (!empty($attributes)) {
+            $this->add_attributes($attributes);
+        }
+        $this->parent = null;
+    }
+
+    protected function set_parent($element) {
+        if ($this->parent) {
+            $info = new stdClass();
+            $info->currparent= $this->parent->get_name();
+            $info->newparent = $element->get_name();
+            $info->element   = $this->get_name();
+            throw new base_element_parent_exception('baseelementhasparent', $info);
+        }
+        $this->parent = $element;
+    }
+
+    protected function get_grandparent() {
+        $parent = $this->parent;
+        if ($parent instanceof base_nested_element) {
+            return $parent->get_grandparent();
+        } else {
+            return $this;
+        }
+    }
+
+    protected function get_grandoptigroupelement_or_grandparent() {
+        $parent = $this->parent;
+        if ($parent instanceof base_optigroup) {
+            return $this; // Have found one parent optigroup, so I (first child of optigroup) am
+        } else if ($parent instanceof base_nested_element) {
+            return $parent->get_grandoptigroupelement_or_grandparent(); // Continue searching
+        } else {
+            return $this;
+        }
+    }
+
+    protected function find_element_by_path($path) {
+        $patharr = explode('/', trim($path, '/')); // Split the path trimming slashes
+        if (substr($path, 0, 1) == '/') { // Absolute path, go to grandparent and process
+            if (!$this->get_grandparent() instanceof base_nested_element) {
+                throw new base_element_struct_exception('baseelementincorrectgrandparent', $patharr[0]);
+            } else if ($this->get_grandparent()->get_name() !== $patharr[0]) {
+                throw new base_element_struct_exception('baseelementincorrectgrandparent', $patharr[0]);
+            } else {
+                $newpath = implode('/', array_slice($patharr, 1)); // Take out 1st element
+                return $this->get_grandparent()->find_element_by_path($newpath); // Process as relative in grandparent
+            }
+        } else {
+            if ($patharr[0] == '..') { // Go to parent
+                if (!$this->get_parent() instanceof base_nested_element) {
+                    throw new base_element_struct_exception('baseelementincorrectparent', $patharr[0]);
+                } else {
+                    $newpath = implode('/', array_slice($patharr, 1)); // Take out 1st element
+                    return $this->get_parent()->find_element_by_path($newpath); // Process as relative in parent
+                }
+            } else if (count($patharr) > 1) { // Go to next child
+                if (!$this->get_child($patharr[0]) instanceof base_nested_element) {
+                    throw new base_element_struct_exception('baseelementincorrectchild', $patharr[0]);
+                } else {
+                    $newpath = implode('/', array_slice($patharr, 1)); // Take out 1st element
+                    return $this->get_child($patharr[0])->find_element_by_path($newpath); // Process as relative in parent
+                }
+            } else { // Return final element or attribute
+                if ($this->get_final_element($patharr[0]) instanceof base_final_element) {
+                    return $this->get_final_element($patharr[0]);
+                } else if ($this->get_attribute($patharr[0]) instanceof base_attribute) {
+                    return $this->get_attribute($patharr[0]);
+                } else {
+                    throw new base_element_struct_exception('baseelementincorrectfinalorattribute', $patharr[0]);
+                }
+            }
+        }
+    }
+
+    protected function find_first_parent_by_name($name) {
+        if ($parent = $this->get_parent()) { // If element has parent
+            $element   = $parent->get_final_element($name); // Look for name into parent finals
+            $attribute = $parent->get_attribute($name);     // Look for name into parent attrs
+            if ($element instanceof base_final_element) {
+                return $element;
+
+            } else if ($attribute instanceof base_attribute) {
+                return $attribute;
+
+            } else { // Not found, go up 1 level and continue searching
+                return $parent->find_first_parent_by_name($name);
+            }
+        } else { // No more parents available, return the original backup::VAR_PARENTID, exception
+            throw new base_element_struct_exception('cannotfindparentidforelement', $name);
+        }
+    }
+
+
+/// Public API starts here
+
+    public function get_attributes() {
+        return $this->attributes;
+    }
+
+    public function get_attribute($name) {
+        if (array_key_exists($name, $this->attributes)) {
+            return $this->attributes[$name];
+        } else {
+            return null;
+        }
+    }
+
+    public function get_parent() {
+        return $this->parent;
+    }
+
+    public function get_level() {
+        return $this->parent == null ? 1 : $this->parent->get_level() + 1;
+    }
+
+    public function add_attributes($attributes) {
+        if ($attributes instanceof base_attribute || is_string($attributes)) { // Accept 1 attribute, object or string
+            $attributes = array($attributes);
+        }
+        if (is_array($attributes)) {
+            foreach ($attributes as $attribute) {
+                if (is_string($attribute)) { // Accept string attributes
+                    $attribute = $this->get_new_attribute($attribute);
+                }
+                if (!($attribute instanceof base_attribute)) {
+                    throw new base_element_attribute_exception('baseelementnoattribute', get_class($attribute));
+                }
+                if (array_key_exists($attribute->get_name(), $this->attributes)) {
+                    throw new base_element_attribute_exception('baseelementattributeexists', $attribute->get_name());
+                }
+                $this->attributes[$attribute->get_name()] = $attribute;
+            }
+        } else {
+            throw new base_element_attribute_exception('baseelementattributeincorrect');
+        }
+    }
+
+    public function clean_values() {
+        parent::clean_value();
+        if (!empty($this->attributes)) {
+            foreach ($this->attributes as $attribute) {
+                $attribute->clean_value();
+            }
+        }
+    }
+
+    public function to_string($showvalue = false) {
+        // Decide the correct prefix
+        $prefix = '#'; // default
+        if ($this->parent instanceof base_optigroup) {
+            $prefix = '?';
+        } else if ($this instanceof base_nested_element) {
+            $prefix = '';
+        }
+        $indent = str_repeat('    ', $this->get_level()); // Indent output based in level (4cc)
+        $output = $indent . $prefix . $this->get_name() . ' (level: ' . $this->get_level() . ')';
+        if ($showvalue) {
+            $value = $this->is_set() ? $this->get_value() : 'not set';
+            $output .= ' => ' . $value;
+        }
+        if (!empty($this->attributes)) {
+            foreach ($this->attributes as $attribute) {
+                $output .= PHP_EOL . $indent . '    ' . $attribute->to_string($showvalue);
+            }
+        }
+        return $output;
+    }
+
+// Implementable API
+
+    /**
+     * Returns one instace of the @base_attribute class to work with
+     * when attributes are added simply by name
+     */
+    abstract protected function get_new_attribute($name);
+}
+
+/**
+ * base_element exception to control all the errors related with parents handling
+ */
+class base_element_parent_exception extends base_atom_exception {
+
+    /**
+     * Constructor - instantiates one base_element_parent_exception
+     *
+     * @param string $errorcode key for the corresponding error string
+     * @param object $a extra words and phrases that might be required in the error string
+     * @param string $debuginfo optional debugging information
+     */
+    public function __construct($errorcode, $a = null, $debuginfo = null) {
+        parent::__construct($errorcode, $a, $debuginfo);
+    }
+}
+
+/**
+ * base_element exception to control all the errors related with attributes handling
+ */
+class base_element_attribute_exception extends base_atom_exception {
+
+    /**
+     * Constructor - instantiates one base_element_attribute_exception
+     *
+     * @param string $errorcode key for the corresponding error string
+     * @param object $a extra words and phrases that might be required in the error string
+     * @param string $debuginfo optional debugging information
+     */
+    public function __construct($errorcode, $a = null, $debuginfo = null) {
+        parent::__construct($errorcode, $a, $debuginfo);
+    }
+}
diff --git a/backup/util/structure/base_nested_element.class.php b/backup/util/structure/base_nested_element.class.php
new file mode 100644 (file)
index 0000000..f2dc77f
--- /dev/null
@@ -0,0 +1,242 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-structure
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ *
+ * TODO: Finish phpdocs
+ */
+
+/**
+ * Abstract class representing one nestable element (non final) piece of information
+ */
+abstract class base_nested_element extends base_final_element {
+
+    /** @var array final elements of the element (maps to XML final elements of the tag) */
+    private $final_elements;
+
+    /** @var array children base_elements of this element (describes structure of the XML file) */
+    private $children;
+
+    /** @var base_optigroup optional group of this element (branches to be processed conditionally) */
+    private $optigroup;
+
+    /** @var array elements already used by the base_element, to avoid circular references */
+    private $used;
+
+    /**
+     * Constructor - instantiates one base_nested_element, specifying its basic info.
+     *
+     * @param string $name name of the element
+     * @param array  $attributes attributes this element will handle (optional, defaults to null)
+     * @param array  $final_elements this element will handle (optional, defaults to null)
+     */
+    public function __construct($name, $attributes = null, $final_elements = null) {
+        parent::__construct($name, $attributes);
+        $this->final_elements = array();
+        if (!empty($final_elements)) {
+            $this->add_final_elements($final_elements);
+        }
+        $this->children = array();
+        $this->optigroup = null;
+        $this->used[] = $name;
+    }
+
+    protected function get_used() {
+        return $this->used;
+    }
+
+    protected function set_used($used) {
+        $this->used = $used;
+    }
+
+    protected function add_used($element) {
+        $this->used = array_merge($this->used, $element->get_used());
+    }
+
+    protected function check_and_set_used($element) {
+        $grandparent = $this->get_grandoptigroupelement_or_grandparent();
+        if ($existing = array_intersect($grandparent->get_used(), $element->get_used())) { // Check the element isn't being used already
+            throw new base_element_struct_exception('baseelementexisting', implode($existing));
+        }
+        $grandparent->add_used($element);
+        // If the parent is one optigroup, add the element useds to it too
+        if ($grandparent->get_parent() instanceof base_optigroup) {
+            $grandparent->get_parent()->add_used($element);
+        }
+
+    }
+
+/// Public API starts here
+
+    public function get_final_elements() {
+        return $this->final_elements;
+    }
+
+    public function get_final_element($name) {
+        if (array_key_exists($name, $this->final_elements)) {
+            return $this->final_elements[$name];
+        } else {
+            return null;
+        }
+    }
+
+    public function get_children() {
+        return $this->children;
+    }
+
+    public function get_child($name) {
+        if (array_key_exists($name, $this->children)) {
+            return $this->children[$name];
+        } else {
+            return null;
+        }
+    }
+
+    public function get_optigroup() {
+        return $this->optigroup;
+    }
+
+    public function add_final_elements($final_elements) {
+        if ($final_elements instanceof base_final_element || is_string($final_elements)) { // Accept 1 final_element, object or string
+            $final_elements = array($final_elements);
+        }
+        if (is_array($final_elements)) {
+            foreach ($final_elements as $final_element) {
+                if (is_string($final_element)) { // Accept string final_elements
+                    $final_element = $this->get_new_final_element($final_element);
+                }
+                if (!($final_element instanceof base_final_element)) {
+                    throw new base_element_struct_exception('baseelementnofinalelement', get_class($final_element));
+                }
+                if (array_key_exists($final_element->get_name(), $this->final_elements)) {
+                    throw new base_element_struct_exception('baseelementexists', $final_element->get_name());
+                }
+                $this->final_elements[$final_element->get_name()] = $final_element;
+                $final_element->set_parent($this);
+            }
+        } else {
+            throw new base_element_struct_exception('baseelementincorrect');
+        }
+    }
+
+    public function add_child($element) {
+        if (!($element instanceof base_nested_element)) { // parameter must be a base_nested_element
+            if (!$found = get_class($element)) {
+                $found = 'non object';
+            }
+            throw new base_element_struct_exception('nestedelementincorrect', $found);
+        }
+        $this->check_and_set_used($element);
+        $this->children[$element->get_name()] = $element;
+        $element->set_parent($this);
+    }
+
+    public function add_optigroup($optigroup) {
+        if (!($optigroup instanceof base_optigroup)) { // parameter must be a base_optigroup
+            if (!$found = get_class($optigroup)) {
+                $found = 'non object';
+            }
+            throw new base_element_struct_exception('optigroupincorrect', $found);
+        }
+        if ($this->optigroup !== null) {
+            throw new base_element_struct_exception('optigroupalreadyset', $found);
+        }
+        $this->check_and_set_used($optigroup);
+        $this->optigroup = $optigroup;
+        $optigroup->set_parent($this);
+    }
+
+    public function get_value() {
+        throw new base_element_struct_exception('nestedelementnotvalue');
+    }
+
+    public function set_value($value) {
+        throw new base_element_struct_exception('nestedelementnotvalue');
+    }
+
+    public function clean_value() {
+        throw new base_element_struct_exception('nestedelementnotvalue');
+    }
+
+    public function clean_values() {
+        parent::clean_values();
+        if (!empty($this->final_elements)) {
+            foreach ($this->final_elements as $final_element) {
+                $final_element->clean_values();
+            }
+        }
+        if (!empty($this->children)) {
+            foreach ($this->children as $child) {
+                $child->clean_values();
+            }
+        }
+        if (!empty($this->optigroup)) {
+            $this->optigroup->clean_values();
+        }
+    }
+
+    public function to_string($showvalue = false) {
+        $output = parent::to_string($showvalue);
+        if (!empty($this->final_elements)) {
+            foreach ($this->final_elements as $final_element) {
+                $output .= PHP_EOL . $final_element->to_string($showvalue);
+            }
+        }
+        if (!empty($this->children)) {
+            foreach ($this->children as $child) {
+                $output .= PHP_EOL . $child->to_string($showvalue);
+            }
+        }
+        if (!empty($this->optigroup)) {
+            $output .= PHP_EOL . $this->optigroup->to_string($showvalue);
+        }
+        return $output;
+    }
+
+// Implementable API
+
+    /**
+     * Returns one instace of the @final_element class to work with
+     * when final_elements are added simply by name
+     */
+    abstract protected function get_new_final_element($name);
+}
+
+/**
+ * base_element exception to control all the errors while building the nested tree
+ *
+ * This exception will be thrown each time the base_element class detects some
+ * inconsistency related with the building of the nested tree representing one base part
+ * (invalid objects, circular references, double parents...)
+ */
+class base_element_struct_exception extends base_atom_exception {
+
+    /**
+     * Constructor - instantiates one base_element_struct_exception
+     *
+     * @param string $errorcode key for the corresponding error string
+     * @param object $a extra words and phrases that might be required in the error string
+     * @param string $debuginfo optional debugging information
+     */
+    public function __construct($errorcode, $a = null, $debuginfo = null) {
+        parent::__construct($errorcode, $a, $debuginfo);
+    }
+}
diff --git a/backup/util/structure/base_optigroup.class.php b/backup/util/structure/base_optigroup.class.php
new file mode 100644 (file)
index 0000000..67a01e3
--- /dev/null
@@ -0,0 +1,179 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-structure
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ *
+ * TODO: Finish phpdocs
+ */
+
+/**
+ * Abstract class representing one optigroup for conditional branching
+ */
+abstract class base_optigroup extends base_nested_element {
+
+    /** @var boolean flag indicating if multiple branches can be processed (true) or no (false) */
+    private $multiple;
+
+    /**
+     * Constructor - instantiates one base_optigroup, specifying its basic info
+     *
+     * @param string $name name of the element
+     * @param array $elements base_optigroup_elements of this group
+     * @param bool $multiple to decide if the group allows multiple branches processing or no
+     */
+    public function __construct($name, $elements = null, $multiple = false) {
+        parent::__construct($name);
+        $this->multiple = $multiple;
+        if (!empty($elements)) {
+            $this->add_children($elements);
+        }
+    }
+
+// Public API starts here
+
+    /**
+     * Return the level of this element, that will be, the level of the parent (doesn't consume level)
+     * (note this os only a "cosmetic" effect (to_string) as fact as the real responsible for this
+     * is the corresponding structure_processor for the final output.
+     */
+    public function get_level() {
+        return $this->get_parent() == null ? 1 : $this->get_parent()->get_level();
+    }
+
+    public function to_string($showvalue = false) {
+        $indent = str_repeat('    ', $this->get_level()); // Indent output based in level (4cc)
+        $output = $indent . '!' . $this->get_name() . ' (level: ' . $this->get_level() . ')';
+        $children = $this->get_children();
+        if (!empty($children)) {
+            foreach ($this->get_children() as $child) {
+                $output .= PHP_EOL . $child->to_string($showvalue);
+            }
+        }
+        return $output;
+    }
+
+// Forbidden API starts here
+
+    /**
+     * Adding attributes is forbidden
+     */
+    public function add_attributes($attributes) {
+        throw new base_element_struct_exception('optigroup_not_attributes');
+    }
+
+    /**
+     * Instantiating attributes is forbidden
+     */
+    protected function get_new_attribute($name) {
+        throw new base_element_struct_exception('optigroup_not_attributes');
+    }
+
+    /**
+     * Adding final elements is forbidden
+     */
+    public function add_final_elements($attributes) {
+        throw new base_element_struct_exception('optigroup_not_final_elements');
+    }
+
+    /**
+     * Instantiating final elements is forbidden
+     */
+    protected function get_new_final_element($name) {
+        throw new base_element_struct_exception('optigroup_not_final_elements');
+    }
+
+// Protected API starts here
+
+    protected function add_children($elements) {
+        if ($elements instanceof base_nested_element) { // Accept 1 element, object
+            $elements = array($elements);
+        }
+        if (is_array($elements)) {
+            foreach ($elements as $element) {
+                $this->add_child($element);
+            }
+        } else {
+            throw new base_optigroup_exception('optigroup_elements_incorrect');
+        }
+    }
+
+    /**
+     * Set the parent of the optigroup and, at the same time, process all the
+     * condition params in all the childs
+     */
+    protected function set_parent($element) {
+        parent::set_parent($element);
+        // Force condition param calculation in all children
+        foreach ($this->get_children() as $child) {
+            $child->set_condition($child->get_condition_param(), $child->get_condition_value());
+        }
+    }
+
+    /**
+     * Recalculate all the used elements in the optigroup, observing
+     * restrictions and passing the new used to outer level
+     */
+    function add_used($element) {
+        $newused = array();
+        // Iterate over all the element useds, filling $newused and
+        // observing the multiple setting
+        foreach ($element->get_used() as $used) {
+            if (!in_array($used, $this->get_used())) { // it's a new one, add to $newused array
+                $newused[] = $used;
+                $this->set_used(array_merge($this->get_used(), array($used))); // add to the optigroup used array
+            } else { // it's an existing one, exception on multiple optigroups
+                if ($this->multiple) {
+                    throw new base_optigroup_exception('multiple_optigroup_duplicate_element', $used);
+                }
+            }
+        }
+        // Finally, inform about newused to the next grand(parent/optigroupelement)
+        if ($newused && $this->get_parent()) {
+            $element->set_used($newused); // Only about the newused
+            $grandparent = $this->get_grandoptigroupelement_or_grandparent();
+            $grandparent->check_and_set_used($element);
+        }
+    }
+
+    protected function is_multiple() {
+        return $this->multiple;
+    }
+}
+
+/**
+ * base_optigroup_exception to control all the errors while building the optigroups
+ *
+ * This exception will be thrown each time the base_optigroup class detects some
+ * inconsistency related with the building of the group
+ */
+class base_optigroup_exception extends base_atom_exception {
+
+    /**
+     * Constructor - instantiates one base_optigroup_exception
+     *
+     * @param string $errorcode key for the corresponding error string
+     * @param object $a extra words and phrases that might be required in the error string
+     * @param string $debuginfo optional debugging information
+     */
+    public function __construct($errorcode, $a = null, $debuginfo = null) {
+        parent::__construct($errorcode, $a, $debuginfo);
+    }
+}
diff --git a/backup/util/structure/base_processor.class.php b/backup/util/structure/base_processor.class.php
new file mode 100644 (file)
index 0000000..ea8e382
--- /dev/null
@@ -0,0 +1,59 @@
+<?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/>.
+
+/**
+ * @package    moodlecore
+ * @subpackage backup-structure
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ *
+ * TODO: Finish phpdocs
+ */
+
+/**
+ * Abstract class representing the required implementation for classes able to process structure classes
+ */
+abstract class base_processor {
+
+    abstract function pre_process_nested_element(base_nested_element $nested);
+    abstract function process_nested_element(base_nested_element $nested);
+    abstract function post_process_nested_element(base_nested_element $nested);
+
+    abstract function process_final_element(base_final_element $final);
+
+    abstract function process_attribute(base_attribute $attribute);
+}
+
+/**
+ * base_processor abstract exception class
+ *
+ * This exceptions will be used by all the processor classes
+ * in order to detect any problem or miss-configuration
+ */
+abstract class base_processor_exception extends moodle_exception {
+
+    /**
+     * Constructor - instantiates one base_processor_exception.
+     *
+     * @param string $errorcode key for the corresponding error string
+     * @param object $a extra words and phrases that might be required in the error string
+     * @param string $debuginfo optional debugging information
+     */
+    public function __construct($errorcode, $a = null, $debuginfo = null) {
+        parent::__construct($errorcode, '', '', $a, $debuginfo);
+    }
+}
diff --git a/backup/util/structure/simpletest/fixtures/structuremocks.php b/backup/util/structure/simpletest/fixtures/structuremocks.php
new file mode 100644 (file)
index 0000000..0701bf5
--- /dev/null
@@ -0,0 +1,123 @@
+<?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/>.
+
+/**
+ * Mockup elements shared by various structure tests
+ *
+ * @package    moodlecore
+ * @subpackage backup-tests
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+/**
+ * helper extended base_attribute class that implements some methods for instantiating and testing
+ */
+class mock_base_attribute extends base_attribute {
+    // Nothing to do. Just allow instances to be created
+}
+
+/**
+ * helper extended final_element class that implements some methods for instantiating and testing
+ */
+class mock_base_final_element extends base_final_element {
+/// Implementable API
+    protected function get_new_attribute($name) {
+        return new mock_base_attribute($name);
+    }
+}
+
+/**
+ * helper extended nested_element class that implements some methods for instantiating and testing
+ */
+class mock_base_nested_element extends base_nested_element {
+/// Implementable API
+    protected function get_new_attribute($name) {
+        return new mock_base_attribute($name);
+    }
+
+    protected function get_new_final_element($name) {
+        return new mock_base_final_element($name);
+    }
+}
+
+/**
+ * helper extended optigroup class that implements some methods for instantiating and testing
+ */
+class mock_base_optigroup extends base_optigroup {
+/// Implementable API
+    protected function get_new_attribute($name) {
+        return new mock_base_attribute($name);
+    }
+
+    protected function get_new_final_element($name) {
+        return new mock_base_final_element($name);
+    }
+
+    public function is_multiple() {
+        return parent::is_multiple();
+    }
+}
+
+/**
+ * helper class that extends backup_final_element in order to skip its value
+ */
+class mock_skip_final_element extends backup_final_element {
+
+    public function set_value($value) {
+        $this->clean_value();
+    }
+}
+
+/**
+ * helper class that extends backup_final_element in order to modify its value
+ */
+class mock_modify_final_element extends backup_final_element {
+    public function set_value($value) {
+        parent::set_value('original was ' . $value . ', now changed');
+    }
+}
+
+/**
+ * helper class that extends backup_final_element to delegate any calculation to another class
+ */
+class mock_final_element_interceptor extends backup_final_element {
+    public function set_value($value) {
+        // Get grandparent name
+        $gpname = $this->get_grandparent()->get_name();
+        // Get parent name
+        $pname = $this->get_parent()->get_name();
+        // Get my name
+        $myname = $this->get_name();
+        // Define class and function name
+        $classname = 'mock_' . $gpname . '_' . $pname . '_interceptor';
+        $methodname= 'intercept_' . $pname . '_' . $myname;
+        // Invoke the interception method
+        $result = call_user_func(array($classname, $methodname), $value);
+        // Finally set it
+        parent::set_value($result);
+    }
+}
+
+/**
+ * test interceptor class (its methods are called from interceptor)
+ */
+abstract class mock_forum_forum_interceptor {
+    static function intercept_forum_completionposts($element) {
+        return 'intercepted!';
+    }
+}
+
diff --git a/backup/util/structure/simpletest/testbackupstructures.php b/backup/util/structure/simpletest/testbackupstructures.php
new file mode 100644 (file)
index 0000000..07901cb
--- /dev/null
@@ -0,0 +1,648 @@
+<?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/>.
+
+/**
+ * Unit tests for base_final_element.class.php
+ *
+ * @package    moodlecore
+ * @subpackage backup-tests
+ * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+// Prevent direct access to this file
+if (!defined('MOODLE_INTERNAL')) {
+    die('Direct access to this script is forbidden.');
+}
+
+// Include all the needed stuff
+require_once($CFG->dirroot . '/backup/util/includes/backup_includes.php');
+require_once($CFG->dirroot . '/backup/util/xml/output/memory_xml_output.class.php');
+
+/**
+ * Unit test case the all the backup structure classes. Note: Uses database
+ */
+class backup_structure_test extends UnitTestCaseUsingDatabase {
+
+    public static $includecoverage = array(
+        'backup/util/structure'
+    );
+    public static $excludecoverage = array(
+        'backup/util/structure/simpletest'
+    );
+
+    protected $testtables = array(
+        'lib'       => array(
+            'files'),
+        'mod/forum' => array(
+            'forum', 'forum_discussions', 'forum_posts',
+            'forum_ratings', 'forum_read'));
+
+    protected $forumid;   // To store the inserted forum->id
+    protected $contextid; // Official contextid for these tests
+
+
+    public function setUp() {
+        parent::setUp();
+
+        $this->switch_to_test_db(); // Switch to test DB for all the execution
+
+        foreach ($this->testtables as $dir => $tables) {
+            $this->create_test_tables($tables, $dir); // Create tables
+        }
+
+        $this->contextid = 666; // Let's assume this is the context for the forum
+        $this->fill_records(); // Add common stuff needed by various test methods
+    }
+
+    public function tearDown() {
+        parent::tearDown(); // In charge of droppng all the test tables
+    }
+
+    private function fill_records() {
+        global $DB;
+
+        // Create one forum
+        $forum_data = (object)array('course' => 1, 'name' => 'Test forum', 'intro' => 'Intro forum');
+        $this->forumid = $DB->insert_record('forum', $forum_data);
+        // With two related file
+        $f1_forum_data = (object)array(
+                                     'contenthash' => 'testf1', 'contextid' => $this->contextid,
+                                     'filearea' => 'forum_intro', 'filename' => 'tf1', 'itemid' => 0,
+                                     'filesize' => 123, 'timecreated' => 0, 'timemodified' => 0,
+                                     'pathnamehash' => 'testf1'
+                                 );
+        $DB->insert_record('files', $f1_forum_data);
+        $f2_forum_data = (object)array(
+                                     'contenthash' => 'tesft2', 'contextid' => $this->contextid,
+                                     'filearea' => 'forum_intro', 'filename' => 'tf2', 'itemid' => 0,
+                                     'filesize' => 123, 'timecreated' => 0, 'timemodified' => 0,
+                                     'pathnamehash' => 'testf2'
+                                 );
+        $DB->insert_record('files', $f2_forum_data);
+
+        // Create two discussions
+        $discussion1 = (object)array('course' => 1, 'forum' => $this->forumid, 'name' => 'd1', 'userid' => 100, 'groupid' => 200);
+        $d1id = $DB->insert_record('forum_discussions', $discussion1);
+        $discussion2 = (object)array('course' => 1, 'forum' => $this->forumid, 'name' => 'd2', 'userid' => 101, 'groupid' => 201);
+        $d2id = $DB->insert_record('forum_discussions', $discussion2);
+
+        // Create four posts
+        $post1 = (object)array('discussion' => $d1id, 'userid' => 100, 'subject' => 'p1', 'message' => 'm1');
+        $p1id = $DB->insert_record('forum_posts', $post1);
+        $post2 = (object)array('discussion' => $d1id, 'parent' => $p1id, 'userid' => 102, 'subject' => 'p2', 'message' => 'm2');
+        $p2id = $DB->insert_record('forum_posts', $post2);
+        $post3 = (object)array('discussion' => $d1id, 'parent' => $p2id, 'userid' => 103, 'subject' => 'p3', 'message' => 'm3');
+        $p3id = $DB->insert_record('forum_posts', $post3);
+        $post4 = (object)array('discussion' => $d2id, 'userid' => 101, 'subject' => 'p4', 'message' => 'm4');
+        $p4id = $DB->insert_record('forum_posts', $post4);
+        // With two related file
+        $f1_post1 = (object)array(
+                                'contenthash' => 'testp1', 'contextid' => $this->contextid,
+                                'filearea' => 'forum_post', 'filename' => 'tp1', 'itemid' => $p1id,
+                                'filesize' => 123, 'timecreated' => 0, 'timemodified' => 0,
+                                'pathnamehash' => 'testp1'
+                            );
+        $DB->insert_record('files', $f1_post1);
+        $f1_post2 = (object)array(
+                                'contenthash' => 'testp2', 'contextid' => $this->contextid,
+                                'filearea' => 'forum_attachment', 'filename' => 'tp2', 'itemid' => $p2id,
+                                'filesize' => 123, 'timecreated' => 0, 'timemodified' => 0,
+                                'pathnamehash' => 'testp2'
+                            );
+        $DB->insert_record('files', $f1_post2);
+
+        // Create two ratings
+        $rating1 = (object)array('userid' => 104, 'post' => $p1id, 'rating' => 2);
+        $r1id = $DB->insert_record('forum_ratings', $rating1);
+        $rating2 = (object)array('userid' => 105, 'post' => $p1id, 'rating' => 3);
+        $r2id = $DB->insert_record('forum_ratings', $rating2);
+
+        // Create 1 reads
+        $read1 = (object)array('userid' => 102, 'forumid' => $this->forumid, 'discussionid' => $d2id, 'postid' => $p4id);
+        $DB->insert_record('forum_read', $read1);
+    }
+
+    /**
+     * Backup structures tests (construction, definition and execution)
+     */
+    function test_backup_structure_construct() {
+        global $DB;
+
+        $backupid = 'Testing Backup ID'; // Official backupid for these tests
+
+        // Create all the elements that will conform the tree
+        $forum = new backup_nested_element('forum',
+                                           array('id'),
+                                           array(
+                                               'type', 'name', 'intro', 'introformat',
+                                               'assessed', 'assesstimestart', 'assesstimefinish', 'scale',
+                                               'maxbytes', 'maxattachments', 'forcesubscribe', 'trackingtype',
+                                               'rsstype', 'rssarticles', 'timemodified', 'warnafter',
+                                               'blockafter',
+                                               new backup_final_element('blockperiod'),
+                                               new mock_skip_final_element('completiondiscussions'),
+                                               new mock_modify_final_element('completionreplies'),
+                                               new mock_final_element_interceptor('completionposts'))
+                                          );
+        $discussions = new backup_nested_element('discussions');
+        $discussion = new backup_nested_element('discussion',
+                                                array('id'),
+                                                array(
+                                                    'forum', 'name', 'firstpost', 'userid',
+                                                    'groupid', 'assessed', 'timemodified', 'usermodified',
+                                                    'timestart', 'timeend')
+                                               );
+        $posts = new backup_nested_element('posts');
+        $post = new backup_nested_element('post',
+                                          array('id'),
+                                          array(
+                                              'discussion', 'parent', 'userid', 'created',
+                                              'modified', 'mailed', 'subject', 'message',
+                                              'messageformat', 'messagetrust', 'attachment', 'totalscore',
+                                              'mailnow')
+                                         );
+        $ratings = new backup_nested_element('ratings');
+        $rating = new backup_nested_element('rating',
+                                            array('id'),
+                                            array('userid', 'post', 'time', 'post_rating')
+                                           );
+        $reads = new backup_nested_element('readposts');
+        $read = new backup_nested_element('read',
+                                          array('id'),
+                                          array(
+                                              'userid', 'discussionid', 'postid',
+                                              'firstread', 'lastread')
+                                         );
+        $inventeds = new backup_nested_element('invented_elements',
+                                               array('reason', 'version')
+                                                   );
+        $invented = new backup_nested_element('invented',
+                                              null,
+                                              array('one', 'two', 'three')
+                                             );
+        $one = $invented->get_final_element('one');
+        $one->add_attributes(array('attr1', 'attr2'));
+
+        // Build the tree
+        $forum->add_child($discussions);
+        $discussions->add_child($discussion);
+
+        $discussion->add_child($posts);
+        $posts->add_child($post);
+
+        $post->add_child($ratings);
+        $ratings->add_child($rating);
+
+        $forum->add_child($reads);
+        $reads->add_child($read);
+
+        $forum->add_child($inventeds);
+        $inventeds->add_child($invented);
+
+        // Let's add 1 optigroup with 3 elements
+        $alternative1 = new backup_optigroup_element('alternative1',
+                                                     array('name', 'value'), '../../id', 1);
+        $alternative2 = new backup_optigroup_element('alternative2',
+                                                     array('name', 'value'), backup::VAR_PARENTID, 2);