MDL-81714 output: Update stored progress bar APIs

Expand the methods available in the stored_progress_bar output component
and stored_progress_task_trait to allow a progress bar to be created in
a "pending" state before the associated task is executed.

Author: marxjohnson

lib/classes/stored_progress_bar.php

@@ -38,11 +38,25 @@ class stored_progress_bar extends \progress_bar {
     /**
      * This overwrites the progress_bar::__construct method.
      *
+     * The stored progress bar does not need to check NO_OUTPUT_BUFFERING since it outputs to the page
+     * then polls for updates asynchronously, rather than waiting for synchronous updates in later output.
+     *
      * @param string $idnumber
+     * @param int $width
+     * @param bool $autostart
      */
-    public function __construct($idnumber) {
-        // Construct from the parent.
-        parent::__construct($idnumber, 0, true);
+    public function __construct(string $idnumber, int $width = 0, bool $autostart = true) {
+        if (!empty($idnumber)) {
+            $this->idnumber  = $idnumber;
+        } else {
+            $this->idnumber  = 'pbar_'.uniqid();
+        }
+
+        $this->width = $width;
+
+        if ($autostart) {
+            $this->create();
+        }
     }
 
     /**
@@ -118,10 +132,10 @@ protected function set_record_id(int $id): void {
     /**
      * Set the time we started the process.
      *
-     * @param int $value
+     * @param ?int $value
      * @return void
      */
-    protected function set_time_started(int $value): void {
+    protected function set_time_started(?int $value): void {
         $this->timestart = $value;
     }
 
@@ -219,8 +233,19 @@ public function export_for_template(\renderer_base $output): array {
     public function start(): int {
         global $DB;
 
-        // Delete any existing records for this.
-        $this->end();
+        $record = $DB->get_record('stored_progress', ['idnumber' => $this->idnumber]);
+        if ($record) {
+            if ($record->timestart == 0) {
+                // Set the timestart now and return.
+                $record->timestart = $this->timestart;
+                $DB->update_record('stored_progress', $record);
+                $this->recordid = $record->id;
+                return $this->recordid;
+            } else {
+                // Delete any existing records for this.
+                $this->end();
+            }
+        }
 
         // Create new progress record.
         $this->recordid = $DB->insert_record('stored_progress', [
@@ -359,4 +384,25 @@ public static function get_timeout(): int {
         return $CFG->progresspollinterval ?? 5;
     }
 
+    /**
+     * Store a progress bar record in a pending state.
+     *
+     * @return int ID of the DB record
+     */
+    public function store_pending(): int {
+        global $DB;
+
+        // Delete any existing records for this.
+        $this->end();
+
+        // Create new progress record.
+        $this->recordid = $DB->insert_record('stored_progress', [
+            'idnumber' => $this->idnumber,
+            'timestart' => $this->timestart,
+            'message' => 'Task pending',
+        ]);
+
+        return $this->recordid;
+    }
+
 }

lib/classes/task/stored_progress_task_trait.php

@@ -16,6 +16,10 @@
 
 namespace core\task;
 
+use core\progress\db_updater;
+use core\progress\stored;
+use core\stored_progress_bar;
+
 /**
  * Trait to use in tasks to automatically add stored progress functionality.
  *
@@ -26,9 +30,44 @@
  */
 trait stored_progress_task_trait {
 
-    /** @var \core\stored_progress_bar|null $progress */
+    /** @var ?\core\stored_progress_bar $progress */
     protected $progress = null;
 
+    /**
+     * Construct a unique name for the progress bar.
+     *
+     * For adhoc tasks, this will need the ID in it. For scheduled tasks just the class name.
+     *
+     * @return string
+     */
+    protected function get_progress_name(): string {
+        if (method_exists($this, 'get_id')) {
+            return get_class($this) . '_' . $this->get_id();
+        } else {
+            return get_class($this);
+        }
+    }
+
+    /**
+     * Initialise a stored progress record.
+     */
+    public function initialise_stored_progress(): void {
+        $this->progress = new \core\stored_progress_bar(
+            \core\stored_progress_bar::convert_to_idnumber($this->get_progress_name()),
+            autostart: false,
+        );
+        $this->progress->store_pending();
+    }
+
+    /**
+     * Get a db_updater object for the stored progress record.
+     *
+     * @return stored
+     */
+    public function get_progress(): stored {
+        return new stored($this->progress);
+    }
+
     /**
      * Start a stored progress bar implementation for the task this trait is used in.
      *
@@ -40,16 +79,8 @@ protected function start_stored_progress(): void {
         // To get around the issue in MDL-80770, we are manually setting the renderer to cli.
         $OUTPUT = $PAGE->get_renderer('core', null, 'cli');
 
-        // Construct a unique name for the progress bar.
-        // For adhoc tasks, this will need the ID in it. For scheduled tasks just the class name.
-        if (method_exists($this, 'get_id')) {
-            $name = get_class($this) . '_' . $this->get_id();
-        } else {
-            $name = get_class($this);
-        }
-
         $this->progress = new \core\stored_progress_bar(
-            \core\stored_progress_bar::convert_to_idnumber($name)
+            \core\stored_progress_bar::convert_to_idnumber($this->get_progress_name())
         );
 
         // Start the progress.

lib/templates/progress_bar.mustache

@@ -31,7 +31,7 @@
     </div>
     <div class="d-flex">
         <div style="flex: 1 1 0; min-width: 0;">
-            <div id="{{idnumber}}_status" class="text-truncate">&nbsp;</div>
+            <div id="{{idnumber}}_status" class="text-truncate">{{message}}</div>
         </div>
         <div class="text-right pl-3" style="flex: 0 0 content">
             <span id="{{idnumber}}_estimate" class="">&nbsp;</span>