MDL-23538 backup: tidied up phpdocs + coding style
authorSam Hemelryk <sam@moodle.com>
Wed, 12 Nov 2014 20:13:20 +0000 (09:13 +1300)
committerSam Hemelryk <sam@moodle.com>
Tue, 18 Nov 2014 21:04:10 +0000 (10:04 +1300)
15 files changed:
backup/util/ui/backup_moodleform.class.php
backup/util/ui/backup_ui.class.php
backup/util/ui/backup_ui_setting.class.php
backup/util/ui/backup_ui_stage.class.php
backup/util/ui/base_moodleform.class.php
backup/util/ui/base_ui.class.php
backup/util/ui/base_ui_stage.class.php
backup/util/ui/import_extensions.php
backup/util/ui/renderer.php
backup/util/ui/restore_moodleform.class.php
backup/util/ui/restore_ui.class.php
backup/util/ui/restore_ui_components.php
backup/util/ui/restore_ui_stage.class.php
backup/util/ui/tests/behat/behat_backup.php
backup/util/ui/tests/ui_test.php

index 3b66dc5..f586d40 100644 (file)
@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -20,7 +19,7 @@
  * as well as the individual forms that relate to the different stages the user
  * interface can exist within.
  *
- * @package   moodlecore
+ * @package   core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -34,6 +33,7 @@ defined('MOODLE_INTERNAL') || die();
  * grown african swallows all of whom have been carring coconuts for several days.
  * EWWWWW!!!!!!!!!!!!!!!!!!!!!!!!
  *
+ * @package core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -41,6 +41,8 @@ abstract class backup_moodleform extends base_moodleform {
     /**
      * Creates the form
      *
+     * Overridden for type hinting on the first arg.
+     *
      * @param backup_ui_stage $uistage
      * @param moodle_url|string $action
      * @param mixed $customdata
@@ -49,38 +51,71 @@ abstract class backup_moodleform extends base_moodleform {
      * @param array $attributes
      * @param bool $editable
      */
-    public function __construct(backup_ui_stage $uistage, $action = null, $customdata = null, $method = 'post', $target = '', $attributes = null, $editable = true) {
+    public function __construct(backup_ui_stage $uistage, $action = null, $customdata = null, $method = 'post',
+                                $target = '', $attributes = null, $editable = true) {
         parent::__construct($uistage, $action, $customdata, $method, $target, $attributes, $editable);
     }
 }
+
 /**
  * Initial backup user interface stage moodleform.
  *
  * Nothing to override we only need it defined so that moodleform doesn't get confused
  * between stages.
+ *
+ * @package   core_backup
+ * @copyright 2010 Sam Hemelryk
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class backup_initial_form extends backup_moodleform {}
+
 /**
  * Schema backup user interface stage moodleform.
  *
  * Nothing to override we only need it defined so that moodleform doesn't get confused
  * between stages.
+ *
+ * @package   core_backup
+ * @copyright 2010 Sam Hemelryk
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class backup_schema_form extends backup_moodleform {}
+
 /**
  * Confirmation backup user interface stage moodleform.
  *
  * Nothing to override we only need it defined so that moodleform doesn't get confused
  * between stages.
+ *
+ * @package   core_backup
+ * @copyright 2010 Sam Hemelryk
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class backup_confirmation_form extends backup_moodleform {
 
+    /**
+     * Adds the last elements, rules, settings etc to the form after data has been set.
+     *
+     * We override this to add a rule and type to the filename setting.
+     *
+     * @throws coding_exception
+     */
     public function definition_after_data() {
         parent::definition_after_data();
         $this->_form->addRule('setting_root_filename', get_string('errorfilenamerequired', 'backup'), 'required');
         $this->_form->setType('setting_root_filename', PARAM_FILE);
     }
 
+    /**
+     * Validates the form.
+     *
+     * Relies on the parent::validation for the bulk of the work.
+     *
+     * @param array $data
+     * @param array $files
+     * @return array
+     * @throws coding_exception
+     */
     public function validation($data, $files) {
         $errors = parent::validation($data, $files);
 
@@ -94,5 +129,4 @@ class backup_confirmation_form extends backup_moodleform {
 
         return $errors;
     }
-
 }
index d906d7c..02b71db 100644 (file)
@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -18,7 +17,7 @@
 /**
  * This file contains the backup user interface class
  *
- * @package   moodlecore
+ * @package   core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 /**
  * This is the backup user interface class
  *
- * The backup user interface class manages the user interface and backup for
- * Moodle.
+ * The backup user interface class manages the user interface and backup for Moodle.
  *
+ * @package core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class backup_ui extends base_ui {
     /**
      * The stages of the backup user interface.
+     * The initial stage of the backup - settings are here.
      */
     const STAGE_INITIAL = 1;
+
+    /**
+     * The stages of the backup user interface.
+     * The schema stage of the backup - here you choose the bits you include.
+     */
     const STAGE_SCHEMA = 2;
+
+    /**
+     * The stages of the backup user interface.
+     * The confirmation stage of the backup.
+     */
     const STAGE_CONFIRMATION = 4;
+
+    /**
+     * The stages of the backup user interface.
+     * The final stage of the backup - where it is being processed.
+     */
     const STAGE_FINAL = 8;
+
+    /**
+     * The stages of the backup user interface.
+     * The backup is now complete.
+     */
     const STAGE_COMPLETE = 16;
 
     /**
@@ -52,10 +72,11 @@ class backup_ui extends base_ui {
      * Intialises what ever stage is requested. If none are requested we check
      * params for 'stage' and default to initial
      *
-     * @param int|null $stage The desired stage to intialise or null for the default
+     * @param int $stage The desired stage to intialise or null for the default
+     * @param array $params
      * @return backup_ui_stage_initial|backup_ui_stage_schema|backup_ui_stage_confirmation|backup_ui_stage_final
      */
-    protected function initialise_stage($stage = null, array $params=null) {
+    protected function initialise_stage($stage = null, array $params = null) {
         if ($stage == null) {
             $stage = optional_param('stage', self::STAGE_INITIAL, PARAM_INT);
         }
@@ -81,6 +102,7 @@ class backup_ui extends base_ui {
         }
         return $stage;
     }
+
     /**
      * Returns the backup id
      * @return string
@@ -88,6 +110,7 @@ class backup_ui extends base_ui {
     public function get_uniqueid() {
         return $this->get_backupid();
     }
+
     /**
      * Gets the backup id from the controller
      * @return string
@@ -95,8 +118,10 @@ class backup_ui extends base_ui {
     public function get_backupid() {
         return $this->controller->get_backupid();
     }
+
     /**
      * Executes the backup plan
+     * @throws backup_ui_exception when the steps are wrong.
      * @return bool
      */
     public function execute() {
@@ -112,16 +137,18 @@ class backup_ui extends base_ui {
         $this->stage = new backup_ui_stage_complete($this, $this->stage->get_params(), $this->controller->get_results());
         return true;
     }
+
     /**
      * Loads the backup controller if we are tracking one
+     * @param string $backupid
      * @return backup_controller|false
      */
-    final public static function load_controller($backupid=false) {
-        // Get the backup id optional param
+    final public static function load_controller($backupid = false) {
+        // Get the backup id optional param.
         if ($backupid) {
             try {
                 // Try to load the controller with it.
-                // If it fails at this point it is likely because this is the first load
+                // If it fails at this point it is likely because this is the first load.
                 $controller = backup_controller::load_controller($backupid);
                 return $controller;
             } catch (Exception $e) {
@@ -143,24 +170,24 @@ class backup_ui extends base_ui {
         $items = array();
         while ($stage > 0) {
             $classes = array('backup_stage');
-            if (floor($stage/2) == $currentstage) {
+            if (floor($stage / 2) == $currentstage) {
                 $classes[] = 'backup_stage_next';
             } else if ($stage == $currentstage) {
                 $classes[] = 'backup_stage_current';
             } else if ($stage < $currentstage) {
                 $classes[] = 'backup_stage_complete';
             }
-            $item = array('text' => strlen(decbin($stage)).'. '.get_string('currentstage'.$stage, 'backup'),'class' => join(' ', $classes));
-            if ($stage < $currentstage && $currentstage < self::STAGE_COMPLETE && (!self::$skipcurrentstage || ($stage*2) != $currentstage)) {
+            $item = array('text' => strlen(decbin($stage)).'. '.get_string('currentstage'.$stage, 'backup'), 'class' => join(' ', $classes));
+            if ($stage < $currentstage && $currentstage < self::STAGE_COMPLETE && (!self::$skipcurrentstage || ($stage * 2) != $currentstage)) {
                 $params = $this->stage->get_params();
                 if (empty($params)) {
                     $params = array();
                 }
-                $params = array_merge($params, array('backup'=>$this->get_backupid(), 'stage'=>$stage));
+                $params = array_merge($params, array('backup' => $this->get_backupid(), 'stage' => $stage));
                 $item['link'] = new moodle_url($PAGE->url, $params);
             }
             array_unshift($items, $item);
-            $stage = floor($stage/2);
+            $stage = floor($stage / 2);
         }
         return $items;
     }
@@ -181,13 +208,18 @@ class backup_ui extends base_ui {
     /**
      * If called with default arg the current stage gets skipped.
      * @static
+     * @param bool $setting Set to true (default) if you want to skip this stage, false otherwise.
      */
-    public static function skip_current_stage($setting=true) {
+    public static function skip_current_stage($setting = true) {
         self::$skipcurrentstage = $setting;
     }
 }
 
 /**
  * Backup user interface exception. Modelled off the backup_exception class
+ *
+ * @package   core_backup
+ * @copyright 2010 Sam Hemelryk
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class backup_ui_exception extends base_ui_exception {}
index 1712a73..37d6e75 100644 (file)
@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -19,7 +18,7 @@
  * This file contains the setting user interface classes that all backup/restore
  * settings use to represent the UI they have.
  *
- * @package   moodlecore
+ * @package   core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -28,6 +27,7 @@
  * Abstract class used to represent the user interface that a setting has.
  *
  * @todo extend as required for restore
+ * @package core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -66,6 +66,7 @@ class base_setting_ui {
      * @var base_setting|backup_setting
      */
     protected $setting;
+
     /**
      * Constructors are sooooo cool
      * @param base_setting $setting
@@ -78,7 +79,7 @@ class base_setting_ui {
      * Destroy all circular references. It helps PHP 5.2 a lot!
      */
     public function destroy() {
-        // No need to destroy anything recursively here, direct reset
+        // No need to destroy anything recursively here, direct reset.
         $this->setting = null;
     }
 
@@ -89,6 +90,7 @@ class base_setting_ui {
     public function get_name() {
         return self::NAME_PREFIX.$this->name;
     }
+
     /**
      * Gets the name of this item including its prefix
      * @return string
@@ -96,6 +98,7 @@ class base_setting_ui {
     public function get_label() {
         return $this->label;
     }
+
     /**
      * Gets the type of this element
      * @return int
@@ -103,6 +106,7 @@ class base_setting_ui {
     public function get_type() {
         return $this->type;
     }
+
     /**
      * Gets the HTML attributes for this item
      * @return array
@@ -110,6 +114,7 @@ class base_setting_ui {
     public function get_attributes() {
         return $this->attributes;
     }
+
     /**
      * Gets the value of this setting
      * @return mixed
@@ -117,6 +122,7 @@ class base_setting_ui {
     public function get_value() {
         return $this->setting->get_value();
     }
+
     /**
      * Gets the value to display in a static quickforms element
      * @return mixed
@@ -135,7 +141,9 @@ class base_setting_ui {
     }
 
     /**
-     * Sets the label
+     * Sets the label.
+     *
+     * @throws base_setting_ui_exception when the label is not valid.
      * @param string $label
      */
     public function set_label($label) {
@@ -145,11 +153,12 @@ class base_setting_ui {
         }
         $this->label = $label;
     }
+
     /**
      * Disables the UI for this element
      */
     public function disable() {
-       $this->attributes['disabled'] = 'disabled';
+        $this->attributes['disabled'] = 'disabled';
     }
 
     /**
@@ -177,6 +186,7 @@ class base_setting_ui {
 /**
  * Abstract class to represent the user interface backup settings have
  *
+ * @package core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -191,13 +201,13 @@ abstract class backup_setting_ui extends base_setting_ui {
      * JAC... Just Another Constructor
      *
      * @param backup_setting $setting
-     * @param string|null $label The label to display with the setting ui
-     * @param array|null $attributes Array of HTML attributes to apply to the element
-     * @param array|null $options Array of options to apply to the setting ui object
+     * @param string $label The label to display with the setting ui
+     * @param array $attributes Array of HTML attributes to apply to the element
+     * @param array $options Array of options to apply to the setting ui object
      */
     public function __construct(backup_setting $setting, $label = null, array $attributes = null, array $options = null) {
         parent::__construct($setting);
-        // Improve the inputs name by appending the level to the name
+        // Improve the inputs name by appending the level to the name.
         switch ($setting->get_level()) {
             case backup_setting::ROOT_LEVEL :
                 $this->name = 'root_'.$setting->get_name();
@@ -220,21 +230,20 @@ abstract class backup_setting_ui extends base_setting_ui {
             $this->options = $options;
         }
     }
+
     /**
      * Creates a new backup setting ui based on the setting it is given
      *
-     * Throws an exception if an invalid type is provided.
-     *
+     * @throws backup_setting_ui_exception if the setting type is not supported,
      * @param backup_setting $setting
      * @param int $type The backup_setting UI type. One of backup_setting::UI_*;
      * @param string $label The label to display with the setting ui
      * @param array $attributes Array of HTML attributes to apply to the element
      * @param array $options Array of options to apply to the setting ui object
-     *
      * @return backup_setting_ui_text|backup_setting_ui_checkbox|backup_setting_ui_select|backup_setting_ui_radio
      */
-    final public static function make(backup_setting $setting, $type, $label, array $attributes = null, array $options=null) {
-        // Base the decision we make on the type that was sent
+    final public static function make(backup_setting $setting, $type, $label, array $attributes = null, array $options = null) {
+        // Base the decision we make on the type that was sent.
         switch ($type) {
             case backup_setting::UI_HTML_CHECKBOX :
                 return new backup_setting_ui_checkbox($setting, $label, null, (array)$attributes, (array)$options);
@@ -248,11 +257,16 @@ abstract class backup_setting_ui extends base_setting_ui {
                 throw new backup_setting_ui_exception('setting_invalid_ui_type');
         }
     }
+
     /**
      * Get element properties that can be used to make a quickform element
+     *
+     * @param base_task $task
+     * @param renderer_base $output
      * @return array
      */
-    abstract public function get_element_properties(base_task $task=null, renderer_base $output=null);
+    abstract public function get_element_properties(base_task $task = null, renderer_base $output = null);
+
     /**
      * Applies config options to a given properties array and then returns it
      * @param array $properties
@@ -264,16 +278,17 @@ abstract class backup_setting_ui extends base_setting_ui {
         }
         return $properties;
     }
+
     /**
      * Gets the label for this item
-     * @param backup_task|null $task Optional, if provided and the setting is an include
+     * @param base_task $task Optional, if provided and the setting is an include
      *          $task is used to set the setting label
      * @return string
      */
-    public function get_label(base_task $task=null) {
-        // If a task has been provided and the label is not already set meaniningfully
+    public function get_label(base_task $task = null) {
+        // If a task has been provided and the label is not already set meaningfully
         // we will attempt to improve it.
-        if (!is_null($task) && $this->label == $this->setting->get_name() && strpos($this->setting->get_name(), '_include')!==false) {
+        if (!is_null($task) && $this->label == $this->setting->get_name() && strpos($this->setting->get_name(), '_include') !== false) {
             if ($this->setting->get_level() == backup_setting::SECTION_LEVEL) {
                 $this->label = get_string('includesection', 'backup', $task->get_name());
             } else if ($this->setting->get_level() == backup_setting::ACTIVITY_LEVEL) {
@@ -282,6 +297,7 @@ abstract class backup_setting_ui extends base_setting_ui {
         }
         return $this->label;
     }
+
     /**
      * Returns true if the setting is changeable.
      *
@@ -296,24 +312,23 @@ abstract class backup_setting_ui extends base_setting_ui {
      */
     public function is_changeable() {
         if ($this->setting->get_status() === backup_setting::NOT_LOCKED) {
-            // Its not locked so its chanegable
+            // Its not locked so its chanegable.
             return true;
         } else if ($this->setting->get_status() !== backup_setting::LOCKED_BY_HIERARCHY) {
-            // Its not changeable because its locked by permission or config
+            // Its not changeable because its locked by permission or config.
             return false;
         } else if ($this->setting->has_dependencies_on_settings()) {
             foreach ($this->setting->get_settings_depended_on() as $dependency) {
                 if ($dependency->is_locked() && $dependency->get_setting()->get_level() !== $this->setting->get_level()) {
-                    // Its not changeable because one or more dependancies arn't
-                    // changeable.
-                   return false;
+                    // Its not changeable because one or more dependancies arn't changeable.
+                    return false;
                 }
             }
             // Its changeable because all dependencies are changeable.
             return true;
         }
         // We should never get here but if we do return false to be safe.
-        // The setting would need to be locked by hierarchy and not have any deps
+        // The setting would need to be locked by hierarchy and not have any deps.
         return false;
     }
 
@@ -322,6 +337,7 @@ abstract class backup_setting_ui extends base_setting_ui {
 /**
  * A text input user interface element for backup settings
  *
+ * @package core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -330,20 +346,26 @@ class backup_setting_ui_text extends backup_setting_ui {
      * @var int
      */
     protected $type = backup_setting::UI_HTML_TEXTFIELD;
+
     /**
      * Returns an array of properties suitable for generating a quickforms element
-     * @param backup_task|null $task
+     * @param base_task $task
+     * @param renderer_base $output
      * @return array (element, name, label, attributes)
      */
-    public function get_element_properties(base_task $task=null, renderer_base $output=null) {
-        // name, label, text, attributes
+    public function get_element_properties(base_task $task = null, renderer_base $output = null) {
         $icon = $this->get_icon();
         $label = $this->get_label($task);
         if (!empty($icon)) {
             $label .= $output->render($icon);
         }
-        // name, label, attributes
-        return $this->apply_options(array('element'=>'text','name'=>self::NAME_PREFIX.$this->name, 'label'=>$label, 'attributes'=>$this->attributes));
+        // Name, label, attributes.
+        return $this->apply_options(array(
+            'element' => 'text',
+            'name' => self::NAME_PREFIX.$this->name,
+            'label' => $label,
+            'attributes' => $this->attributes)
+        );
     }
 
 }
@@ -351,50 +373,64 @@ class backup_setting_ui_text extends backup_setting_ui {
 /**
  * A checkbox user interface element for backup settings (default)
  *
+ * @package core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class backup_setting_ui_checkbox extends backup_setting_ui {
+
     /**
      * @var int
      */
     protected $type = backup_setting::UI_HTML_CHECKBOX;
+
     /**
      * @var bool
      */
     protected $changeable = true;
+
     /**
      * The text to show next to the checkbox
      * @var string
      */
     protected $text;
+
     /**
      * Overridden constructor so we can take text argument
+     *
      * @param backup_setting $setting
      * @param string $label
      * @param string $text
      * @param array $attributes
      * @param array $options
      */
-    public function __construct(backup_setting $setting, $label = null, $text=null, array $attributes = array(), array $options = array()) {
+    public function __construct(backup_setting $setting, $label = null, $text = null, array $attributes = array(), array $options = array()) {
         parent::__construct($setting, $label, $attributes, $options);
         $this->text = $text;
     }
+
     /**
      * Returns an array of properties suitable for generating a quickforms element
-     * @param backup_task|null $task
+     * @param base_task $task
+     * @param renderer_base $output
      * @return array (element, name, label, text, attributes);
      */
-    public function get_element_properties(base_task $task=null, renderer_base $output=null) {
-        // name, label, text, attributes
-
+    public function get_element_properties(base_task $task = null, renderer_base $output = null) {
+        // Name, label, text, attributes.
         $icon = $this->get_icon();
         $label = $this->get_label($task);
         if (!empty($icon)) {
             $label .= $output->render($icon);
         }
-        return $this->apply_options(array('element'=>'checkbox','name'=>self::NAME_PREFIX.$this->name, 'label'=>$label, 'text'=>$this->text, 'attributes'=>$this->attributes));
+        return $this->apply_options(array(
+            'element' => 'checkbox',
+            'name' => self::NAME_PREFIX.$this->name,
+            'label' => $label,
+            'text' => $this->text,
+            'attributes' => $this->attributes
+        ));
     }
+
     /**
      * Sets the text for the element
      * @param string $text
@@ -402,6 +438,7 @@ class backup_setting_ui_checkbox extends backup_setting_ui {
     public function set_text($text) {
         $this->text = $text;
     }
+
     /**
      * Gets the static value for the element
      * @global core_renderer $OUTPUT
@@ -409,7 +446,7 @@ class backup_setting_ui_checkbox extends backup_setting_ui {
      */
     public function get_static_value() {
         global $OUTPUT;
-        // Checkboxes are always yes or no
+        // Checkboxes are always yes or no.
         if ($this->get_value()) {
             return $OUTPUT->pix_icon('i/valid', get_string('yes'));
         } else {
@@ -422,7 +459,7 @@ class backup_setting_ui_checkbox extends backup_setting_ui {
      * @return bool
      */
     public function is_changeable() {
-        if ($this->changeable===false) {
+        if ($this->changeable === false) {
             return false;
         } else {
             return parent::is_changeable();
@@ -442,6 +479,7 @@ class backup_setting_ui_checkbox extends backup_setting_ui {
 /**
  * Radio button user interface element for backup settings
  *
+ * @package core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -450,17 +488,21 @@ class backup_setting_ui_radio extends backup_setting_ui {
      * @var int
      */
     protected $type = backup_setting::UI_HTML_RADIOBUTTON;
+
     /**
      * The string shown next to the input
      * @var string
      */
     protected $text;
+
     /**
      * The value for the radio input
      * @var string
      */
     protected $value;
+
     /**
+     * Constructor
      *
      * @param backup_setting $setting
      * @param string $label
@@ -469,25 +511,33 @@ class backup_setting_ui_radio extends backup_setting_ui {
      * @param array $attributes
      * @param array $options
      */
-    public function __construct(backup_setting $setting, $label = null, $text=null, $value=null, array $attributes = array(), array $options = array()) {
+    public function __construct(backup_setting $setting, $label = null, $text = null, $value = null, array $attributes = array(), array $options = array()) {
         parent::__construct($setting, $label, $attributes, $options);
         $this->text = $text;
         $this->value = (string)$value;
     }
+
     /**
      * Returns an array of properties suitable for generating a quickforms element
-     * @param backup_task|null $task
+     * @param base_task $task
+     * @param renderer_base $output
      * @return array (element, name, label, text, value, attributes)
      */
-    public function get_element_properties(base_task $task=null, renderer_base $output=null) {
-        // name, label, text, attributes
+    public function get_element_properties(base_task $task = null, renderer_base $output = null) {
         $icon = $this->get_icon();
         $label = $this->get_label($task);
         if (!empty($icon)) {
             $label .= $output->render($icon);
         }
-        // name, label, text, value, attributes
-        return $this->apply_options(array('element'=>'radio','name'=>self::NAME_PREFIX.$this->name, 'label'=>$label, 'text'=>$this->text, 'value'=>$this->value, 'attributes'=>$this->attributes));
+        // Name, label, text, value, attributes.
+        return $this->apply_options(array(
+            'element' => 'radio',
+            'name' => self::NAME_PREFIX.$this->name,
+            'label' => $label,
+            'text' => $this->text,
+            'value' => $this->value,
+            'attributes' => $this->attributes
+        ));
     }
     /**
      * Sets the text next to this input
@@ -514,6 +564,7 @@ class backup_setting_ui_radio extends backup_setting_ui {
 /**
  * A select box, drop down user interface for backup settings
  *
+ * @package core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -522,12 +573,15 @@ class backup_setting_ui_select extends backup_setting_ui {
      * @var int
      */
     protected $type = backup_setting::UI_HTML_DROPDOWN;
+
     /**
      * An array of options to display in the select
      * @var array
      */
     protected $values;
+
     /**
+     * Constructor
      *
      * @param backup_setting $setting
      * @param string $label
@@ -535,32 +589,41 @@ class backup_setting_ui_select extends backup_setting_ui {
      * @param array $attributes
      * @param array $options
      */
-    public function __construct(backup_setting $setting, $label = null, $values=null, array $attributes = array(), array $options = array()) {
+    public function __construct(backup_setting $setting, $label = null, $values = null, array $attributes = array(), array $options = array()) {
         parent::__construct($setting, $label, $attributes, $options);
         $this->values = $values;
     }
+
     /**
      * Returns an array of properties suitable for generating a quickforms element
-     * @param backup_task|null $task
+     * @param base_task $task
+     * @param renderer_base $output
      * @return array (element, name, label, options, attributes)
      */
-    public function get_element_properties(base_task $task = null, renderer_base $output=null) {
-        // name, label, text, attributes
+    public function get_element_properties(base_task $task = null, renderer_base $output = null) {
         $icon = $this->get_icon();
         $label = $this->get_label($task);
         if (!empty($icon)) {
             $label .= $output->render($icon);
         }
-        // name, label, options, attributes
-        return $this->apply_options(array('element'=>'select','name'=>self::NAME_PREFIX.$this->name, 'label'=>$label, 'options'=>$this->values, 'attributes'=>$this->attributes));
+        // Name, label, options, attributes.
+        return $this->apply_options(array(
+            'element' => 'select',
+            'name' => self::NAME_PREFIX.$this->name,
+            'label' => $label,
+            'options' => $this->values,
+            'attributes' => $this->attributes
+        ));
     }
+
     /**
      * Sets the options for the select box
-     * @param array $values Associative array of value=>text options
+     * @param array $values Associative array of value => text options
      */
     public function set_values(array $values) {
         $this->values = $values;
     }
+
     /**
      * Gets the static value for this select element
      * @return string
@@ -568,6 +631,7 @@ class backup_setting_ui_select extends backup_setting_ui {
     public function get_static_value() {
         return $this->values[$this->get_value()];
     }
+
     /**
      * Returns true if the setting is changeable, false otherwise
      *
@@ -582,8 +646,22 @@ class backup_setting_ui_select extends backup_setting_ui {
     }
 }
 
+/**
+ * A date selector user interface widget for backup settings.
+ *
+ * @package core_backup
+ * @copyright 2010 Sam Hemelryk
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class backup_setting_ui_dateselector extends backup_setting_ui_text {
-    public function get_element_properties(base_task $task = null, renderer_base $output=null) {
+
+    /**
+     * Returns an array of properties suitable for generating a quickforms element
+     * @param base_task $task
+     * @param renderer_base $output
+     * @return array (element, name, label, options, attributes)
+     */
+    public function get_element_properties(base_task $task = null, renderer_base $output = null) {
         if (!array_key_exists('optional', $this->attributes)) {
             $this->attributes['optional'] = false;
         }
@@ -591,6 +669,11 @@ class backup_setting_ui_dateselector extends backup_setting_ui_text {
         $properties['element'] = 'date_selector';
         return $properties;
     }
+
+    /**
+     * Gets the static value for this select element
+     * @return string
+     */
     public function get_static_value() {
         $value = $this->get_value();
         if (!empty($value)) {
@@ -600,5 +683,20 @@ class backup_setting_ui_dateselector extends backup_setting_ui_text {
     }
 }
 
+/**
+ * Base setting UI exception class.
+ *
+ * @package core_backup
+ * @copyright 2010 Sam Hemelryk
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class base_setting_ui_exception extends base_setting_exception {}
+
+/**
+ * Backup setting UI exception class.
+ *
+ * @package core_backup
+ * @copyright 2010 Sam Hemelryk
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class backup_setting_ui_exception extends base_setting_ui_exception {};
index cde79ff..ec1b3b1 100644 (file)
@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -20,9 +19,9 @@
  *
  * This file contains the classes required to manage the stages that make up the
  * backup user interface.
- * These will be primarily operated a {@see backup_ui} instance.
+ * These will be primarily operated a {@link backup_ui} instance.
  *
- * @package   moodlecore
+ * @package   core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
  *  - process : To process the stage
  *  - initialise_stage_form : To get a backup_moodleform instance for the stage
  *
+ * @package   core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 abstract class backup_ui_stage extends base_ui_stage {
 
+    /**
+     * Constructor.
+     *
+     * @param backup_ui $ui
+     * @param array $params
+     */
     public function __construct(backup_ui $ui, array $params = null) {
-       parent::__construct($ui, $params);
+        parent::__construct($ui, $params);
     }
+
     /**
      * The backup id from the backup controller
      * @return string
@@ -57,6 +64,7 @@ abstract class backup_ui_stage extends base_ui_stage {
  *
  * In this stage the user is required to set the root level settings.
  *
+ * @package   core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -71,15 +79,16 @@ class backup_ui_stage_initial extends backup_ui_stage {
     /**
      * Initial backup stage constructor
      * @param backup_ui $ui
+     * @param array $params
      */
-    public function __construct(backup_ui $ui, array $params=null) {
+    public function __construct(backup_ui $ui, array $params = null) {
         $this->stage = backup_ui::STAGE_INITIAL;
         parent::__construct($ui, $params);
     }
 
     /**
      * Processes the initial backup stage
-     * @param backup_moodleform $form
+     * @param base_moodleform $m
      * @return int The number of changes
      */
     public function process(base_moodleform $m = null) {
@@ -98,9 +107,9 @@ class backup_ui_stage_initial extends backup_ui_stage {
             $tasks = $this->ui->get_tasks();
             $changes = 0;
             foreach ($tasks as &$task) {
-                // We are only interesting in the backup root task for this stage
+                // We are only interesting in the backup root task for this stage.
                 if ($task instanceof backup_root_task) {
-                    // Get all settings into a var so we can iterate by reference
+                    // Get all settings into a var so we can iterate by reference.
                     $settings = $task->get_settings();
                     foreach ($settings as &$setting) {
                         $name = $setting->get_ui_name();
@@ -114,7 +123,7 @@ class backup_ui_stage_initial extends backup_ui_stage {
                     }
                 }
             }
-            // Return the number of changes the user made
+            // Return the number of changes the user made.
             return $changes;
         } else {
             return false;
@@ -166,24 +175,24 @@ class backup_ui_stage_initial extends backup_ui_stage {
         global $PAGE;
         if ($this->stageform === null) {
             $form = new backup_initial_form($this, $PAGE->url);
-            // Store as a variable so we can iterate by reference
+            // Store as a variable so we can iterate by reference.
             $tasks = $this->ui->get_tasks();
-            // Iterate all tasks by reference
+            // Iterate all tasks by reference.
             $add_settings = array();
             $dependencies = array();
             foreach ($tasks as &$task) {
-                // For the initial stage we are only interested in the root settings
+                // For the initial stage we are only interested in the root settings.
                 if ($task instanceof backup_root_task) {
                     $form->add_heading('rootsettings', get_string('rootsettings', 'backup'));
                     $settings = $task->get_settings();
-                    // First add all settings except the filename setting
+                    // First add all settings except the filename setting.
                     foreach ($settings as &$setting) {
                         if ($setting->get_name() == 'filename') {
                             continue;
                         }
                         $add_settings[] = array($setting, $task);
                     }
-                    // Then add all dependencies
+                    // Then add all dependencies.
                     foreach ($settings as &$setting) {
                         if ($setting->get_name() == 'filename') {
                             continue;
@@ -200,7 +209,7 @@ class backup_ui_stage_initial extends backup_ui_stage {
             }
             $this->stageform = $form;
         }
-        // Return the form
+        // Return the form.
         return $this->stageform;
     }
 }
@@ -211,10 +220,12 @@ class backup_ui_stage_initial extends backup_ui_stage {
  * During the schema stage the user is required to set the settings that relate
  * to the area that they are backing up as well as its children.
  *
+ * @package   core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class backup_ui_stage_schema extends backup_ui_stage {
+
     /**
      * @var int Maximum number of settings to add to form at once
      */
@@ -222,38 +233,40 @@ class backup_ui_stage_schema extends backup_ui_stage {
 
     /**
      * Schema stage constructor
-     * @param backup_moodleform $ui
+     * @param backup_ui $ui
+     * @param array $params
      */
-    public function __construct(backup_ui $ui, array $params=null) {
+    public function __construct(backup_ui $ui, array $params = null) {
         $this->stage = backup_ui::STAGE_SCHEMA;
         parent::__construct($ui, $params);
     }
+
     /**
      * Processes the schema stage
      *
-     * @param backup_moodleform|null $form
+     * @param base_moodleform $form
      * @return int The number of changes the user made
      */
     public function process(base_moodleform $form = null) {
         $form = $this->initialise_stage_form();
-        // Check it wasn't cancelled
+        // Check it wasn't cancelled.
         if ($form->is_cancelled()) {
             $this->ui->cancel_process();
         }
 
-        // Check it has been submit
+        // Check it has been submit.
         $data = $form->get_data();
         if ($data && confirm_sesskey()) {
-            // Get the tasks into a var so we can iterate by reference
+            // Get the tasks into a var so we can iterate by reference.
             $tasks = $this->ui->get_tasks();
             $changes = 0;
-            // Iterate all tasks by reference
+            // Iterate all tasks by reference.
             foreach ($tasks as &$task) {
-                // We are only interested in schema settings
+                // We are only interested in schema settings.
                 if (!($task instanceof backup_root_task)) {
-                    // Store as a variable so we can iterate by reference
+                    // Store as a variable so we can iterate by reference.
                     $settings = $task->get_settings();
-                    // Iterate by reference
+                    // Iterate by reference.
                     foreach ($settings as &$setting) {
                         $name = $setting->get_ui_name();
                         if (isset($data->$name) &&  $data->$name != $setting->get_value()) {
@@ -266,12 +279,13 @@ class backup_ui_stage_schema extends backup_ui_stage {
                     }
                 }
             }
-            // Return the number of changes the user made
+            // Return the number of changes the user made.
             return $changes;
         } else {
             return false;
         }
     }
+
     /**
      * Creates the backup_schema_form instance for this stage
      *
@@ -297,24 +311,24 @@ class backup_ui_stage_schema extends backup_ui_stage {
             foreach ($tasks as $task) {
                 if (!($task instanceof backup_root_task)) {
                     if (!$courseheading) {
-                        // If we havn't already display a course heading to group nicely
+                        // If we haven't already display a course heading to group nicely.
                         $form->add_heading('coursesettings', get_string('includeactivities', 'backup'));
                         $courseheading = true;
                     }
-                    // First add each setting
+                    // First add each setting.
                     foreach ($task->get_settings() as $setting) {
                         $add_settings[] = array($setting, $task);
                     }
-                    // The add all the dependencies
+                    // The add all the dependencies.
                     foreach ($task->get_settings() as $setting) {
                         $dependencies[] = $setting;
                     }
                 } else if ($this->ui->enforce_changed_dependencies()) {
                     // Only show these settings if dependencies changed them.
-                    // Add a root settings heading to group nicely
+                    // Add a root settings heading to group nicely.
                     $form->add_heading('rootsettings', get_string('rootsettings', 'backup'));
                     // Iterate all settings and add them to the form as a fixed
-                    // setting. We only want schema settings to be editable
+                    // setting. We only want schema settings to be editable.
                     foreach ($task->get_settings() as $setting) {
                         if ($setting->get_name() != 'filename') {
                             $form->add_fixed_setting($setting, $task);
@@ -328,13 +342,13 @@ class backup_ui_stage_schema extends backup_ui_stage {
 
             // Add settings for tasks in batches of up to 1000. Adding settings
             // in larger batches improves performance, but if it takes too long,
-            // we won't be able to update the progress bar so the backup might
+            // we won't be able to update the progress bar so the backup might.
             // time out. 1000 is chosen to balance this.
             $numsettings = count($add_settings);
             $progress->start_progress('', ceil($numsettings / self::MAX_SETTINGS_BATCH));
             $start = 0;
             $done = 1;
-            while($start < $numsettings) {
+            while ($start < $numsettings) {
                 $length = min(self::MAX_SETTINGS_BATCH, $numsettings - $start);
                 $form->add_settings(array_slice($add_settings, $start, $length));
                 $start += $length;
@@ -364,40 +378,44 @@ class backup_ui_stage_schema extends backup_ui_stage {
  * On this stage the user reviews the setting for the backup and can change the filename
  * of the file that will be generated.
  *
+ * @package   core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class backup_ui_stage_confirmation extends backup_ui_stage {
+
     /**
      * Constructs the stage
      * @param backup_ui $ui
+     * @param array $params
      */
-    public function __construct($ui, array $params=null) {
+    public function __construct($ui, array $params = null) {
         $this->stage = backup_ui::STAGE_CONFIRMATION;
         parent::__construct($ui, $params);
     }
+
     /**
      * Processes the confirmation stage
      *
-     * @param backup_moodleform $form
+     * @param base_moodleform $form
      * @return int The number of changes the user made
      */
     public function process(base_moodleform $form = null) {
         $form = $this->initialise_stage_form();
-        // Check it hasn't been cancelled
+        // Check it hasn't been cancelled.
         if ($form->is_cancelled()) {
             $this->ui->cancel_process();
         }
 
         $data = $form->get_data();
         if ($data && confirm_sesskey()) {
-            // Collect into a variable so we can iterate by reference
+            // Collect into a variable so we can iterate by reference.
             $tasks = $this->ui->get_tasks();
             $changes = 0;
-            // Iterate each task by reference
+            // Iterate each task by reference.
             foreach ($tasks as &$task) {
                 if ($task instanceof backup_root_task) {
-                    // At this stage all we are interested in is the filename setting
+                    // At this stage all we are interested in is the filename setting.
                     $setting = $task->get_setting('filename');
                     $name = $setting->get_ui_name();
                     if (isset($data->$name) &&  $data->$name != $setting->get_value()) {
@@ -406,12 +424,13 @@ class backup_ui_stage_confirmation extends backup_ui_stage {
                     }
                 }
             }
-            // Return the number of changes the user made
+            // Return the number of changes the user made.
             return $changes;
         } else {
             return false;
         }
     }
+
     /**
      * Creates the backup_confirmation_form instance this stage requires
      *
@@ -420,7 +439,7 @@ class backup_ui_stage_confirmation extends backup_ui_stage {
     protected function initialise_stage_form() {
         global $PAGE;
         if ($this->stageform === null) {
-            // Get the form
+            // Get the form.
             $form = new backup_confirmation_form($this, $PAGE->url);
             $content = '';
             $courseheading = false;
@@ -449,16 +468,16 @@ class backup_ui_stage_confirmation extends backup_ui_stage {
 
             foreach ($tasks as $task) {
                 if ($task instanceof backup_root_task) {
-                    // If its a backup root add a root settings heading to group nicely
+                    // If its a backup root add a root settings heading to group nicely.
                     $form->add_heading('rootsettings', get_string('rootsettings', 'backup'));
                 } else if (!$courseheading) {
-                    // we havn't already add a course heading
+                    // We haven't already add a course heading.
                     $form->add_heading('coursesettings', get_string('includeditems', 'backup'));
                     $courseheading = true;
                 }
-                // Iterate all settings, doesnt need to happen by reference
+                // Iterate all settings, doesnt need to happen by reference.
                 foreach ($task->get_settings() as $setting) {
-                    // For this stage only the filename setting should be editable
+                    // For this stage only the filename setting should be editable.
                     if ($setting->get_name() != 'filename') {
                         $form->add_fixed_setting($setting, $task);
                     }
@@ -488,34 +507,47 @@ class backup_ui_stage_confirmation extends backup_ui_stage {
  * This highlights that we neither need a form nor a display method for this stage
  * we simply need to process.
  *
+ * @package   core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class backup_ui_stage_final extends backup_ui_stage {
+
     /**
      * Constructs the final stage
      * @param backup_ui $ui
+     * @param array $params
      */
-    public function __construct(backup_ui $ui, array $params=null) {
+    public function __construct(backup_ui $ui, array $params = null) {
         $this->stage = backup_ui::STAGE_FINAL;
         parent::__construct($ui, $params);
     }
+
     /**
      * Processes the final stage.
      *
      * In this case it ALWAYS passes processing to the previous stage (confirmation)
+     *
+     * @param base_moodleform $form
+     * @return bool
      */
-    public function process(base_moodleform $form=null) {
+    public function process(base_moodleform $form = null) {
         return true;
     }
+
     /**
      * should NEVER be called... throws an exception
      */
     protected function initialise_stage_form() {
         throw new backup_ui_exception('backup_ui_must_execute_first');
     }
+
     /**
      * should NEVER be called... throws an exception
+     *
+     * @throws backup_ui_exception always
+     * @param core_backup_renderer $renderer
+     * @return void
      */
     public function display(core_backup_renderer $renderer) {
         throw new backup_ui_exception('backup_ui_must_execute_first');
@@ -528,26 +560,31 @@ class backup_ui_stage_final extends backup_ui_stage {
  * At this stage everything is done and the user will be redirected to view the
  * backup file in the file browser.
  *
+ * @package   core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class backup_ui_stage_complete extends backup_ui_stage_final {
+
     /**
      * The results of the backup execution
      * @var array
      */
     protected $results;
+
     /**
      * Constructs the complete backup stage
+     *
      * @param backup_ui $ui
-     * @param array|null $params
+     * @param array $params
      * @param array $results
      */
-    public function __construct(backup_ui $ui, array $params=null, array $results=null) {
+    public function __construct(backup_ui $ui, array $params = null, array $results = null) {
         $this->results = $results;
         parent::__construct($ui, $params);
         $this->stage = backup_ui::STAGE_COMPLETE;
     }
+
     /**
      * Displays the completed backup stage.
      *
@@ -559,20 +596,20 @@ class backup_ui_stage_complete extends backup_ui_stage_final {
      */
     public function display(core_backup_renderer $renderer) {
 
-        // Get the resulting stored_file record
+        // Get the resulting stored_file record.
         $type = $this->get_ui()->get_controller()->get_type();
         $courseid = $this->get_ui()->get_controller()->get_courseid();
         switch ($type) {
-        case 'activity':
-            $cmid = $this->get_ui()->get_controller()->get_id();
-            $cm = get_coursemodule_from_id(null, $cmid, $courseid);
-            $modcontext = context_module::instance($cm->id);
-            $restorerul = new moodle_url('/backup/restorefile.php', array('contextid'=>$modcontext->id));
-            break;
-        case 'course':
-        default:
-            $coursecontext = context_course::instance($courseid);
-            $restorerul = new moodle_url('/backup/restorefile.php', array('contextid'=>$coursecontext->id));
+            case 'activity':
+                $cmid = $this->get_ui()->get_controller()->get_id();
+                $cm = get_coursemodule_from_id(null, $cmid, $courseid);
+                $modcontext = context_module::instance($cm->id);
+                $restorerul = new moodle_url('/backup/restorefile.php', array('contextid' => $modcontext->id));
+                break;
+            case 'course':
+            default:
+                $coursecontext = context_course::instance($courseid);
+                $restorerul = new moodle_url('/backup/restorefile.php', array('contextid' => $coursecontext->id));
         }
 
         $output = '';
index 6f03ee4..b5c8159 100644 (file)
@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -20,7 +19,7 @@
  * as well as the individual forms that relate to the different stages the user
  * interface can exist within.
  *
- * @package   moodlecore
+ * @package   core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -30,40 +29,46 @@ defined('MOODLE_INTERNAL') || die();
 require_once($CFG->libdir . '/formslib.php');
 
 /**
- * Backup moodleform bridge
+ * Base moodleform bridge
  *
  * Ahhh the mighty moodleform bridge! Strong enough to take the weight of 682 full
  * grown african swallows all of whom have been carring coconuts for several days.
  * EWWWWW!!!!!!!!!!!!!!!!!!!!!!!!
  *
+ * @package   core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 abstract class base_moodleform extends moodleform {
+
     /**
      * The stage this form belongs to
      * @var base_ui_stage
      */
     protected $uistage = null;
+
     /**
      * True if we have a course div open, false otherwise
      * @var bool
      */
     protected $coursediv = false;
+
     /**
      * True if we have a section div open, false otherwise
      * @var bool
      */
     protected $sectiondiv = false;
+
     /**
      * True if we have an activity div open, false otherwise
      * @var bool
      */
     protected $activitydiv = false;
+
     /**
      * Creates the form
      *
-     * @param backup_ui_stage $uistage
+     * @param base_ui_stage $uistage
      * @param moodle_url|string $action
      * @param mixed $customdata
      * @param string $method get|post
@@ -71,7 +76,8 @@ abstract class base_moodleform extends moodleform {
      * @param array $attributes
      * @param bool $editable
      */
-    function __construct(base_ui_stage $uistage, $action=null, $customdata=null, $method='post', $target='', $attributes=null, $editable=true) {
+    public function __construct(base_ui_stage $uistage, $action = null, $customdata = null, $method = 'post',
+                                $target = '', $attributes = null, $editable = true) {
         $this->uistage = $uistage;
         // Add a class to the attributes to prevent the default collapsible behaviour.
         if (!$attributes) {
@@ -83,10 +89,11 @@ abstract class base_moodleform extends moodleform {
         }
         parent::__construct($action, $customdata, $method, $target, $attributes, $editable);
     }
+
     /**
      * The standard form definition... obviously not much here
      */
-    function definition() {
+    public function definition() {
         $ui = $this->uistage->get_ui();
         $mform = $this->_form;
         $mform->setDisableShortforms();
@@ -96,7 +103,7 @@ abstract class base_moodleform extends moodleform {
         $mform->setType($ui->get_name(), PARAM_ALPHANUM);
         $params = $this->uistage->get_params();
         if (is_array($params) && count($params) > 0) {
-            foreach ($params as $name=>$value) {
+            foreach ($params as $name => $value) {
                 // TODO: Horrible hack, but current backup ui structure does not allow
                 // to make this easy (only changing params to objects that would be
                 // possible. MDL-38735.
@@ -118,17 +125,22 @@ abstract class base_moodleform extends moodleform {
      * to add elements on the fly.
      * @global moodle_page $PAGE
      */
-    function definition_after_data() {
-        $buttonarray=array();
-        $buttonarray[] = $this->_form->createElement('submit', 'submitbutton', get_string($this->uistage->get_ui()->get_name().'stage'.$this->uistage->get_stage().'action', 'backup'), array('class'=>'proceedbutton'));
+    public function definition_after_data() {
+        $buttonarray = array();
+        $buttonarray[] = $this->_form->createElement(
+            'submit',
+            'submitbutton',
+            get_string($this->uistage->get_ui()->get_name().'stage'.$this->uistage->get_stage().'action', 'backup'),
+            array('class' => 'proceedbutton')
+        );
         if (!$this->uistage->is_first_stage()) {
-            $buttonarray[] = $this->_form->createElement('submit', 'previous', get_string('previousstage','backup'));
+            $buttonarray[] = $this->_form->createElement('submit', 'previous', get_string('previousstage', 'backup'));
         } else if ($this->uistage instanceof backup_ui_stage) {
             // Only display the button on the first stage of backup, they only place where it has an effect.
             $buttonarray[] = $this->_form->createElement('submit', 'oneclickbackup', get_string('jumptofinalstep', 'backup'),
                 array('class' => 'oneclickbackup'));
         }
-        $buttonarray[] = $this->_form->createElement('cancel', 'cancel', get_string('cancel'), array('class'=>'confirmcancel'));
+        $buttonarray[] = $this->_form->createElement('cancel', 'cancel', get_string('cancel'), array('class' => 'confirmcancel'));
         $this->_form->addGroup($buttonarray, 'buttonar', '', array(' '), false);
         $this->_form->closeHeaderBefore('buttonar');
 
@@ -138,7 +150,7 @@ abstract class base_moodleform extends moodleform {
     /**
      * Closes any open divs
      */
-    function close_task_divs() {
+    public function close_task_divs() {
         if ($this->activitydiv) {
             $this->_form->addElement('html', html_writer::end_tag('div'));
             $this->activitydiv = false;
@@ -152,14 +164,17 @@ abstract class base_moodleform extends moodleform {
             $this->coursediv = false;
         }
     }
+
     /**
      * Adds the backup_setting as a element to the form
      * @param backup_setting $setting
+     * @param base_task $task
      * @return bool
      */
-    function add_setting(backup_setting $setting, base_task $task=null) {
+    public function add_setting(backup_setting $setting, base_task $task = null) {
         return $this->add_settings(array(array($setting, $task)));
     }
+
     /**
      * Adds multiple backup_settings as elements to the form
      * @param array $settingstasks Consists of array($setting, $task) elements
@@ -177,10 +192,10 @@ abstract class base_moodleform extends moodleform {
                 continue;
             }
 
-            // First add the formatting for this setting
+            // First add the formatting for this setting.
             $this->add_html_formatting($setting);
 
-            // Then call the add method with the get_element_properties array
+            // Then call the add method with the get_element_properties array.
             call_user_func_array(array($this->_form, 'addElement'), $setting->get_ui()->get_element_properties($task, $OUTPUT));
             $this->_form->setType($setting->get_ui_name(), $setting->get_param_validation());
             $defaults[$setting->get_ui_name()] = $setting->get_value();
@@ -193,14 +208,16 @@ abstract class base_moodleform extends moodleform {
         $this->_form->setDefaults($defaults);
         return true;
     }
+
     /**
      * Adds a heading to the form
      * @param string $name
      * @param string $text
      */
-    function add_heading($name , $text) {
+    public function add_heading($name , $text) {
         $this->_form->addElement('header', $name, $text);
     }
+
     /**
      * Adds HTML formatting for the given backup setting, needed to group/segment
      * correctly.
@@ -208,8 +225,8 @@ abstract class base_moodleform extends moodleform {
      */
     protected function add_html_formatting(backup_setting $setting) {
         $mform = $this->_form;
-        $isincludesetting = (strpos($setting->get_name(), '_include')!==false);
-        if ($isincludesetting && $setting->get_level() != backup_setting::ROOT_LEVEL)  {
+        $isincludesetting = (strpos($setting->get_name(), '_include') !== false);
+        if ($isincludesetting && $setting->get_level() != backup_setting::ROOT_LEVEL) {
             switch ($setting->get_level()) {
                 case backup_setting::COURSE_LEVEL:
                     if ($this->activitydiv) {
@@ -223,8 +240,8 @@ abstract class base_moodleform extends moodleform {
                     if ($this->coursediv) {
                         $this->_form->addElement('html', html_writer::end_tag('div'));
                     }
-                    $mform->addElement('html', html_writer::start_tag('div', array('class'=>'grouped_settings course_level')));
-                    $mform->addElement('html', html_writer::start_tag('div', array('class'=>'include_setting course_level')));
+                    $mform->addElement('html', html_writer::start_tag('div', array('class' => 'grouped_settings course_level')));
+                    $mform->addElement('html', html_writer::start_tag('div', array('class' => 'include_setting course_level')));
                     $this->coursediv = true;
                     break;
                 case backup_setting::SECTION_LEVEL:
@@ -235,46 +252,51 @@ abstract class base_moodleform extends moodleform {
                     if ($this->sectiondiv) {
                         $this->_form->addElement('html', html_writer::end_tag('div'));
                     }
-                    $mform->addElement('html', html_writer::start_tag('div', array('class'=>'grouped_settings section_level')));
-                    $mform->addElement('html', html_writer::start_tag('div', array('class'=>'include_setting section_level')));
+                    $mform->addElement('html', html_writer::start_tag('div', array('class' => 'grouped_settings section_level')));
+                    $mform->addElement('html', html_writer::start_tag('div', array('class' => 'include_setting section_level')));
                     $this->sectiondiv = true;
                     break;
                 case backup_setting::ACTIVITY_LEVEL:
                     if ($this->activitydiv) {
                         $this->_form->addElement('html', html_writer::end_tag('div'));
                     }
-                    $mform->addElement('html', html_writer::start_tag('div', array('class'=>'grouped_settings activity_level')));
-                    $mform->addElement('html', html_writer::start_tag('div', array('class'=>'include_setting activity_level')));
+                    $mform->addElement('html', html_writer::start_tag('div', array('class' => 'grouped_settings activity_level')));
+                    $mform->addElement('html', html_writer::start_tag('div', array('class' => 'include_setting activity_level')));
                     $this->activitydiv = true;
                     break;
                 default:
-                    $mform->addElement('html', html_writer::start_tag('div', array('class'=>'normal_setting')));
+                    $mform->addElement('html', html_writer::start_tag('div', array('class' => 'normal_setting')));
                     break;
             }
         } else if ($setting->get_level() == backup_setting::ROOT_LEVEL) {
-            $mform->addElement('html', html_writer::start_tag('div', array('class'=>'root_setting')));
+            $mform->addElement('html', html_writer::start_tag('div', array('class' => 'root_setting')));
         } else {
-            $mform->addElement('html', html_writer::start_tag('div', array('class'=>'normal_setting')));
+            $mform->addElement('html', html_writer::start_tag('div', array('class' => 'normal_setting')));
         }
     }
+
     /**
      * Adds a fixed or static setting to the form
      * @param backup_setting $setting
+     * @param base_task $task
      */
-    function add_fixed_setting(backup_setting $setting, base_task $task) {
+    public function add_fixed_setting(backup_setting $setting, base_task $task) {
         global $OUTPUT;
         $settingui = $setting->get_ui();
         if ($setting->get_visibility() == backup_setting::VISIBLE) {
             $this->add_html_formatting($setting);
             switch ($setting->get_status()) {
                 case backup_setting::LOCKED_BY_PERMISSION:
-                    $icon = ' '.$OUTPUT->pix_icon('i/permissionlock', get_string('lockedbypermission', 'backup'), 'moodle', array('class'=>'smallicon lockedicon permissionlock'));
+                    $icon = ' '.$OUTPUT->pix_icon('i/permissionlock', get_string('lockedbypermission', 'backup'), 'moodle',
+                            array('class' => 'smallicon lockedicon permissionlock'));
                     break;
                 case backup_setting::LOCKED_BY_CONFIG:
-                    $icon = ' '.$OUTPUT->pix_icon('i/configlock', get_string('lockedbyconfig', 'backup'), 'moodle', array('class'=>'smallicon lockedicon configlock'));
+                    $icon = ' '.$OUTPUT->pix_icon('i/configlock', get_string('lockedbyconfig', 'backup'), 'moodle',
+                            array('class' => 'smallicon lockedicon configlock'));
                     break;
                 case backup_setting::LOCKED_BY_HIERARCHY:
-                    $icon = ' '.$OUTPUT->pix_icon('i/hierarchylock', get_string('lockedbyhierarchy', 'backup'), 'moodle', array('class'=>'smallicon lockedicon configlock'));
+                    $icon = ' '.$OUTPUT->pix_icon('i/hierarchylock', get_string('lockedbyhierarchy', 'backup'), 'moodle',
+                            array('class' => 'smallicon lockedicon configlock'));
                     break;
                 default:
                     $icon = '';
@@ -291,18 +313,20 @@ abstract class base_moodleform extends moodleform {
         $this->_form->addElement('hidden', $settingui->get_name(), $settingui->get_value());
         $this->_form->setType($settingui->get_name(), $settingui->get_param_validation());
     }
+
     /**
      * Adds dependencies to the form recursively
      *
      * @param backup_setting $setting
      */
-    function add_dependencies(backup_setting $setting) {
+    public function add_dependencies(backup_setting $setting) {
         $mform = $this->_form;
-        // Apply all dependencies for backup
-        foreach ($setting->get_my_dependency_properties() as $key=>$dependency) {
+        // Apply all dependencies for backup.
+        foreach ($setting->get_my_dependency_properties() as $key => $dependency) {
             call_user_func_array(array($this->_form, 'disabledIf'), $dependency);
         }
     }
+
     /**
      * Returns true if the form was cancelled, false otherwise
      * @return bool
@@ -352,7 +376,11 @@ abstract class base_moodleform extends moodleform {
         $config->yesLabel = get_string('confirmcancelyes', 'backup');
         $config->noLabel = get_string('confirmcancelno', 'backup');
         $config->closeButtonTitle = get_string('close', 'editor');
-        $PAGE->requires->yui_module('moodle-backup-confirmcancel', 'M.core_backup.confirmcancel.watch_cancel_buttons', array($config));
+        $PAGE->requires->yui_module(
+            'moodle-backup-confirmcancel',
+            'M.core_backup.confirmcancel.watch_cancel_buttons',
+            array($config)
+        );
 
         // Get list of module types on course.
         $modinfo = get_fast_modinfo($COURSE);
index efd74a2..abdd018 100644 (file)
@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -18,7 +17,7 @@
 /**
  * This file contains the backup user interface class
  *
- * @package   moodlecore
+ * @package   core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
  * The backup user interface class manages the user interface and backup for
  * Moodle.
  *
+ * @package   core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 abstract class base_ui {
     /**
      * The progress of this instance of the backup ui class
+     * It is in the initial stage.
      */
     const PROGRESS_INTIAL = 0;
+
+    /**
+     * The progress of this instance of the backup ui class
+     * It is processed.
+     */
     const PROGRESS_PROCESSED = 1;
+
+    /**
+     * The progress of this instance of the backup ui class
+     * It is saved.
+     */
     const PROGRESS_SAVED = 2;
+
+    /**
+     * The progress of this instance of the backup ui class
+     * It has been executed.
+     */
     const PROGRESS_EXECUTED = 3;
+
     /**
      * The controller
      * @var backup_controller|restore_controller
      */
     protected $controller;
+
     /**
      * The current stage
      * @var base_ui_stage
      */
     protected $stage;
+
     /**
      * The current progress of the UI
      * @var int One of self::PROGRESS_*
      */
     protected $progress;
+
     /**
      * The number of changes made by dependency enforcement
      * @var int
@@ -64,14 +84,16 @@ abstract class base_ui {
     /**
      * Yay for constructors
      * @param backup_controller $controller
+     * @param array $params
      */
-    public function __construct($controller, array $params=null) {
+    public function __construct($controller, array $params = null) {
         $this->controller = $controller;
         $this->progress = self::PROGRESS_INTIAL;
         $this->stage = $this->initialise_stage(null, $params);
-        // Process UI event before to be safe
+        // Process UI event before to be safe.
         $this->controller->process_ui_event();
     }
+
     /**
      * Destorys the backup controller and the loaded stage.
      */
@@ -83,16 +105,20 @@ abstract class base_ui {
         unset($this->stage);
 
     }
+
     /**
      * Intialises what ever stage is requested. If none are requested we check
      * params for 'stage' and default to initial
      *
      * @param int|null $stage The desired stage to intialise or null for the default
+     * @param array $params
      * @return base_ui_stage
      */
-    abstract protected function initialise_stage($stage = null, array $params=null);
+    abstract protected function initialise_stage($stage = null, array $params = null);
+
     /**
      * This processes the current stage of the backup
+     * @throws backup_ui_exception
      * @return bool
      */
     public function process() {
@@ -106,22 +132,24 @@ abstract class base_ui {
             return false;
         }
 
-        // Process the stage
+        // Process the stage.
         $processoutcome = $this->stage->process();
 
         if ($processoutcome !== false) {
             $this->stage = $this->initialise_stage($this->stage->get_next_stage(), $this->stage->get_params());
         }
 
-        // Process UI event after to check changes are valid
+        // Process UI event after to check changes are valid.
         $this->controller->process_ui_event();
         return $processoutcome;
     }
+
     /**
      * Saves the backup controller.
      *
      * Once this has been called nothing else can be changed in the controller.
      *
+     * @throws base_ui_exception
      * @return bool
      */
     public function save_controller() {
@@ -129,17 +157,19 @@ abstract class base_ui {
             throw new base_ui_exception('backupuialreadysaved');
         }
         $this->progress = self::PROGRESS_SAVED;
-        // First enforce dependencies
+        // First enforce dependencies.
         $this->enforce_dependencies();
-        // Process UI event after to check any changes are valid
+        // Process UI event after to check any changes are valid.
         $this->controller->process_ui_event();
-        // Save the controller
+        // Save the controller.
         $this->controller->save_controller();
         return true;
     }
+
     /**
      * Displays the UI for the backup!
      *
+     * @throws base_ui_exception
      * @param core_backup_renderer $renderer
      * @return string HTML code to echo
      */
@@ -149,6 +179,7 @@ abstract class base_ui {
         }
         return $this->stage->display($renderer);
     }
+
     /**
      * Gets all backup tasks from the controller
      * @return array Array of backup_task
@@ -158,6 +189,7 @@ abstract class base_ui {
         $tasks = $plan->get_tasks();
         return $tasks;
     }
+
     /**
      * Gets the stage we are on
      * @return int
@@ -165,6 +197,7 @@ abstract class base_ui {
     public function get_stage() {
         return $this->stage->get_stage();
     }
+
     /**
      * Gets the name of the stage we are on
      * @return string
@@ -172,44 +205,48 @@ abstract class base_ui {
     public function get_stage_name() {
         return $this->stage->get_name();
     }
+
     /**
      * Gets the backup id from the controller
      * @return string
      */
     abstract public function get_uniqueid();
+
     /**
      * Executes the backup plan
      * @return bool
      */
     abstract public function execute();
+
     /**
      * Enforces dependencies on all settings. Call before save
      * @return bool True if dependencies were enforced and changes were made
      */
     protected function enforce_dependencies() {
-        // Get the plan
+        // Get the plan.
         $plan = $this->controller->get_plan();
-        // Get the tasks as a var so we can iterate by reference
+        // Get the tasks as a var so we can iterate by reference.
         $tasks = $plan->get_tasks();
         $changes = 0;
         foreach ($tasks as &$task) {
-            // Store as a var so we can iterate by reference
+            // Store as a var so we can iterate by reference.
             $settings = $task->get_settings();
             foreach ($settings as &$setting) {
-                // Get all dependencies for iteration by reference
+                // Get all dependencies for iteration by reference.
                 $dependencies = $setting->get_dependencies();
                 foreach ($dependencies as &$dependency) {
-                    // Enforce each dependency
+                    // Enforce each dependency.
                     if ($dependency->enforce()) {
                         $changes++;
                     }
                 }
             }
         }
-        // Store the number of settings that changed through enforcement
+        // Store the number of settings that changed through enforcement.
         $this->dependencychanges = $changes;
-        return ($changes>0);
+        return ($changes > 0);
     }
+
     /**
      * Returns true if enforce_dependencies changed any settings
      * @return bool
@@ -217,11 +254,14 @@ abstract class base_ui {
     public function enforce_changed_dependencies() {
         return ($this->dependencychanges > 0);
     }
+
     /**
      * Loads the backup controller if we are tracking one
+     * @throws coding_exception
+     * @param string|bool $uniqueid
      * @return backup_controller|false
      */
-    public static function load_controller($uniqueid=false) {
+    public static function load_controller($uniqueid = false) {
         throw new coding_exception('load_controller() method needs to be overridden in each subclass of base_ui');
     }
 
@@ -230,11 +270,11 @@ abstract class base_ui {
      */
     public function cancel_process() {
         global $PAGE;
-        // Determine the appropriate URL to redirect the user to
+        // Determine the appropriate URL to redirect the user to.
         if ($PAGE->context->contextlevel == CONTEXT_MODULE && $PAGE->cm !== null) {
-            $relevanturl = new moodle_url('/mod/'.$PAGE->cm->modname.'/view.php', array('id'=>$PAGE->cm->id));
+            $relevanturl = new moodle_url('/mod/'.$PAGE->cm->modname.'/view.php', array('id' => $PAGE->cm->id));
         } else {
-            $relevanturl = new moodle_url('/course/view.php', array('id'=>$PAGE->course->id));
+            $relevanturl = new moodle_url('/course/view.php', array('id' => $PAGE->course->id));
         }
         redirect($relevanturl);
     }
@@ -258,6 +298,11 @@ abstract class base_ui {
     public function get_type() {
         return $this->controller->get_type();
     }
+
+    /**
+     * Returns the controller object.
+     * @return backup_controller|restore_controller
+     */
     public function get_controller() {
         return $this->controller;
     }
@@ -271,6 +316,7 @@ abstract class base_ui {
     /**
      * Gets the requested setting
      * @param string $name
+     * @param bool $default
      * @return mixed
      */
     public function get_setting($name, $default = false) {
@@ -285,6 +331,7 @@ abstract class base_ui {
      * Gets the value for the requested setting
      *
      * @param string $name
+     * @param bool $default
      * @return mixed
      */
     public function get_setting_value($name, $default = false) {
@@ -296,12 +343,24 @@ abstract class base_ui {
         }
     }
 
+    /**
+     * Returns the name of this stage.
+     * @return mixed
+     */
     abstract public function get_name();
 
+    /**
+     * Returns the first stage ID.
+     * @return mixed
+     */
     abstract public function get_first_stage_id();
 }
 
 /**
  * Backup user interface exception. Modelled off the backup_exception class
+ *
+ * @package   core_backup
+ * @copyright 2010 Sam Hemelryk
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class base_ui_exception extends backup_exception {}
index 85f99a2..6cd368a 100644 (file)
@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -20,9 +19,9 @@
  *
  * This file contains the classes required to manage the stages that make up the
  * backup user interface.
- * These will be primarily operated a {@see backup_ui} instance.
+ * These will be primarily operated a {@link base_ui} instance.
  *
- * @package   moodlecore
+ * @package   core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
  *  - process : To process the stage
  *  - initialise_stage_form : To get a backup_moodleform instance for the stage
  *
+ * @package   core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 abstract class base_ui_stage {
+
     /**
      * The current stage
      * @var int
      */
     protected $stage = 1;
+
     /**
      * The backuck UI object
      * @var base_ui
      */
     protected $ui;
+
     /**
      * The moodleform for this stage
      * @var base_moodleform
      */
     protected $stageform = null;
+
     /**
      * Custom form params that will be added as hidden inputs
+     * @var array
      */
     protected $params = null;
+
     /**
+     * Constructor
      *
      * @param base_ui $ui
+     * @param array $params
      */
-    public function __construct(base_ui $ui, array $params=null) {
+    public function __construct(base_ui $ui, array $params = null) {
         $this->ui = $ui;
         $this->params = $params;
     }
+
     /**
      * Returns the custom params for this stage
      * @return array|null
@@ -73,6 +82,7 @@ abstract class base_ui_stage {
     final public function get_params() {
         return $this->params;
     }
+
     /**
      * The current stage
      * @return int
@@ -80,27 +90,31 @@ abstract class base_ui_stage {
     final public function get_stage() {
         return $this->stage;
     }
+
     /**
      * The next stage
      * @return int
      */
     public function get_next_stage() {
-        return floor($this->stage*2);
+        return floor($this->stage * 2);
     }
+
     /**
      * The previous stage
      * @return int
      */
     final public function get_prev_stage() {
-        return floor($this->stage/2);
+        return floor($this->stage / 2);
     }
+
     /**
      * The name of this stage
      * @return string
      */
     public function get_name() {
-        return get_string('currentstage'.$this->stage,'backup');
+        return get_string('currentstage' . $this->stage, 'backup');
     }
+
     /**
      * The backup id from the backup controller
      * @return string
@@ -121,8 +135,8 @@ abstract class base_ui_stage {
     public function display(core_backup_renderer $renderer) {
 
         $form = $this->initialise_stage_form();
-        // a nasty hack follows to work around the sad fact that moodle quickforms
-        // do not allow to actually return the HTML content, just to echo it
+        // A nasty hack follows to work around the sad fact that moodle quickforms
+        // do not allow to actually return the HTML content, just to echo it.
         flush();
         ob_start();
         $form->display();
@@ -138,9 +152,10 @@ abstract class base_ui_stage {
      * This must be overridden by every stage as it will be different for every stage
      *
      * @abstract
-     * @param backup_moodleform|null $form
+     * @param base_moodleform $form
      */
-    abstract public function process(base_moodleform $form=null);
+    abstract public function process(base_moodleform $form = null);
+
     /**
      * Creates an instance of the correct moodleform properly populated and all
      * dependencies instantiated
@@ -150,10 +165,18 @@ abstract class base_ui_stage {
      */
     abstract protected function initialise_stage_form();
 
+    /**
+     * Returns the base UI class
+     * @return base_ui
+     */
     final public function get_ui() {
         return $this->ui;
     }
 
+    /**
+     * Returns true if this stage is the first stage.
+     * @return bool
+     */
     public function is_first_stage() {
         return $this->stage == 1;
     }
index 7edcc2e..18384c6 100644 (file)
@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
  * and functionality in order to customise the backup UI for the purposes of
  * import.
  *
- * @package   moodlecore
+ * @package   core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 /**
  * Import UI class
+ *
+ * @package   core_backup
+ * @copyright 2010 Sam Hemelryk
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class import_ui extends backup_ui {
+
     /**
      * Customises the backup progress bar
      *
      * @global moodle_page $PAGE
-     * @return array
+     * @return array[] An array of arrays
      */
     public function get_progress_bar() {
         global $PAGE;
@@ -42,19 +46,25 @@ class import_ui extends backup_ui {
         $items = array();
         while ($stage > 0) {
             $classes = array('backup_stage');
-            if (floor($stage/2) == $currentstage) {
+            if (floor($stage / 2) == $currentstage) {
                 $classes[] = 'backup_stage_next';
             } else if ($stage == $currentstage) {
                 $classes[] = 'backup_stage_current';
             } else if ($stage < $currentstage) {
                 $classes[] = 'backup_stage_complete';
             }
-            $item = array('text' => strlen(decbin($stage*2)).'. '.get_string('importcurrentstage'.$stage, 'backup'),'class' => join(' ', $classes));
-            if ($stage < $currentstage && $currentstage < self::STAGE_COMPLETE && (!self::$skipcurrentstage || $stage*2 != $currentstage)) {
-                $item['link'] = new moodle_url($PAGE->url, $this->stage->get_params() + array('backup'=>$this->get_backupid(), 'stage'=>$stage));
+            $item = array(
+                'text' => strlen(decbin($stage * 2)).'. '.get_string('importcurrentstage'.$stage, 'backup'),
+                'class' => join(' ', $classes)
+            );
+            if ($stage < $currentstage && $currentstage < self::STAGE_COMPLETE && (!self::$skipcurrentstage || $stage * 2 != $currentstage)) {
+                $item['link'] = new moodle_url(
+                    $PAGE->url,
+                    $this->stage->get_params() + array('backup' => $this->get_backupid(), 'stage' => $stage)
+                );
             }
             array_unshift($items, $item);
-            $stage = floor($stage/2);
+            $stage = floor($stage / 2);
         }
         $selectorlink = new moodle_url($PAGE->url, $this->stage->get_params());
         $selectorlink->remove_params('importid');
@@ -70,9 +80,10 @@ class import_ui extends backup_ui {
      * params for 'stage' and default to initial
      *
      * @param int|null $stage The desired stage to intialise or null for the default
+     * @param array $params
      * @return backup_ui_stage_initial|backup_ui_stage_schema|backup_ui_stage_confirmation|backup_ui_stage_final
      */
-    protected function initialise_stage($stage = null, array $params=null) {
+    protected function initialise_stage($stage = null, array $params = null) {
         if ($stage == null) {
             $stage = optional_param('stage', self::STAGE_INITIAL, PARAM_INT);
         }
@@ -102,11 +113,19 @@ class import_ui extends backup_ui {
 
 /**
  * Extends the initial stage
+ *
+ * @package   core_backup
+ * @copyright 2010 Sam Hemelryk
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class import_ui_stage_inital extends backup_ui_stage_initial {}
 
 /**
  * Extends the schema stage
+ *
+ * @package   core_backup
+ * @copyright 2010 Sam Hemelryk
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class import_ui_stage_schema extends backup_ui_stage_schema {}
 
@@ -115,6 +134,10 @@ class import_ui_stage_schema extends backup_ui_stage_schema {}
  *
  * This overides the initialise stage form to remove the filenamesetting heading
  * as it is always hidden.
+ *
+ * @package   core_backup
+ * @copyright 2010 Sam Hemelryk
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class import_ui_stage_confirmation extends backup_ui_stage_confirmation {
 
@@ -145,14 +168,16 @@ class import_ui_stage_confirmation extends backup_ui_stage_confirmation {
         } else {
             $elements = $form->get_element('buttonar')->getElements();
             foreach ($elements as &$element) {
-                if ($element->getName()=='submitbutton') {
-                    $element->setValue(get_string('import'.$this->get_ui()->get_name().'stage'.$this->get_stage().'action', 'backup'));
+                if ($element->getName() == 'submitbutton') {
+                    $element->setValue(
+                        get_string('import'.$this->get_ui()->get_name().'stage'.$this->get_stage().'action', 'backup')
+                    );
                 }
             }
         }
 
-        // a nasty hack follows to work around the sad fact that moodle quickforms
-        // do not allow to actually return the HTML content, just to echo it
+        // A nasty hack follows to work around the sad fact that moodle quickforms
+        // do not allow to actually return the HTML content, just to echo it.
         flush();
         ob_start();
         $form->display();
@@ -164,11 +189,19 @@ class import_ui_stage_confirmation extends backup_ui_stage_confirmation {
 }
 /**
  * Overrides the final stage.
+ *
+ * @package   core_backup
+ * @copyright 2010 Sam Hemelryk
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class import_ui_stage_final extends backup_ui_stage_final {}
 
 /**
  * Extends the restore course search to search for import courses.
+ *
+ * @package   core_backup
+ * @copyright 2010 Sam Hemelryk
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class import_course_search extends restore_course_search {
     /**
index e705270..5a2a70f 100644 (file)
@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -18,7 +17,7 @@
 /**
  * This file contains backup and restore output renderers
  *
- * @package   moodlecore
+ * @package   core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
  *
  * Can be retrieved with the following code:
  * <?php
- * $renderer = $PAGE->get_renderer('core','backup');
+ * $renderer = $PAGE->get_renderer('core', 'backup');
  * ?>
  *
+ * @package   core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class core_backup_renderer extends plugin_renderer_base {
+
     /**
-     * Renderers a progress bar for the backup or restore given the items that
-     * make it up.
+     * Renderers a progress bar for the backup or restore given the items that make it up.
+     *
      * @param array $items An array of items
      * @return string
      */
@@ -53,7 +54,7 @@ class core_backup_renderer extends plugin_renderer_base {
                 $item = html_writer::tag('span', $text, $item);
             }
         }
-        return html_writer::tag('div', join(get_separator(), $items), array('class'=>'backup_progress clearfix'));
+        return html_writer::tag('div', join(get_separator(), $items), array('class' => 'backup_progress clearfix'));
     }
 
     /**
@@ -75,11 +76,12 @@ class core_backup_renderer extends plugin_renderer_base {
 
     /**
      * Prints a dependency notification
+     *
      * @param string $message
      * @return string
      */
     public function dependency_notification($message) {
-        return html_writer::tag('div', $message, array('class'=>'notification dependencies_enforced'));
+        return html_writer::tag('div', $message, array('class' => 'notification dependencies_enforced'));
     }
 
     /**
@@ -93,23 +95,23 @@ class core_backup_renderer extends plugin_renderer_base {
         $yestick = $this->output->pix_icon('i/valid', get_string('yes'));
         $notick = $this->output->pix_icon('i/invalid', get_string('no'));
 
-        $html  = html_writer::start_tag('div', array('class'=>'backup-restore'));
+        $html  = html_writer::start_tag('div', array('class' => 'backup-restore'));
 
-        $html .= html_writer::start_tag('div', array('class'=>'backup-section'));
-        $html .= $this->output->heading(get_string('backupdetails', 'backup'), 2, array('class'=>'header'));
+        $html .= html_writer::start_tag('div', array('class' => 'backup-section'));
+        $html .= $this->output->heading(get_string('backupdetails', 'backup'), 2, array('class' => 'header'));
         $html .= $this->backup_detail_pair(get_string('backuptype', 'backup'), get_string('backuptype'.$details->type, 'backup'));
         $html .= $this->backup_detail_pair(get_string('backupformat', 'backup'), get_string('backupformat'.$details->format, 'backup'));
         $html .= $this->backup_detail_pair(get_string('backupmode', 'backup'), get_string('backupmode'.$details->mode, 'backup'));
         $html .= $this->backup_detail_pair(get_string('backupdate', 'backup'), userdate($details->backup_date));
         $html .= $this->backup_detail_pair(get_string('moodleversion', 'backup'),
-                html_writer::tag('span', $details->moodle_release, array('class'=>'moodle_release')).
-                html_writer::tag('span', '['.$details->moodle_version.']', array('class'=>'moodle_version sub-detail')));
+                html_writer::tag('span', $details->moodle_release, array('class' => 'moodle_release')).
+                html_writer::tag('span', '['.$details->moodle_version.']', array('class' => 'moodle_version sub-detail')));
         $html .= $this->backup_detail_pair(get_string('backupversion', 'backup'),
-                html_writer::tag('span', $details->backup_release, array('class'=>'moodle_release')).
-                html_writer::tag('span', '['.$details->backup_version.']', array('class'=>'moodle_version sub-detail')));
+                html_writer::tag('span', $details->backup_release, array('class' => 'moodle_release')).
+                html_writer::tag('span', '['.$details->backup_version.']', array('class' => 'moodle_version sub-detail')));
         $html .= $this->backup_detail_pair(get_string('originalwwwroot', 'backup'),
-                html_writer::tag('span', $details->original_wwwroot, array('class'=>'originalwwwroot')).
-                html_writer::tag('span', '['.$details->original_site_identifier_hash.']', array('class'=>'sitehash sub-detail')));
+                html_writer::tag('span', $details->original_wwwroot, array('class' => 'originalwwwroot')).
+                html_writer::tag('span', '['.$details->original_site_identifier_hash.']', array('class' => 'sitehash sub-detail')));
         if (!empty($details->include_file_references_to_external_content)) {
             $message = '';
             if (backup_general_helper::backup_is_samesite($details)) {
@@ -122,46 +124,46 @@ class core_backup_renderer extends plugin_renderer_base {
 
         $html .= html_writer::end_tag('div');
 
-        $html .= html_writer::start_tag('div', array('class'=>'backup-section settings-section'));
-        $html .= $this->output->heading(get_string('backupsettings', 'backup'), 2, array('class'=>'header'));
-        foreach ($details->root_settings as $label=>$value) {
+        $html .= html_writer::start_tag('div', array('class' => 'backup-section settings-section'));
+        $html .= $this->output->heading(get_string('backupsettings', 'backup'), 2, array('class' => 'header'));
+        foreach ($details->root_settings as $label => $value) {
             if ($label == 'filename' or $label == 'user_files') {
                 continue;
             }
-            $html .= $this->backup_detail_pair(get_string('rootsetting'.str_replace('_','',$label), 'backup'), $value?$yestick:$notick);
+            $html .= $this->backup_detail_pair(get_string('rootsetting'.str_replace('_', '', $label), 'backup'), $value ? $yestick : $notick);
         }
         $html .= html_writer::end_tag('div');
 
         if ($details->type === 'course') {
-            $html .= html_writer::start_tag('div', array('class'=>'backup-section'));
-            $html .= $this->output->heading(get_string('backupcoursedetails', 'backup'), 2, array('class'=>'header'));
+            $html .= html_writer::start_tag('div', array('class' => 'backup-section'));
+            $html .= $this->output->heading(get_string('backupcoursedetails', 'backup'), 2, array('class' => 'header'));
             $html .= $this->backup_detail_pair(get_string('coursetitle', 'backup'), $details->course->title);
             $html .= $this->backup_detail_pair(get_string('courseid', 'backup'), $details->course->courseid);
 
-            $html .= html_writer::start_tag('div', array('class'=>'backup-sub-section'));
-            $html .= $this->output->heading(get_string('backupcoursesections', 'backup'), 3, array('class'=>'subheader'));
-            foreach ($details->sections as $key=>$section) {
+            $html .= html_writer::start_tag('div', array('class' => 'backup-sub-section'));
+            $html .= $this->output->heading(get_string('backupcoursesections', 'backup'), 3, array('class' => 'subheader'));
+            foreach ($details->sections as $key => $section) {
                 $included = $key.'_included';
                 $userinfo = $key.'_userinfo';
                 if ($section->settings[$included] && $section->settings[$userinfo]) {
-                    $value = get_string('sectionincanduser','backup');
+                    $value = get_string('sectionincanduser', 'backup');
                 } else if ($section->settings[$included]) {
-                    $value = get_string('sectioninc','backup');
+                    $value = get_string('sectioninc', 'backup');
                 } else {
                     continue;
                 }
                 $html .= $this->backup_detail_pair(get_string('backupcoursesection', 'backup', $section->title), $value);
                 $table = null;
-                foreach ($details->activities as $activitykey=>$activity) {
+                foreach ($details->activities as $activitykey => $activity) {
                     if ($activity->sectionid != $section->sectionid) {
                         continue;
                     }
                     if (empty($table)) {
                         $table = new html_table();
-                        $table->head = array(get_string('module','backup'), get_string('title','backup'), get_string('userinfo','backup'));
+                        $table->head = array(get_string('module', 'backup'), get_string('title', 'backup'), get_string('userinfo', 'backup'));
                         $table->colclasses = array('modulename', 'moduletitle', 'userinfoincluded');
-                        $table->align = array('left','left', 'center');
-                        $table->attributes = array('class'=>'activitytable generaltable');
+                        $table->align = array('left', 'left', 'center');
+                        $table->attributes = array('class' => 'activitytable generaltable');
                         $table->data = array();
                     }
                     $name = get_string('pluginname', $activity->modulename);
@@ -169,11 +171,11 @@ class core_backup_renderer extends plugin_renderer_base {
                     $table->data[] = array(
                         $this->output->render($icon).$name,
                         $activity->title,
-                        ($activity->settings[$activitykey.'_userinfo'])?$yestick:$notick,
+                        ($activity->settings[$activitykey.'_userinfo']) ? $yestick : $notick,
                     );
                 }
                 if (!empty($table)) {
-                    $html .= $this->backup_detail_pair(get_string('sectionactivities','backup'), html_writer::table($table));
+                    $html .= $this->backup_detail_pair(get_string('sectionactivities', 'backup'), html_writer::table($table));
                 }
 
             }
@@ -240,7 +242,8 @@ class core_backup_renderer extends plugin_renderer_base {
      * @param int $currentcourse
      * @return string
      */
-    public function course_selector(moodle_url $nextstageurl, $wholecourse = true, restore_category_search $categories = null, restore_course_search $courses=null, $currentcourse = null) {
+    public function course_selector(moodle_url $nextstageurl, $wholecourse = true, restore_category_search $categories = null,
+                                    restore_course_search $courses = null, $currentcourse = null) {
         global $CFG, $PAGE;
         require_once($CFG->dirroot.'/course/lib.php');
 
@@ -258,20 +261,21 @@ class core_backup_renderer extends plugin_renderer_base {
 
         $form = html_writer::start_tag('form', array('method' => 'post', 'action' => $nextstageurl->out_omit_querystring(),
             'class' => 'mform'));
-        foreach ($nextstageurl->params() as $key=>$value) {
-            $form .= html_writer::empty_tag('input', array('type'=>'hidden', 'name'=>$key, 'value'=>$value));
+        foreach ($nextstageurl->params() as $key => $value) {
+            $form .= html_writer::empty_tag('input', array('type' => 'hidden', 'name' => $key, 'value' => $value));
         }
 
         $hasrestoreoption = false;
 
-        $html  = html_writer::start_tag('div', array('class'=>'backup-course-selector backup-restore'));
+        $html  = html_writer::start_tag('div', array('class' => 'backup-course-selector backup-restore'));
         if ($wholecourse && !empty($categories) && ($categories->get_count() > 0 || $categories->get_search())) {
-            // New course
+            // New course.
             $hasrestoreoption = true;
             $html .= $form;
-            $html .= html_writer::start_tag('div', array('class'=>'bcs-new-course backup-section'));
-            $html .= $this->output->heading(get_string('restoretonewcourse', 'backup'), 2, array('class'=>'header'));
-            $html .= $this->backup_detail_input(get_string('restoretonewcourse', 'backup'), 'radio', 'target', backup::TARGET_NEW_COURSE, array('checked'=>'checked'));
+            $html .= html_writer::start_tag('div', array('class' => 'bcs-new-course backup-section'));
+            $html .= $this->output->heading(get_string('restoretonewcourse', 'backup'), 2, array('class' => 'header'));
+            $html .= $this->backup_detail_input(get_string('restoretonewcourse', 'backup'), 'radio', 'target',
+                backup::TARGET_NEW_COURSE, array('checked' => 'checked'));
             $selectacategoryhtml = $this->backup_detail_pair(get_string('selectacategory', 'backup'), $this->render($categories));
             // Display the category selection as required if the form was submitted but this data was not supplied.
             if ($missingdata && $target == backup::TARGET_NEW_COURSE) {
@@ -282,37 +286,41 @@ class core_backup_renderer extends plugin_renderer_base {
             } else {
                 $html .= $selectacategoryhtml;
             }
-            $html .= $this->backup_detail_pair('', html_writer::empty_tag('input', array('type'=>'submit', 'value'=>get_string('continue'))));
+            $html .= $this->backup_detail_pair('', html_writer::empty_tag('input', array('type' => 'submit', 'value' => get_string('continue'))));
             $html .= html_writer::end_tag('div');
             $html .= html_writer::end_tag('form');
         }
 
         if ($wholecourse && !empty($currentcourse)) {
-            // Current course
+            // Current course.
             $hasrestoreoption = true;
             $html .= $form;
-            $html .= html_writer::empty_tag('input', array('type'=>'hidden', 'name'=>'targetid', 'value'=>$currentcourse));
-            $html .= html_writer::start_tag('div', array('class'=>'bcs-current-course backup-section'));
-            $html .= $this->output->heading(get_string('restoretocurrentcourse', 'backup'), 2, array('class'=>'header'));
-            $html .= $this->backup_detail_input(get_string('restoretocurrentcourseadding', 'backup'), 'radio', 'target', backup::TARGET_CURRENT_ADDING, array('checked'=>'checked'));
-            $html .= $this->backup_detail_input(get_string('restoretocurrentcoursedeleting', 'backup'), 'radio', 'target', backup::TARGET_CURRENT_DELETING);
-            $html .= $this->backup_detail_pair('', html_writer::empty_tag('input', array('type'=>'submit', 'value'=>get_string('continue'))));
+            $html .= html_writer::empty_tag('input', array('type' => 'hidden', 'name' => 'targetid', 'value' => $currentcourse));
+            $html .= html_writer::start_tag('div', array('class' => 'bcs-current-course backup-section'));
+            $html .= $this->output->heading(get_string('restoretocurrentcourse', 'backup'), 2, array('class' => 'header'));
+            $html .= $this->backup_detail_input(get_string('restoretocurrentcourseadding', 'backup'), 'radio', 'target',
+                backup::TARGET_CURRENT_ADDING, array('checked' => 'checked'));
+            $html .= $this->backup_detail_input(get_string('restoretocurrentcoursedeleting', 'backup'), 'radio', 'target',
+                backup::TARGET_CURRENT_DELETING);
+            $html .= $this->backup_detail_pair('', html_writer::empty_tag('input', array('type' => 'submit', 'value' => get_string('continue'))));
             $html .= html_writer::end_tag('div');
             $html .= html_writer::end_tag('form');
         }
 
         if (!empty($courses) && ($courses->get_count() > 0 || $courses->get_search())) {
-            // Existing course
+            // Existing course.
             $hasrestoreoption = true;
             $html .= $form;
-            $html .= html_writer::start_tag('div', array('class'=>'bcs-existing-course backup-section'));
-            $html .= $this->output->heading(get_string('restoretoexistingcourse', 'backup'), 2, array('class'=>'header'));
+            $html .= html_writer::start_tag('div', array('class' => 'bcs-existing-course backup-section'));
+            $html .= $this->output->heading(get_string('restoretoexistingcourse', 'backup'), 2, array('class' => 'header'));
             if ($wholecourse) {
-                $html .= $this->backup_detail_input(get_string('restoretoexistingcourseadding', 'backup'), 'radio', 'target', backup::TARGET_EXISTING_ADDING, array('checked'=>'checked'));
-                $html .= $this->backup_detail_input(get_string('restoretoexistingcoursedeleting', 'backup'), 'radio', 'target', backup::TARGET_EXISTING_DELETING);
+                $html .= $this->backup_detail_input(get_string('restoretoexistingcourseadding', 'backup'), 'radio', 'target',
+                    backup::TARGET_EXISTING_ADDING, array('checked' => 'checked'));
+                $html .= $this->backup_detail_input(get_string('restoretoexistingcoursedeleting', 'backup'), 'radio', 'target',
+                    backup::TARGET_EXISTING_DELETING);
             } else {
                 // We only allow restore adding to existing for now. Enforce it here.
-                $html .= html_writer::empty_tag('input', array('type'=>'hidden', 'name'=>'target', 'value'=>backup::TARGET_EXISTING_ADDING));
+                $html .= html_writer::empty_tag('input', array('type' => 'hidden', 'name' => 'target', 'value' => backup::TARGET_EXISTING_ADDING));
                 $courses->invalidate_results(); // Clean list of courses
                 $courses->set_include_currentcourse(); // Show current course in the list
             }
@@ -326,13 +334,13 @@ class core_backup_renderer extends plugin_renderer_base {
             } else {
                 $html .= $selectacoursehtml;
             }
-            $html .= $this->backup_detail_pair('', html_writer::empty_tag('input', array('type'=>'submit', 'value'=>get_string('continue'))));
+            $html .= $this->backup_detail_pair('', html_writer::empty_tag('input', array('type' => 'submit', 'value' => get_string('continue'))));
             $html .= html_writer::end_tag('div');
             $html .= html_writer::end_tag('form');
         }
 
         if (!$hasrestoreoption) {
-            echo $this->output->notification(get_string('norestoreoptions','backup'));
+            echo $this->output->notification(get_string('norestoreoptions', 'backup'));
         }
 
         $html .= html_writer::end_tag('div');
@@ -346,18 +354,18 @@ class core_backup_renderer extends plugin_renderer_base {
      * @param import_course_search $courses
      * @return string
      */
-    public function import_course_selector(moodle_url $nextstageurl, import_course_search $courses=null) {
-        $html  = html_writer::start_tag('div', array('class'=>'import-course-selector backup-restore'));
-        $html .= html_writer::start_tag('form', array('method'=>'post', 'action'=>$nextstageurl->out_omit_querystring()));
-        foreach ($nextstageurl->params() as $key=>$value) {
-            $html .= html_writer::empty_tag('input', array('type'=>'hidden', 'name'=>$key, 'value'=>$value));
+    public function import_course_selector(moodle_url $nextstageurl, import_course_search $courses = null) {
+        $html  = html_writer::start_tag('div', array('class' => 'import-course-selector backup-restore'));
+        $html .= html_writer::start_tag('form', array('method' => 'post', 'action' => $nextstageurl->out_omit_querystring()));
+        foreach ($nextstageurl->params() as $key => $value) {
+            $html .= html_writer::empty_tag('input', array('type' => 'hidden', 'name' => $key, 'value' => $value));
         }
         // We only allow import adding for now. Enforce it here.
-        $html .= html_writer::empty_tag('input', array('type'=>'hidden', 'name'=>'target', 'value'=>backup::TARGET_CURRENT_ADDING));
-        $html .= html_writer::start_tag('div', array('class'=>'ics-existing-course backup-section'));
-        $html .= $this->output->heading(get_string('importdatafrom'), 2, array('class'=>'header'));
+        $html .= html_writer::empty_tag('input', array('type' => 'hidden', 'name' => 'target', 'value' => backup::TARGET_CURRENT_ADDING));
+        $html .= html_writer::start_tag('div', array('class' => 'ics-existing-course backup-section'));
+        $html .= $this->output->heading(get_string('importdatafrom'), 2, array('class' => 'header'));
         $html .= $this->backup_detail_pair(get_string('selectacourse', 'backup'), $this->render($courses));
-        $html .= $this->backup_detail_pair('', html_writer::empty_tag('input', array('type'=>'submit', 'value'=>get_string('continue'))));
+        $html .= $this->backup_detail_pair('', html_writer::empty_tag('input', array('type' => 'submit', 'value' => get_string('continue'))));
         $html .= html_writer::end_tag('div');
         $html .= html_writer::end_tag('form');
         $html .= html_writer::end_tag('div');
@@ -373,11 +381,11 @@ class core_backup_renderer extends plugin_renderer_base {
      * @return string
      */
     protected function backup_detail_pair($label, $value) {
-        static $count= 0;
-        $count++;
-        $html  = html_writer::start_tag('div', array('class'=>'detail-pair'));
-        $html .= html_writer::tag('label', $label, array('class'=>'detail-pair-label', 'for'=>'detail-pair-value-'.$count));
-        $html .= html_writer::tag('div', $value, array('class'=>'detail-pair-value', 'name'=>'detail-pair-value-'.$count));
+        static $count = 0;
+        $count ++;
+        $html  = html_writer::start_tag('div', array('class' => 'detail-pair'));
+        $html .= html_writer::tag('label', $label, array('class' => 'detail-pair-label', 'for' => 'detail-pair-value-'.$count));
+        $html .= html_writer::tag('div', $value, array('class' => 'detail-pair-value', 'name' => 'detail-pair-value-'.$count));
         $html .= html_writer::end_tag('div');
         return $html;
     }
@@ -393,13 +401,16 @@ class core_backup_renderer extends plugin_renderer_base {
      * @param string|null $description
      * @return string
      */
-    protected function backup_detail_input($label, $type, $name, $value, array $attributes=array(), $description=null) {
-        if (!empty ($description)) {
-            $description = html_writer::tag('span', $description, array('class'=>'description'));
+    protected function backup_detail_input($label, $type, $name, $value, array $attributes = array(), $description = null) {
+        if (!empty($description)) {
+            $description = html_writer::tag('span', $description, array('class' => 'description'));
         } else {
             $description = '';
         }
-        return $this->backup_detail_pair($label, html_writer::empty_tag('input', $attributes+array('name'=>$name, 'type'=>$type, 'value'=>$value)).$description);
+        return $this->backup_detail_pair(
+            $label,
+            html_writer::empty_tag('input', $attributes + array('name' => $name, 'type' => $type, 'value' => $value)) . $description
+        );
     }
 
     /**
@@ -414,9 +425,9 @@ class core_backup_renderer extends plugin_renderer_base {
      * @param string|null $description
      * @return string
      */
-    protected function backup_detail_select($label, $name, $options, $selected='', $nothing=false, array $attributes=array(), $description=null) {
+    protected function backup_detail_select($label, $name, $options, $selected = '', $nothing = false, array $attributes = array(), $description = null) {
         if (!empty ($description)) {
-            $description = html_writer::tag('span', $description, array('class'=>'description'));
+            $description = html_writer::tag('span', $description, array('class' => 'description'));
         } else {
             $description = '';
         }
@@ -430,7 +441,7 @@ class core_backup_renderer extends plugin_renderer_base {
      * @return string
      */
     public function precheck_notices($results) {
-        $output = html_writer::start_tag('div', array('class'=>'restore-precheck-notices'));
+        $output = html_writer::start_tag('div', array('class' => 'restore-precheck-notices'));
         if (array_key_exists('errors', $results)) {
             foreach ($results['errors'] as $error) {
                 $output .= $this->output->notification($error);
@@ -453,9 +464,9 @@ class core_backup_renderer extends plugin_renderer_base {
     public function substage_buttons($haserrors) {
         $output  = html_writer::start_tag('div', array('continuebutton'));
         if (!$haserrors) {
-            $output .= html_writer::empty_tag('input', array('type'=>'submit', 'value'=>get_string('continue')));
+            $output .= html_writer::empty_tag('input', array('type' => 'submit', 'value' => get_string('continue')));
         }
-        $output .= html_writer::empty_tag('input', array('type'=>'submit', 'name'=>'cancel', 'value'=>get_string('cancel')));
+        $output .= html_writer::empty_tag('input', array('type' => 'submit', 'name' => 'cancel', 'value' => get_string('cancel')));
         $output .= html_writer::end_tag('div');
         return $output;
     }
@@ -469,9 +480,9 @@ class core_backup_renderer extends plugin_renderer_base {
      */
     public function role_mappings($rolemappings, $roles) {
         $roles[0] = get_string('none');
-        $output  = html_writer::start_tag('div', array('class'=>'restore-rolemappings'));
+        $output  = html_writer::start_tag('div', array('class' => 'restore-rolemappings'));
         $output .= $this->output->heading(get_string('restorerolemappings', 'backup'), 2);
-        foreach ($rolemappings as $id=>$mapping) {
+        foreach ($rolemappings as $id => $mapping) {
             $label = $mapping->name;
             $name = 'mapping'.$id;
             $selected = $mapping->targetroleid;
@@ -488,7 +499,7 @@ class core_backup_renderer extends plugin_renderer_base {
      * @param string $method
      * @return string
      */
-    public function continue_button($url, $method='post') {
+    public function continue_button($url, $method = 'post') {
         if (!($url instanceof moodle_url)) {
             $url = new moodle_url($url);
         }
@@ -514,7 +525,7 @@ class core_backup_renderer extends plugin_renderer_base {
      * Displays a backup files viewer
      *
      * @global stdClass $USER
-     * @param backup_files_viewer $tree
+     * @param backup_files_viewer $viewer
      * @return string
      */
     public function render_backup_files_viewer(backup_files_viewer $viewer) {
@@ -531,7 +542,15 @@ class core_backup_renderer extends plugin_renderer_base {
             if ($file->is_directory()) {
                 continue;
             }
-            $fileurl = moodle_url::make_pluginfile_url($file->get_contextid(), $file->get_component(), $file->get_filearea(), null, $file->get_filepath(), $file->get_filename(), true);
+            $fileurl = moodle_url::make_pluginfile_url(
+                $file->get_contextid(),
+                $file->get_component(),
+                $file->get_filearea(),
+                null,
+                $file->get_filepath(),
+                $file->get_filename(),
+                true
+            );
             $params = array();
             $params['action'] = 'choosebackupfile';
             $params['filename'] = $file->get_filename();
@@ -552,7 +571,17 @@ class core_backup_renderer extends plugin_renderer_base {
         }
 
         $html = html_writer::table($table);
-        $html .= $this->output->single_button(new moodle_url('/backup/backupfilesedit.php', array('currentcontext'=>$viewer->currentcontext->id, 'contextid'=>$viewer->filecontext->id, 'filearea'=>$viewer->filearea, 'component'=>$viewer->component, 'returnurl'=>$this->page->url->out())), get_string('managefiles', 'backup'), 'post');
+        $html .= $this->output->single_button(
+            new moodle_url('/backup/backupfilesedit.php', array(
+                'currentcontext' => $viewer->currentcontext->id,
+                'contextid' => $viewer->filecontext->id,
+                'filearea' => $viewer->filearea,
+                'component' => $viewer->component,
+                'returnurl' => $this->page->url->out())
+            ),
+            get_string('managefiles', 'backup'),
+            'post'
+        );
 
         return $html;
     }
@@ -580,7 +609,7 @@ class core_backup_renderer extends plugin_renderer_base {
                     $row->attributes['class'] .= ' dimmed';
                 }
                 $row->cells = array(
-                    html_writer::empty_tag('input', array('type'=>'radio', 'name'=>'targetid', 'value'=>$course->id)),
+                    html_writer::empty_tag('input', array('type' => 'radio', 'name' => 'targetid', 'value' => $course->id)),
                     format_string($course->shortname, true, array('context' => context_course::instance($course->id))),
                     format_string($course->fullname, true, array('context' => context_course::instance($course->id)))
                 );
@@ -605,9 +634,9 @@ class core_backup_renderer extends plugin_renderer_base {
         $output .= html_writer::table($table);
         $output .= html_writer::end_tag('div');
 
-        $output .= html_writer::start_tag('div', array('class'=>'rcs-search'));
-        $output .= html_writer::empty_tag('input', array('type'=>'text', 'name'=>restore_course_search::$VAR_SEARCH, 'value'=>$component->get_search()));
-        $output .= html_writer::empty_tag('input', array('type'=>'submit', 'name'=>'searchcourses', 'value'=>get_string('search')));
+        $output .= html_writer::start_tag('div', array('class' => 'rcs-search'));
+        $output .= html_writer::empty_tag('input', array('type' => 'text', 'name' => restore_course_search::$VAR_SEARCH, 'value' => $component->get_search()));
+        $output .= html_writer::empty_tag('input', array('type' => 'submit', 'name' => 'searchcourses', 'value' => get_string('search')));
         $output .= html_writer::end_tag('div');
 
         $output .= html_writer::end_tag('div');
@@ -627,9 +656,9 @@ class core_backup_renderer extends plugin_renderer_base {
         if ($component->get_count() === 0) {
             $output .= $this->output->notification(get_string('nomatchingcourses', 'backup'));
 
-            $output .= html_writer::start_tag('div', array('class'=>'ics-search'));
-            $output .= html_writer::empty_tag('input', array('type'=>'text', 'name'=>restore_course_search::$VAR_SEARCH, 'value'=>$component->get_search()));
-            $output .= html_writer::empty_tag('input', array('type'=>'submit', 'name'=>'searchcourses', 'value'=>get_string('search')));
+            $output .= html_writer::start_tag('div', array('class' => 'ics-search'));
+            $output .= html_writer::empty_tag('input', array('type' => 'text', 'name' => restore_course_search::$VAR_SEARCH, 'value' => $component->get_search()));
+            $output .= html_writer::empty_tag('input', array('type' => 'submit', 'name' => 'searchcourses', 'value' => get_string('search')));
             $output .= html_writer::end_tag('div');
 
             $output .= html_writer::end_tag('div');
@@ -643,7 +672,7 @@ class core_backup_renderer extends plugin_renderer_base {
             $countstr = get_string('totalcoursesearchresults', 'backup', $component->get_count());
         }
 
-        $output .= html_writer::tag('div', $countstr, array('class'=>'ics-totalresults'));
+        $output .= html_writer::tag('div', $countstr, array('class' => 'ics-totalresults'));
         $output .= html_writer::start_tag('div', array('class' => 'ics-results'));
 
         $table = new html_table();
@@ -656,7 +685,7 @@ class core_backup_renderer extends plugin_renderer_base {
                 $row->attributes['class'] .= ' dimmed';
             }
             $row->cells = array(
-                html_writer::empty_tag('input', array('type'=>'radio', 'name'=>'importid', 'value'=>$course->id)),
+                html_writer::empty_tag('input', array('type' => 'radio', 'name' => 'importid', 'value' => $course->id)),
                 format_string($course->shortname, true, array('context' => context_course::instance($course->id))),
                 format_string($course->fullname, true, array('context' => context_course::instance($course->id)))
             );
@@ -673,9 +702,9 @@ class core_backup_renderer extends plugin_renderer_base {
         $output .= html_writer::table($table);
         $output .= html_writer::end_tag('div');
 
-        $output .= html_writer::start_tag('div', array('class'=>'ics-search'));
-        $output .= html_writer::empty_tag('input', array('type'=>'text', 'name'=>restore_course_search::$VAR_SEARCH, 'value'=>$component->get_search()));
-        $output .= html_writer::empty_tag('input', array('type'=>'submit', 'name'=>'searchcourses', 'value'=>get_string('search')));
+        $output .= html_writer::start_tag('div', array('class' => 'ics-search'));
+        $output .= html_writer::empty_tag('input', array('type' => 'text', 'name' => restore_course_search::$VAR_SEARCH, 'value' => $component->get_search()));
+        $output .= html_writer::empty_tag('input', array('type' => 'submit', 'name' => 'searchcourses', 'value' => get_string('search')));
         $output .= html_writer::end_tag('div');
 
         $output .= html_writer::end_tag('div');
@@ -706,9 +735,9 @@ class core_backup_renderer extends plugin_renderer_base {
                     $row->attributes['class'] .= ' dimmed';
                 }
                 $row->cells = array(
-                    html_writer::empty_tag('input', array('type'=>'radio', 'name'=>'targetid', 'value'=>$category->id)),
+                    html_writer::empty_tag('input', array('type' => 'radio', 'name' => 'targetid', 'value' => $category->id)),
                     format_string($category->name, true, array('context' => context_coursecat::instance($category->id))),
-                    format_text($category->description, $category->descriptionformat, array('overflowdiv'=>true))
+                    format_text($category->description, $category->descriptionformat, array('overflowdiv' => true))
                 );
                 $table->data[] = $row;
             }
@@ -731,9 +760,9 @@ class core_backup_renderer extends plugin_renderer_base {
         $output .= html_writer::table($table);
         $output .= html_writer::end_tag('div');
 
-        $output .= html_writer::start_tag('div', array('class'=>'rcs-search'));
-        $output .= html_writer::empty_tag('input', array('type'=>'text', 'name'=>restore_category_search::$VAR_SEARCH, 'value'=>$component->get_search()));
-        $output .= html_writer::empty_tag('input', array('type'=>'submit', 'name'=>'searchcourses', 'value'=>get_string('search')));
+        $output .= html_writer::start_tag('div', array('class' => 'rcs-search'));
+        $output .= html_writer::empty_tag('input', array('type' => 'text', 'name' => restore_category_search::$VAR_SEARCH, 'value' => $component->get_search()));
+        $output .= html_writer::empty_tag('input', array('type' => 'submit', 'name' => 'searchcourses', 'value' => get_string('search')));
         $output .= html_writer::end_tag('div');
 
         $output .= html_writer::end_tag('div');
@@ -749,10 +778,30 @@ class core_backup_renderer extends plugin_renderer_base {
  * @since     Moodle 2.0
  */
 class backup_files_viewer implements renderable {
+
+    /**
+     * @var array
+     */
     public $files;
+
+    /**
+     * @var context
+     */
     public $filecontext;
+
+    /**
+     * @var string
+     */
     public $component;
+
+    /**
+     * @var string
+     */
     public $filearea;
+
+    /**
+     * @var context
+     */
     public $currentcontext;
 
     /**
index c8a1ed7..3ac1551 100644 (file)
@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
 /**
  * This file contains the forms used by the restore stages
  *
- * @package   moodlecore
+ * @package   core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
+/**
+ * An abstract moodleform class specially designed for the restore forms.
+ *
+ * @abstract Marked abstract here because some idiot forgot to mark it abstract in code!
+ * @package   core_backup
+ * @copyright 2010 Sam Hemelryk
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class restore_moodleform extends base_moodleform {
-    public function __construct(restore_ui_stage $uistage, $action = null, $customdata = null, $method = 'post', $target = '', $attributes = null, $editable = true) {
+    /**
+     * Constructor.
+     *
+     * Overridden just for the purpose of typehinting the first arg.
+     *
+     * @param restore_ui_stage $uistage
+     * @param null $action
+     * @param null $customdata
+     * @param string $method
+     * @param string $target
+     * @param null $attributes
+     * @param bool $editable
+     */
+    public function __construct(restore_ui_stage $uistage, $action = null, $customdata = null, $method = 'post',
+                                $target = '', $attributes = null, $editable = true) {
         parent::__construct($uistage, $action, $customdata, $method, $target, $attributes, $editable);
     }
 }
 
+/**
+ * Restore settings form.
+ *
+ * @package   core_backup
+ * @copyright 2010 Sam Hemelryk
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class restore_settings_form extends restore_moodleform {}
+
+/**
+ * Restore schema review form.
+ *
+ * @package   core_backup
+ * @copyright 2010 Sam Hemelryk
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class restore_schema_form extends restore_moodleform {}
+
+/**
+ * Restore complete process review form.
+ *
+ * @package   core_backup
+ * @copyright 2010 Sam Hemelryk
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class restore_review_form extends restore_moodleform {};
\ No newline at end of file
index cd74972..0bb8323 100644 (file)
@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -18,7 +17,7 @@
 /**
  * This file contains the restore user interface class
  *
- * @package   moodlecore
+ * @package   core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
  * The restore user interface class manages the user interface and restore for
  * Moodle.
  *
+ * @package   core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class restore_ui extends base_ui {
     /**
      * The stages of the restore user interface.
+     * Confirm the backup you are going to restore.
      */
     const STAGE_CONFIRM = 1;
+
+    /**
+     * The stages of the restore user interface.
+     * Select the destination for the restore.
+     */
     const STAGE_DESTINATION = 2;
+
+    /**
+     * The stages of the restore user interface.
+     * Alter the setting for the restore.
+     */
     const STAGE_SETTINGS = 4;
+
+    /**
+     * The stages of the restore user interface.
+     * Alter and review the schema that you are going to restore.
+     */
     const STAGE_SCHEMA = 8;
+
+    /**
+     * The stages of the restore user interface.
+     * The final review before the restore is run.
+     */
     const STAGE_REVIEW = 16;
+
+    /**
+     * The stages of the restore user interface.
+     * The restore is in process right now.
+     */
     const STAGE_PROCESS = 32;
+
+    /**
+     * The stages of the restore user interface.
+     * The process is complete.
+     */
     const STAGE_COMPLETE = 64;
 
     /**
-     *
+     * The current UI stage.
      * @var restore_ui_stage
      */
     protected $stage = null;
@@ -68,14 +99,17 @@ class restore_ui extends base_ui {
         restore_ui::STAGE_PROCESS       => 'process',
         restore_ui::STAGE_COMPLETE      => 'complete'
     );
+
     /**
      * Intialises what ever stage is requested. If none are requested we check
      * params for 'stage' and default to initial
      *
+     * @throws restore_ui_exception for an invalid stage
      * @param int|null $stage The desired stage to intialise or null for the default
+     * @param array $params
      * @return restore_ui_stage_initial|restore_ui_stage_schema|restore_ui_stage_confirmation|restore_ui_stage_final
      */
-    protected function initialise_stage($stage = null, array $params=null) {
+    protected function initialise_stage($stage = null, array $params = null) {
         if ($stage == null) {
             $stage = optional_param('stage', self::STAGE_CONFIRM, PARAM_INT);
         }
@@ -86,8 +120,10 @@ class restore_ui extends base_ui {
         $stage = new $class($this, $params);
         return $stage;
     }
+
     /**
      * This processes the current stage of the restore
+     * @throws restore_ui_exception if the progress is wrong.
      * @return bool
      */
     public function process() {
@@ -101,16 +137,17 @@ class restore_ui extends base_ui {
             return false;
         }
 
-        // Process the stage
+        // Process the stage.
         $processoutcome = $this->stage->process();
-        if ($processoutcome !== false && !($this->get_stage()==self::STAGE_PROCESS && optional_param('substage', false, PARAM_BOOL))) {
+        if ($processoutcome !== false && !($this->get_stage() == self::STAGE_PROCESS && optional_param('substage', false, PARAM_BOOL))) {
             $this->stage = $this->initialise_stage($this->stage->get_next_stage(), $this->stage->get_params());
         }
 
-        // Process UI event after to check changes are valid
+        // Process UI event after to check changes are valid.
         $this->controller->process_ui_event();
         return $processoutcome;
     }
+
     /**
      * Returns true if the stage is independent (not requiring a restore controller)
      * @return bool
@@ -118,6 +155,7 @@ class restore_ui extends base_ui {
     public function is_independent() {
         return false;
     }
+
     /**
      * Gets the unique ID associated with this UI
      * @return string
@@ -125,6 +163,7 @@ class restore_ui extends base_ui {
     public function get_uniqueid() {
         return $this->get_restoreid();
     }
+
     /**
      * Gets the restore id from the controller
      * @return string
@@ -158,7 +197,7 @@ class restore_ui extends base_ui {
     /**
      * Sets the progress reporter that will be returned by get_progress_reporter.
      *
-     * @param c\core\progress\base$progressreporter Progress reporter
+     * @param \core\progress\base $progressreporter Progress reporter
      */
     public function set_progress_reporter(\core\progress\base $progressreporter) {
         $this->progressreporter = $progressreporter;
@@ -166,6 +205,7 @@ class restore_ui extends base_ui {
 
     /**
      * Executes the restore plan
+     * @throws restore_ui_exception if the progress or stage is wrong.
      * @return bool
      */
     public function execute() {
@@ -204,7 +244,7 @@ class restore_ui extends base_ui {
      */
     protected function is_temporary_course_created($courseid) {
         global $DB;
-        //Check if current controller instance has created new course.
+        // Check if current controller instance has created new course.
         if ($this->controller->get_target() == backup::TARGET_NEW_COURSE) {
             $results = $DB->record_exists_sql("SELECT bc.itemid
                                                FROM {backup_controllers} bc, {course} c
@@ -226,16 +266,18 @@ class restore_ui extends base_ui {
     public function enforce_changed_dependencies() {
         return ($this->dependencychanges > 0);
     }
+
     /**
      * Loads the restore controller if we are tracking one
-     * @return restore_controller|false
+     * @param string|bool $restoreid
+     * @return string
      */
-    final public static function load_controller($restoreid=false) {
-        // Get the restore id optional param
+    final public static function load_controller($restoreid = false) {
+        // Get the restore id optional param.
         if ($restoreid) {
             try {
                 // Try to load the controller with it.
-                // If it fails at this point it is likely because this is the first load
+                // If it fails at this point it is likely because this is the first load.
                 $controller = restore_controller::load_controller($restoreid);
                 return $controller;
             } catch (Exception $e) {
@@ -244,9 +286,11 @@ class restore_ui extends base_ui {
         }
         return $restoreid;
     }
+
     /**
      * Initialised the requested independent stage
      *
+     * @throws restore_ui_exception
      * @param int $stage One of self::STAGE_*
      * @param int $contextid
      * @return restore_ui_stage_confirm|restore_ui_stage_destination
@@ -261,16 +305,18 @@ class restore_ui extends base_ui {
         }
         return new $class($contextid);
     }
+
     /**
      * Cancels the current restore and redirects the user back to the relevant place
      */
     public function cancel_process() {
-        //Delete temporary restore course if exists.
+        // Delete temporary restore course if exists.
         if ($this->controller->get_target() == backup::TARGET_NEW_COURSE) {
             $this->cleanup();
         }
         parent::cancel_process();
     }
+
     /**
      * Gets an array of progress bar items that can be displayed through the restore renderer.
      * @return array Array of items for the progress bar
@@ -283,22 +329,23 @@ class restore_ui extends base_ui {
         $items = array();
         while ($stage > 0) {
             $classes = array('backup_stage');
-            if (floor($stage/2) == $currentstage) {
+            if (floor($stage / 2) == $currentstage) {
                 $classes[] = 'backup_stage_next';
             } else if ($stage == $currentstage) {
                 $classes[] = 'backup_stage_current';
             } else if ($stage < $currentstage) {
                 $classes[] = 'backup_stage_complete';
             }
-            $item = array('text' => strlen(decbin($stage)).'. '.get_string('restorestage'.$stage, 'backup'),'class' => join(' ', $classes));
+            $item = array('text' => strlen(decbin($stage)).'. '.get_string('restorestage'.$stage, 'backup'), 'class' => join(' ', $classes));
             if ($stage < $currentstage && $currentstage < self::STAGE_COMPLETE && $stage > self::STAGE_DESTINATION) {
-                $item['link'] = new moodle_url($PAGE->url, array('restore'=>$this->get_restoreid(), 'stage'=>$stage));
+                $item['link'] = new moodle_url($PAGE->url, array('restore' => $this->get_restoreid(), 'stage' => $stage));
             }
             array_unshift($items, $item);
-            $stage = floor($stage/2);
+            $stage = floor($stage / 2);
         }
         return $items;
     }
+
     /**
      * Gets the name of this UI
      * @return string
@@ -306,6 +353,7 @@ class restore_ui extends base_ui {
     public function get_name() {
         return 'restore';
     }
+
     /**
      * Gets the first stage for this UI
      * @return int STAGE_CONFIRM
@@ -313,6 +361,7 @@ class restore_ui extends base_ui {
     public function get_first_stage_id() {
         return self::STAGE_CONFIRM;
     }
+
     /**
      * Returns true if this stage has substages of which at least one needs to be displayed
      * @return bool
@@ -320,9 +369,11 @@ class restore_ui extends base_ui {
     public function requires_substage() {
         return ($this->stage->has_sub_stages() && !$this->stage->process());
     }
+
     /**
      * Displays this stage
      *
+     * @throws base_ui_exception if the progress is wrong.
      * @param core_backup_renderer $renderer
      * @return string HTML code to echo
      */
@@ -335,6 +386,10 @@ class restore_ui extends base_ui {
 }
 
 /**
- * restore user interface exception. Modelled off the restore_exception class
+ * Restore user interface exception. Modelled off the restore_exception class
+ *
+ * @package   core_backup
+ * @copyright 2010 Sam Hemelryk
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class restore_ui_exception extends base_ui_exception {}
index f892b8c..8b71044 100644 (file)
@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
 /**
  * This file contains components used by the restore UI
  *
- * @package   moodlecore
+ * @package   core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 /**
  * A base class that can be used to build a specific search upon
+ *
+ * @package   core_backup
+ * @copyright 2010 Sam Hemelryk
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 abstract class restore_search_base implements renderable {
 
@@ -79,18 +82,19 @@ abstract class restore_search_base implements renderable {
      * Constructor
      * @param array $config Config options
      */
-    public function __construct(array $config=array()) {
+    public function __construct(array $config = array()) {
 
         $this->search = optional_param($this->get_varsearch(), self::DEFAULT_SEARCH, PARAM_NOTAGS);
         $this->maxresults = get_config('backup', 'import_general_maxresults');
 
-        foreach ($config as $name=>$value) {
+        foreach ($config as $name => $value) {
             $method = 'set_'.$name;
             if (method_exists($this, $method)) {
                 $this->$method($value);
             }
         }
     }
+
     /**
      * The URL for this search
      * @global moodle_page $PAGE
@@ -101,15 +105,17 @@ abstract class restore_search_base implements renderable {
         $params = array(
             $this->get_varsearch()    => $this->get_search()
         );
-        return ($this->url !== null)?new moodle_url($this->url, $params):new moodle_url($PAGE->url, $params);
+        return ($this->url !== null) ? new moodle_url($this->url, $params) : new moodle_url($PAGE->url, $params);
     }
+
     /**
      * The current search string
      * @return string
      */
     final public function get_search() {
-        return ($this->search !== null)?$this->search:self::DEFAULT_SEARCH;
+        return ($this->search !== null) ? $this->search : self::DEFAULT_SEARCH;
     }
+
     /**
      * The total number of results
      * @return int
@@ -120,6 +126,7 @@ abstract class restore_search_base implements renderable {
         }
         return $this->totalcount;
     }
+
     /**
      * Returns an array of results from the search
      * @return array
@@ -130,6 +137,7 @@ abstract class restore_search_base implements renderable {
         }
         return $this->results;
     }
+
     /**
      * Sets the page URL
      * @param moodle_url $url
@@ -137,6 +145,7 @@ abstract class restore_search_base implements renderable {
     final public function set_url(moodle_url $url) {
         $this->url = $url;
     }
+
     /**
      * Invalidates the results collected so far
      */
@@ -144,12 +153,13 @@ abstract class restore_search_base implements renderable {
         $this->results = null;
         $this->totalcount = null;
     }
+
     /**
      * Adds a required capability which all results will be checked against
      * @param string $capability
      * @param int|null $user
      */
-    final public function require_capability($capability, $user=null) {
+    final public function require_capability($capability, $user = null) {
         if (!is_int($user)) {
             $user = null;
         }
@@ -158,6 +168,7 @@ abstract class restore_search_base implements renderable {
             'user' => $user
         );
     }
+
     /**
      * Executes the search
      *
@@ -198,7 +209,7 @@ abstract class restore_search_base implements renderable {
                     }
                 }
                 // Check if we are over the limit.
-                if ($this->totalcount+1 > $this->maxresults) {
+                if ($this->totalcount + 1 > $this->maxresults) {
                     $this->hasmoreresults = true;
                     break;
                 }
@@ -212,6 +223,10 @@ abstract class restore_search_base implements renderable {
         return $this->totalcount;
     }
 
+    /**
+     * Returns true if there are more search results.
+     * @return bool
+     */
     final public function has_more_results() {
         if ($this->results === null) {
             $this->search();
@@ -224,15 +239,18 @@ abstract class restore_search_base implements renderable {
      * @return array
      */
     abstract protected function get_searchsql();
+
     /**
      * Gets the context level associated with this components items
      * @return CONTEXT_*
      */
     abstract protected function get_itemcontextlevel();
+
     /**
      * Formats the results
      */
     abstract protected function format_results();
+
     /**
      * Gets the string used to transfer the search string for this compontents requests
      * @return string
@@ -242,24 +260,42 @@ abstract class restore_search_base implements renderable {
 
 /**
  * A course search component
+ *
+ * @package   core_backup
+ * @copyright 2010 Sam Hemelryk
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class restore_course_search extends restore_search_base {
 
+    /**
+     * @var string
+     */
     static $VAR_SEARCH = 'search';
 
+    /**
+     * The current course id.
+     * @var int
+     */
     protected $currentcourseid = null;
+
+    /**
+     * Determines if the current course is included in the results.
+     * @var bool
+     */
     protected $includecurrentcourse;
 
     /**
+     * Constructor
      * @param array $config
      * @param int $currentcouseid The current course id so it can be ignored
      */
-    public function __construct(array $config=array(), $currentcouseid = null) {
+    public function __construct(array $config = array(), $currentcouseid = null) {
         parent::__construct($config);
         $this->setup_restrictions();
         $this->currentcourseid = $currentcouseid;
         $this->includecurrentcourse = false;
     }
+
     /**
      * Sets up any access restrictions for the courses to be displayed in the search.
      *
@@ -268,9 +304,11 @@ class restore_course_search extends restore_search_base {
     protected function setup_restrictions() {
         $this->require_capability('moodle/restore:restorecourse');
     }
+
     /**
-     *
+     * Get the search SQL.
      * @global moodle_database $DB
+     * @return array
      */
     protected function get_searchsql() {
         global $DB;
@@ -284,7 +322,7 @@ class restore_course_search extends restore_search_base {
             'siteid' => SITEID
         );
 
-        $select     = " SELECT c.id,c.fullname,c.shortname,c.visible,c.sortorder ";
+        $select     = " SELECT c.id, c.fullname, c.shortname, c.visible, c.sortorder ";
         $from       = " FROM {course} c ";
         $where      = " WHERE (".$DB->sql_like('c.fullname', ':fullnamesearch', false)." OR ".$DB->sql_like('c.shortname', ':shortnamesearch', false).") AND c.id <> :siteid";
         $orderby    = " ORDER BY c.sortorder";
@@ -296,13 +334,31 @@ class restore_course_search extends restore_search_base {
 
         return array($select.$ctxselect.$from.$ctxjoin.$where.$orderby, $params);
     }
+
+    /**
+     * Gets the context level for the search result items.
+     * @return CONTEXT_|int
+     */
     protected function get_itemcontextlevel() {
         return CONTEXT_COURSE;
     }
+
+    /**
+     * Formats results.
+     */
     protected function format_results() {}
+
+    /**
+     * Returns the name the search variable should use
+     * @return string
+     */
     public function get_varsearch() {
         return self::$VAR_SEARCH;
     }
+
+    /**
+     * Returns true if the current course should be included in the results.
+     */
     public function set_include_currentcourse() {
         $this->includecurrentcourse = true;
     }
@@ -310,18 +366,31 @@ class restore_course_search extends restore_search_base {
 
 /**
  * A category search component
+ *
+ * @package   core_backup
+ * @copyright 2010 Sam Hemelryk
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class restore_category_search extends restore_search_base  {
 
+    /**
+     * The search variable to use.
+     * @var string
+     */
     static $VAR_SEARCH = 'catsearch';
 
-    public function __construct(array $config=array()) {
+    /**
+     * Constructor
+     * @param array $config
+     */
+    public function __construct(array $config = array()) {
         parent::__construct($config);
         $this->require_capability('moodle/course:create');
     }
     /**
-     *
+     * Returns the search SQL.
      * @global moodle_database $DB
+     * @return array
      */
     protected function get_searchsql() {
         global $DB;
@@ -333,19 +402,32 @@ class restore_category_search extends restore_search_base  {
             'namesearch' => '%'.$this->get_search().'%',
         );
 
-        $select     = " SELECT c.id,c.name,c.visible,c.sortorder,c.description,c.descriptionformat ";
+        $select     = " SELECT c.id, c.name, c.visible, c.sortorder, c.description, c.descriptionformat ";
         $from       = " FROM {course_categories} c ";
         $where      = " WHERE ".$DB->sql_like('c.name', ':namesearch', false);
         $orderby    = " ORDER BY c.sortorder";
 
         return array($select.$ctxselect.$from.$ctxjoin.$where.$orderby, $params);
     }
+
+    /**
+     * Returns the context level of the search results.
+     * @return CONTEXT_COURSECAT
+     */
     protected function get_itemcontextlevel() {
         return CONTEXT_COURSECAT;
     }
+
+    /**
+     * Formats the results.
+     */
     protected function format_results() {}
+
+    /**
+     * Returns the name to use for the search variable.
+     * @return string
+     */
     public function get_varsearch() {
         return self::$VAR_SEARCH;
     }
 }
-
index 63dc00e..5bb40a1 100644 (file)
@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -20,9 +19,9 @@
  *
  * This file contains the classes required to manage the stages that make up the
  * restore user interface.
- * These will be primarily operated a {@see restore_ui} instance.
+ * These will be primarily operated a {@link restore_ui} instance.
  *
- * @package   moodlecore
+ * @package   core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -35,6 +34,7 @@
  *  - process : To process the stage
  *  - initialise_stage_form : To get a restore_moodleform instance for the stage
  *
+ * @package   core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -42,8 +42,9 @@ abstract class restore_ui_stage extends base_ui_stage {
     /**
      * Constructor
      * @param restore_ui $ui
+     * @param array $params
      */
-    public function __construct(restore_ui $ui, array $params=null) {
+    public function __construct(restore_ui $ui, array $params = null) {
         $this->ui = $ui;
         $this->params = $params;
     }
@@ -54,6 +55,7 @@ abstract class restore_ui_stage extends base_ui_stage {
     final public function get_restoreid() {
         return $this->get_uniqueid();
     }
+
     /**
      * This is an independent stage
      * @return int
@@ -75,8 +77,9 @@ abstract class restore_ui_stage extends base_ui_stage {
      * @return string
      */
     final public function get_name() {
-        return get_string('restorestage'.$this->stage,'backup');
+        return get_string('restorestage'.$this->stage, 'backup');
     }
+
     /**
      * Returns true if this is the settings stage
      * @return bool
@@ -91,6 +94,10 @@ abstract class restore_ui_stage extends base_ui_stage {
  *
  * An independent stage is a judged to be so because it doesn't require, and has
  * no use for the restore controller.
+ *
+ * @package   core_backup
+ * @copyright 2010 Sam Hemelryk
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 abstract class restore_ui_independent_stage {
     /**
@@ -98,9 +105,29 @@ abstract class restore_ui_independent_stage {
      */
     private $progressreporter;
 
+    /**
+     * Constructs the restore stage.
+     * @param int $contextid
+     */
     abstract public function __construct($contextid);
+
+    /**
+     * Processes the current restore stage.
+     * @return mixed
+     */
     abstract public function process();
+
+    /**
+     * Displays this restore stage.
+     * @param core_backup_renderer $renderer
+     * @return mixed
+     */
     abstract public function display(core_backup_renderer $renderer);
+
+    /**
+     * Returns the current restore stage.
+     * @return int
+     */
     abstract public function get_stage();
 
     /**
@@ -146,23 +173,30 @@ abstract class restore_ui_independent_stage {
         $items = array();
         while ($stage > 0) {
             $classes = array('backup_stage');
-            if (floor($stage/2) == $currentstage) {
+            if (floor($stage / 2) == $currentstage) {
                 $classes[] = 'backup_stage_next';
             } else if ($stage == $currentstage) {
                 $classes[] = 'backup_stage_current';
             } else if ($stage < $currentstage) {
                 $classes[] = 'backup_stage_complete';
             }
-            $item = array('text' => strlen(decbin($stage)).'. '.get_string('restorestage'.$stage, 'backup'),'class' => join(' ', $classes));
+            $item = array('text' => strlen(decbin($stage)).'. '.get_string('restorestage'.$stage, 'backup'), 'class' => join(' ', $classes));
             if ($stage < $currentstage && $currentstage < restore_ui::STAGE_COMPLETE) {
-                //$item['link'] = new moodle_url($PAGE->url, array('restore'=>$this->get_restoreid(), 'stage'=>$stage));
+                // By default you can't go back to independent stages, if that changes in the future uncomment the next line.
+                // $item['link'] = new moodle_url($PAGE->url, array('restore' => $this->get_restoreid(), 'stage' => $stage));
             }
             array_unshift($items, $item);
-            $stage = floor($stage/2);
+            $stage = floor($stage / 2);
         }
         return $items;
     }
+
+    /**
+     * Returns the restore stage name.
+     * @return string
+     */
     abstract public function get_stage_name();
+
     /**
      * Obviously true
      * @return true
@@ -170,8 +204,12 @@ abstract class restore_ui_independent_stage {
     final public function is_independent() {
         return true;
     }
+
+    /**
+     * Handles the destruction of this object.
+     */
     public function destroy() {
-        // Nothing to destroy here!
+        // Nothing to destroy here!.
     }
 }
 
@@ -179,22 +217,44 @@ abstract class restore_ui_independent_stage {
  * The confirmation stage.
  *
  * This is the first stage, it is independent.
+ *
+ * @package   core_backup
+ * @copyright 2010 Sam Hemelryk
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class restore_ui_stage_confirm extends restore_ui_independent_stage implements file_progress {
 
+    /**
+     * The context ID.
+     * @var int
+     */
     protected $contextid;
+
+    /**
+     * The file name.
+     * @var string
+     */
     protected $filename = null;
+
+    /**
+     * The file path.
+     * @var string
+     */
     protected $filepath = null;
 
     /**
      * @var string Content hash of archive file to restore (if specified by hash)
      */
     protected $contenthash = null;
+
     /**
      * @var string Pathname hash of stored_file object to restore
      */
     protected $pathnamehash = null;
 
+    /**
+     * @var array
+     */
     protected $details;
 
     /**
@@ -202,6 +262,11 @@ class restore_ui_stage_confirm extends restore_ui_independent_stage implements f
      */
     protected $startedprogress = false;
 
+    /**
+     * Constructor
+     * @param int $contextid
+     * @throws coding_exception
+     */
     public function __construct($contextid) {
         $this->contextid = $contextid;
         $this->filename = optional_param('filename', null, PARAM_FILE);
@@ -217,6 +282,11 @@ class restore_ui_stage_confirm extends restore_ui_independent_stage implements f
         }
     }
 
+    /**
+     * Processes this restore stage
+     * @return bool
+     * @throws restore_ui_exception
+     */
     public function process() {
         global $CFG;
         if ($this->filename) {
@@ -243,6 +313,7 @@ class restore_ui_stage_confirm extends restore_ui_independent_stage implements f
      * Extracts the file.
      *
      * @param string|stored_file $source Archive file to extract
+     * @return bool
      */
     protected function extract_file_to_dir($source) {
         global $CFG, $USER;
@@ -298,24 +369,34 @@ class restore_ui_stage_confirm extends restore_ui_independent_stage implements f
         $format = backup_general_helper::detect_backup_format($this->filepath);
 
         if ($format === backup::FORMAT_UNKNOWN) {
-            // unknown format - we can't do anything here
+            // Unknown format - we can't do anything here.
             return $renderer->backup_details_unknown($prevstageurl);
 
         } else if ($format !== backup::FORMAT_MOODLE) {
-            // non-standard format to be converted
+            // Non-standard format to be converted.
             $details = array('format' => $format, 'type' => backup::TYPE_1COURSE); // todo type to be returned by a converter
             return $renderer->backup_details_nonstandard($nextstageurl, $details);
 
         } else {
-            // standard MBZ backup, let us get information from it and display
+            // Standard MBZ backup, let us get information from it and display.
             $this->details = backup_general_helper::get_backup_information($this->filepath);
             return $renderer->backup_details($this->details, $nextstageurl);
         }
     }
 
+    /**
+     * The restore stage name.
+     * @return string
+     * @throws coding_exception
+     */
     public function get_stage_name() {
         return get_string('restorestage'.restore_ui::STAGE_CONFIRM, 'backup');
     }
+
+    /**
+     * The restore stage this class is for.
+     * @return int
+     */
     public function get_stage() {
         return restore_ui::STAGE_CONFIRM;
     }
@@ -325,25 +406,72 @@ class restore_ui_stage_confirm extends restore_ui_independent_stage implements f
  * This is the destination stage.
  *
  * This stage is the second stage and is also independent
+ *
+ * @package   core_backup
+ * @copyright 2010 Sam Hemelryk
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class restore_ui_stage_destination extends restore_ui_independent_stage {
+
+    /**
+     * The context ID.
+     * @var int
+     */
     protected $contextid;
+
+    /**
+     * The backup file path.
+     * @var mixed|null
+     */
     protected $filepath = null;
+
+    /**
+     * The course ID.
+     * @var null
+     */
     protected $courseid = null;
+
+    /**
+     * The restore target. One of backup::TARGET_NEW
+     * @var int
+     */
     protected $target = backup::TARGET_NEW_COURSE;
+
+    /**
+     * The course search component.
+     * @var null|restore_course_search
+     */
     protected $coursesearch = null;
+
+    /**
+     * The category search component.
+     * @var null|restore_category_search
+     */
     protected $categorysearch = null;
+
+    /**
+     * Constructs the destination stage.
+     * @param int $contextid
+     * @throws coding_exception
+     */
     public function __construct($contextid) {
         global $PAGE;
         $this->contextid = $contextid;
         $this->filepath = required_param('filepath', PARAM_ALPHANUM);
         $url = new moodle_url($PAGE->url, array(
-            'filepath'=>$this->filepath,
-            'contextid'=>$this->contextid,
-            'stage'=>restore_ui::STAGE_DESTINATION));
-        $this->coursesearch = new restore_course_search(array('url'=>$url), context::instance_by_id($contextid)->instanceid);
-        $this->categorysearch = new restore_category_search(array('url'=>$url));
+            'filepath' => $this->filepath,
+            'contextid' => $this->contextid,
+            'stage' => restore_ui::STAGE_DESTINATION));
+        $this->coursesearch = new restore_course_search(array('url' => $url), context::instance_by_id($contextid)->instanceid);
+        $this->categorysearch = new restore_category_search(array('url' => $url));
     }
+
+    /**
+     * Processes the destination stage.
+     * @return bool
+     * @throws coding_exception
+     * @throws restore_ui_exception
+     */
     public function process() {
         global $CFG, $DB;
         if (!file_exists("$CFG->tempdir/backup/".$this->filepath) || !is_dir("$CFG->tempdir/backup/".$this->filepath)) {
@@ -361,7 +489,7 @@ class restore_ui_stage_destination extends restore_ui_independent_stage {
             } else {
                 $this->courseid = $targetid;
             }
-            return ($DB->record_exists('course', array('id'=>$this->courseid)));
+            return ($DB->record_exists('course', array('id' => $this->courseid)));
         }
         return false;
     }
@@ -377,7 +505,7 @@ class restore_ui_stage_destination extends restore_ui_independent_stage {
         $format = backup_general_helper::detect_backup_format($this->filepath);
 
         if ($format === backup::FORMAT_MOODLE) {
-            // standard Moodle 2 format, let use get the type of the backup
+            // Standard Moodle 2 format, let use get the type of the backup.
             $details = backup_general_helper::get_backup_information($this->filepath);
             if ($details->type === backup::TYPE_1COURSE) {
                 $wholecourse = true;
@@ -386,9 +514,9 @@ class restore_ui_stage_destination extends restore_ui_independent_stage {
             }
 
         } else {
-            // non-standard format to be converted. We assume it contains the
+            // Non-standard format to be converted. We assume it contains the
             // whole course for now. However, in the future there might be a callback
-            // to the installed converters
+            // to the installed converters.
             $wholecourse = true;
         }
 
@@ -407,39 +535,77 @@ class restore_ui_stage_destination extends restore_ui_independent_stage {
         return $renderer->course_selector($nextstageurl, $wholecourse, $this->categorysearch, $this->coursesearch, $currentcourse);
     }
 
+    /**
+     * Returns the stage name.
+     * @return string
+     * @throws coding_exception
+     */
     public function get_stage_name() {
         return get_string('restorestage'.restore_ui::STAGE_DESTINATION, 'backup');
     }
+
+    /**
+     * Returns the backup file path
+     * @return mixed|null
+     */
     public function get_filepath() {
         return $this->filepath;
     }
+
+    /**
+     * Returns the course id.
+     * @return null
+     */
     public function get_course_id() {
         return $this->courseid;
     }
+
+    /**
+     * Returns the current restore stage
+     * @return int
+     */
     public function get_stage() {
         return restore_ui::STAGE_DESTINATION;
     }
+
+    /**
+     * Returns the target for this restore.
+     * One of backup::TARGET_*
+     * @return int
+     */
     public function get_target() {
         return $this->target;
     }
 }
+
 /**
  * This stage is the settings stage.
  *
  * This stage is the third stage, it is dependent on a restore controller and
  * is the first stage as such.
+ *
+ * @package   core_backup
+ * @copyright 2010 Sam Hemelryk
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class restore_ui_stage_settings extends restore_ui_stage {
     /**
      * Initial restore stage constructor
      * @param restore_ui $ui
+     * @param array $params
      */
-    public function __construct(restore_ui $ui, array $params=null) {
+    public function __construct(restore_ui $ui, array $params = null) {
         $this->stage = restore_ui::STAGE_SETTINGS;
         parent::__construct($ui, $params);
     }
 
-    public function process(base_moodleform $form=null) {
+    /**
+     * Process the settings stage.
+     *
+     * @param base_moodleform $form
+     * @return bool|int
+     */
+    public function process(base_moodleform $form = null) {
         $form = $this->initialise_stage_form();
 
         if ($form->is_cancelled()) {
@@ -451,9 +617,9 @@ class restore_ui_stage_settings extends restore_ui_stage {
             $tasks = $this->ui->get_tasks();
             $changes = 0;
             foreach ($tasks as &$task) {
-                // We are only interesting in the backup root task for this stage
+                // We are only interesting in the backup root task for this stage.
                 if ($task instanceof restore_root_task || $task instanceof restore_course_task) {
-                    // Get all settings into a var so we can iterate by reference
+                    // Get all settings into a var so we can iterate by reference.
                     $settings = $task->get_settings();
                     foreach ($settings as &$setting) {
                         $name = $setting->get_ui_name();
@@ -467,37 +633,43 @@ class restore_ui_stage_settings extends restore_ui_stage {
                     }
                 }
             }
-            // Return the number of changes the user made
+            // Return the number of changes the user made.
             return $changes;
         } else {
             return false;
         }
     }
 
+    /**
+     * Initialise the stage form.
+     *
+     * @return backup_moodleform|base_moodleform|restore_settings_form
+     * @throws coding_exception
+     */
     protected function initialise_stage_form() {
         global $PAGE;
         if ($this->stageform === null) {
             $form = new restore_settings_form($this, $PAGE->url);
-            // Store as a variable so we can iterate by reference
+            // Store as a variable so we can iterate by reference.
             $tasks = $this->ui->get_tasks();
             $headingprinted = false;
-            // Iterate all tasks by reference
+            // Iterate all tasks by reference.
             foreach ($tasks as &$task) {
-                // For the initial stage we are only interested in the root settings
+                // For the initial stage we are only interested in the root settings.
                 if ($task instanceof restore_root_task) {
                     if (!$headingprinted) {
                         $form->add_heading('rootsettings', get_string('restorerootsettings', 'backup'));
                         $headingprinted = true;
                     }
                     $settings = $task->get_settings();
-                    // First add all settings except the filename setting
+                    // First add all settings except the filename setting.
                     foreach ($settings as &$setting) {
                         if ($setting->get_name() == 'filename') {
                             continue;
                         }
                         $form->add_setting($setting, $task);
                     }
-                    // Then add all dependencies
+                    // Then add all dependencies.
                     foreach ($settings as &$setting) {
                         if ($setting->get_name() == 'filename') {
                             continue;
@@ -508,7 +680,7 @@ class restore_ui_stage_settings extends restore_ui_stage {
             }
             $this->stageform = $form;
         }
-        // Return the form
+        // Return the form.
         return $this->stageform;
     }
 }
@@ -519,6 +691,7 @@ class restore_ui_stage_settings extends restore_ui_stage {
  * During the schema stage the user is required to set the settings that relate
  * to the area that they are backing up as well as its children.
  *
+ * @package   core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -530,38 +703,40 @@ class restore_ui_stage_schema extends restore_ui_stage {
 
     /**
      * Schema stage constructor
-     * @param backup_moodleform $ui
+     * @param restore_ui $ui
+     * @param array $params
      */
-    public function __construct(restore_ui $ui, array $params=null) {
+    public function __construct(restore_ui $ui, array $params = null) {
         $this->stage = restore_ui::STAGE_SCHEMA;
         parent::__construct($ui, $params);
     }
+
     /**
      * Processes the schema stage
      *
-     * @param backup_moodleform|null $form
+     * @param base_moodleform $form
      * @return int The number of changes the user made
      */
     public function process(base_moodleform $form = null) {
         $form = $this->initialise_stage_form();
-        // Check it wasn't cancelled
+        // Check it wasn't cancelled.
         if ($form->is_cancelled()) {
             $this->ui->cancel_process();
         }
 
-        // Check it has been submit
+        // Check it has been submit.
         $data = $form->get_data();
         if ($data && confirm_sesskey()) {
-            // Get the tasks into a var so we can iterate by reference
+            // Get the tasks into a var so we can iterate by reference.
             $tasks = $this->ui->get_tasks();
             $changes = 0;
-            // Iterate all tasks by reference
+            // Iterate all tasks by reference.
             foreach ($tasks as &$task) {
-                // We are only interested in schema settings
+                // We are only interested in schema settings.
                 if (!($task instanceof restore_root_task)) {
-                    // Store as a variable so we can iterate by reference
+                    // Store as a variable so we can iterate by reference.
                     $settings = $task->get_settings();
-                    // Iterate by reference
+                    // Iterate by reference.
                     foreach ($settings as &$setting) {
                         $name = $setting->get_ui_name();
                         if (isset($data->$name) &&  $data->$name != $setting->get_value()) {
@@ -574,12 +749,13 @@ class restore_ui_stage_schema extends restore_ui_stage {
                     }
                 }
             }
-            // Return the number of changes the user made
+            // Return the number of changes the user made.
             return $changes;
         } else {
             return false;
         }
     }
+
     /**
      * Creates the backup_schema_form instance for this stage
      *
@@ -602,22 +778,22 @@ class restore_ui_stage_schema extends restore_ui_stage {
             foreach ($tasks as $task) {
                 if (!($task instanceof restore_root_task)) {
                     if (!$courseheading) {
-                        // If we havn't already display a course heading to group nicely
+                        // If we haven't already display a course heading to group nicely.
                         $form->add_heading('coursesettings', get_string('coursesettings', 'backup'));
                         $courseheading = true;
                     }
                     // Put each setting into an array of settings to add. Adding
-                    // a setting individually is a very slow operation, so we add
+                    // a setting individually is a very slow operation, so we add.
                     // them all in a batch later on.
                     foreach ($task->get_settings() as $setting) {
                         $allsettings[] = array($setting, $task);
                     }
                 } else if ($this->ui->enforce_changed_dependencies()) {
                     // Only show these settings if dependencies changed them.
-                    // Add a root settings heading to group nicely
+                    // Add a root settings heading to group nicely.
                     $form->add_heading('rootsettings', get_string('rootsettings', 'backup'));
                     // Iterate all settings and add them to the form as a fixed
-                    // setting. We only want schema settings to be editable
+                    // setting. We only want schema settings to be editable.
                     foreach ($task->get_settings() as $setting) {
                         if ($setting->get_name() != 'filename') {
                             $form->add_fixed_setting($setting, $task);
@@ -631,13 +807,13 @@ class restore_ui_stage_schema extends restore_ui_stage {
 
             // Add settings for tasks in batches of up to 1000. Adding settings
             // in larger batches improves performance, but if it takes too long,
-            // we won't be able to update the progress bar so the backup might
+            // we won't be able to update the progress bar so the backup might.
             // time out. 1000 is chosen to balance this.
             $numsettings = count($allsettings);
             $progress->start_progress('', ceil($numsettings / self::MAX_SETTINGS_BATCH));
             $start = 0;
             $done = 1;
-            while($start < $numsettings) {
+            while ($start < $numsettings) {
                 $length = min(self::MAX_SETTINGS_BATCH, $numsettings - $start);
                 $form->add_settings(array_slice($allsettings, $start, $length));
                 $start += $length;
@@ -667,27 +843,31 @@ class restore_ui_stage_schema extends restore_ui_stage {
  * On this stage the user reviews the setting for the backup and can change the filename
  * of the file that will be generated.
  *
+ * @package   core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class restore_ui_stage_review extends restore_ui_stage {
+
     /**
      * Constructs the stage
      * @param restore_ui $ui
+     * @param array $params
      */
-    public function __construct($ui, array $params=null) {
+    public function __construct($ui, array $params = null) {
         $this->stage = restore_ui::STAGE_REVIEW;
         parent::__construct($ui, $params);
     }
+
     /**
      * Processes the confirmation stage
      *
-     * @param backup_moodleform $form
+     * @param base_moodleform $form
      * @return int The number of changes the user made
      */
     public function process(base_moodleform $form = null) {
         $form = $this->initialise_stage_form();
-        // Check it hasn't been cancelled
+        // Check it hasn't been cancelled.
         if ($form->is_cancelled()) {
             $this->ui->cancel_process();
         }
@@ -707,7 +887,7 @@ class restore_ui_stage_review extends restore_ui_stage {
     protected function initialise_stage_form() {
         global $PAGE;
         if ($this->stageform === null) {
-            // Get the form
+            // Get the form.
             $form = new restore_review_form($this, $PAGE->url);
             $content = '';
             $courseheading = false;
@@ -718,14 +898,14 @@ class restore_ui_stage_review extends restore_ui_stage {
             $done = 1;
             foreach ($tasks as $task) {
                 if ($task instanceof restore_root_task) {
-                    // If its a backup root add a root settings heading to group nicely
+                    // If its a backup root add a root settings heading to group nicely.
                     $form->add_heading('rootsettings', get_string('rootsettings', 'backup'));
                 } else if (!$courseheading) {
-                    // we havn't already add a course heading
+                    // We haven't already add a course heading.
                     $form->add_heading('coursesettings', get_string('coursesettings', 'backup'));
                     $courseheading = true;
                 }
-                // Iterate all settings, doesnt need to happen by reference
+                // Iterate all settings, doesnt need to happen by reference.
                 foreach ($task->get_settings() as $setting) {
                     $form->add_fixed_setting($setting, $task);
                 }
@@ -754,21 +934,34 @@ class restore_ui_stage_review extends restore_ui_stage {
  * This highlights that we neither need a form nor a display method for this stage
  * we simply need to process.
  *
+ * @package   core_backup
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class restore_ui_stage_process extends restore_ui_stage {
 
+    /**
+     * There is no substage required.
+     */
     const SUBSTAGE_NONE = 0;
+
+    /**
+     * The prechecks substage is required/the current substage.
+     */
     const SUBSTAGE_PRECHECKS = 2;
 
+    /**
+     * The current substage.
+     * @var int
+     */
     protected $substage = 0;
 
     /**
      * Constructs the final stage
-     * @param backup_ui $ui
+     * @param base_ui $ui
+     * @param array $params
      */
-    public function __construct(base_ui $ui, array $params=null) {
+    public function __construct(base_ui $ui, array $params = null) {
         $this->stage = restore_ui::STAGE_PROCESS;
         parent::__construct($ui, $params);
     }
@@ -779,13 +972,15 @@ class restore_ui_stage_process extends restore_ui_stage {
      * before execution, if there is we gear up to display the subpage, otherwise
      * we return true which will lead to execution of the restore and the loading
      * of the completed stage.
+     *
+     * @param base_moodleform $form
      */
-    public function process(base_moodleform $form=null) {
+    public function process(base_moodleform $form = null) {
         if (optional_param('cancel', false, PARAM_BOOL)) {
-            redirect(new moodle_url('/course/view.php', array('id'=>$this->get_ui()->get_controller()->get_courseid())));
+            redirect(new moodle_url('/course/view.php', array('id' => $this->get_ui()->get_controller()->get_courseid())));
         }
 
-        // First decide whether a substage is needed
+        // First decide whether a substage is needed.
         $rc = $this->ui->get_controller();
         if ($rc->get_status() == backup::STATUS_SETTING_UI) {
             $rc->finish_ui();
@@ -803,11 +998,11 @@ class restore_ui_stage_process extends restore_ui_stage {
         $substage = optional_param('substage', null, PARAM_INT);
         if (empty($this->substage) && !empty($substage)) {
             $this->substage = $substage;
-            // Now check whether that substage has already been submit
+            // Now check whether that substage has already been submit.
             if ($this->substage == self::SUBSTAGE_PRECHECKS && optional_param('sesskey', null, PARAM_RAW) == sesskey()) {
                 $info = $rc->get_info();
                 if (!empty($info->role_mappings->mappings)) {
-                    foreach ($info->role_mappings->mappings as $key=>&$mapping) {
+                    foreach ($info->role_mappings->mappings as $key => &$mapping) {
                         $mapping->targetroleid = optional_param('mapping'.$key, $mapping->targetroleid, PARAM_INT);
                     }
                     $info->role_mappings->modified = true;
@@ -830,6 +1025,7 @@ class restore_ui_stage_process extends restore_ui_stage {
     /**
      * Renders the process stage screen
      *
+     * @throws restore_ui_exception
      * @param core_backup_renderer $renderer renderer instance to use
      * @return string HTML code
      */
@@ -875,6 +1071,10 @@ class restore_ui_stage_process extends restore_ui_stage {
         return $html;
     }
 
+    /**
+     * Returns true if this stage can have sub-stages.
+     * @return bool|false
+     */
     public function has_sub_stages() {
         return true;
     }
@@ -884,20 +1084,26 @@ class restore_ui_stage_process extends restore_ui_stage {
  * This is the completed stage.
  *
  * Once this is displayed there is nothing more to do.
+ *
+ * @package   core_backup
+ * @copyright 2010 Sam Hemelryk
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class restore_ui_stage_complete extends restore_ui_stage_process {
+
     /**
      * The results of the backup execution
      * @var array
      */
     protected $results;
+
     /**
      * Constructs the complete backup stage
-     * @param backup_ui $ui
-     * @param array|null $params
+     * @param restore_ui $ui
+     * @param array $params
      * @param array $results
      */
-    public function __construct(restore_ui $ui, array $params=null, array $results=null) {
+    public function __construct(restore_ui $ui, array $params = null, array $results = null) {
         $this->results = $results;
         parent::__construct($ui, $params);
         $this->stage = restore_ui::STAGE_COMPLETE;
index ab0a272..4a31e06 100644 (file)
@@ -57,7 +57,8 @@ class behat_backup extends behat_base {
     }
 
     /**
-     * Backups the specified course using the provided options. If you are interested in restoring this backup would be useful to provide a 'Filename' option.
+     * Backups the specified course using the provided options. If you are interested in restoring this backup would be
+     * useful to provide a 'Filename' option.
      *
      * @Given /^I backup "(?P<course_fullname_string>(?:[^"]|\\")*)" course using this options:$/
      * @param string $backupcourse
@@ -195,7 +196,9 @@ class behat_backup extends behat_base {
     }
 
     /**
-     * Restores the backup into the specified course and the provided options. You should be in the 'Restore' page where the backup is.
+     * Restores the backup into the specified course and the provided options.
+     *
+     * You should be in the 'Restore' page where the backup is.
      *
      * @Given /^I restore "(?P<backup_filename_string>(?:[^"]|\\")*)" backup into "(?P<existing_course_fullname_string>(?:[^"]|\\")*)" course using this options:$/
      * @param string $backupfilename
@@ -229,7 +232,9 @@ class behat_backup extends behat_base {
     }
 
     /**
-     * Restores the specified backup into a new course using the provided options. You should be in the 'Restore' page where the backup is.
+     * Restores the specified backup into a new course using the provided options.
+     *
+     * You should be in the 'Restore' page where the backup is.
      *
      * @Given /^I restore "(?P<backup_filename_string>(?:[^"]|\\")*)" backup into a new course using this options:$/
      * @param string $backupfilename
@@ -258,7 +263,9 @@ class behat_backup extends behat_base {
     }
 
     /**
-     * Merges the backup into the current course using the provided restore options. You should be in the 'Restore' page where the backup is.
+     * Merges the backup into the current course using the provided restore options.
+     *
+     * You should be in the 'Restore' page where the backup is.
      *
      * @Given /^I merge "(?P<backup_filename_string>(?:[^"]|\\")*)" backup into the current course using this options:$/
      * @param string $backupfilename
@@ -286,7 +293,9 @@ class behat_backup extends behat_base {
     }
 
     /**
-     * Merges the backup into the current course after deleting this contents, using the provided restore options. You should be in the 'Restore' page where the backup is.
+     * Merges the backup into the current course after deleting this contents, using the provided restore options.
+     *
+     * You should be in the 'Restore' page where the backup is.
      *
      * @Given /^I merge "(?P<backup_filename_string>(?:[^"]|\\")*)" backup into the current course after deleting it's contents using this options:$/
      * @param string $backupfilename
index 9bccb8d..e33c748 100644 (file)
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
+ * Contains user interface tests.
+ *
  * @package   core_backup
- * @category  phpunit
  * @copyright 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
 
-// Include all the needed stuff
+// Include all the needed stuff.
 global $CFG;
 //require_once($CFG->dirroot . '/backup/util/checks/backup_check.class.php');
 
 /**
  * ui tests (all)
+ *
+ * @package   core_backup
+ * @copyright 2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class backup_ui_testcase extends basic_testcase {
 
     /**
-     * test backup_ui class
+     * Test backup_ui class
      */
-    function test_backup_ui() {
+    public function test_backup_ui() {
     }
 }