MDL-33430 Give tasks an access to their current plan's results

This in turn provides access to the plan's results for both structure and
execution steps so they can register something useful there.

backup/util/plan/base_plan.class.php

@@ -75,10 +75,27 @@ public function get_tasks() {
         return $this->tasks;
     }
 
+    /**
+     * Add the passed info to the plan results
+     *
+     * At the moment we expect an associative array structure to be merged into
+     * the current results. In the future, some sort of base_result class may
+     * be introduced.
+     *
+     * @param array $result associative array describing a result of a task/step
+     */
     public function add_result($result) {
+        if (!is_array($result)) {
+            throw new coding_exception('Associative array is expected as a parameter of add_result()');
+        }
         $this->results = array_merge($this->results, $result);
     }
 
+    /**
+     * Return the results collected via {@link self::add_result()} method
+     *
+     * @return array
+     */
     public function get_results() {
         return $this->results;
     }

backup/util/plan/base_task.class.php

@@ -154,7 +154,7 @@ public function execute() {
             // If step returns array, it will be forwarded to plan
             // (TODO: shouldn't be array but proper result object)
             if (is_array($result) and !empty($result)) {
-                $this->plan->add_result($result);
+                $this->add_result($result);
             }
         }
         // Mark as executed if any step has been executed
@@ -191,6 +191,34 @@ public function calculate_checksum() {
                    backup_general_helper::array_checksum_recursive($this->steps));
     }
 
+    /**
+     * Add the given info to the current plan's results.
+     *
+     * @see base_plan::add_result()
+     * @param array $result associative array describing a result of a task/step
+     */
+    public function add_result($result) {
+        if (!is_null($this->plan)) {
+            $this->plan->add_result($result);
+        } else {
+            debugging('Attempting to add a result of a task not binded with a plan', DEBUG_DEVELOPER);
+        }
+    }
+
+    /**
+     * Return the current plan's results
+     *
+     * @return array|null
+     */
+    public function get_results() {
+        if (!is_null($this->plan)) {
+            return $this->plan->get_results();
+        } else {
+            debugging('Attempting to get results of a task not binded with a plan', DEBUG_DEVELOPER);
+            return null;
+        }
+    }
+
 // Protected API starts here
 
     /**