moodle/lib/classes/output/stored_progress_bar.php

<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

namespace core\output;

/**
 * Stored progress bar class.
 *
 * @package    core
 * @copyright  2023 onwards Catalyst IT {@link http://www.catalyst-eu.net/}
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 * @author     Conn Warwicker <conn.warwicker@catalyst-eu.net>
 */
class stored_progress_bar extends progress_bar {

    /** @var bool Can use output buffering. */
    protected static $supportsoutputbuffering = true;

    /** @var bool Flag to indicate the Javascript module has been initialised already. */
    protected static $jsloaded = false;

    /** @var int DB record ID */
    protected $recordid;

    /** @var string|null Message to associate with bar */
    protected $message = null;

    /** @var \core\clock Clock object */
    protected $clock;

    /**
     * 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 The suggested width.
     * @param bool $autostart Whether to start the progress bar right away.
     */
    public function __construct(string $idnumber, int $width = 0, bool $autostart = true) {

        $this->clock = \core\di::get(\core\clock::class);

        // Construct from the parent.
        parent::__construct($idnumber, $width, $autostart);
    }

    /**
     * Just set the timestart, do not render the bar immediately.
     *
     * @return void
     */
    public function create(): void {
        $this->timestart = $this->clock->time();
    }

    /**
     * Load the stored progress bar from the database based on its uniqued idnumber
     *
     * @param string $idnumber Unique ID of the bar
     * @return stored_progress_bar|null
     */
    public static function get_by_idnumber(string $idnumber): ?stored_progress_bar {
        global $DB;

        $record = $DB->get_record('stored_progress', ['idnumber' => $idnumber]);
        if ($record) {
            return self::load($record);
        } else {
            return null;
        }
    }

    /**
     * Load the stored progress bar from the database, based on it's record ID
     *
     * @param int $id Database record ID
     * @return stored_progress_bar|null
     */
    public static function get_by_id(int $id): ?stored_progress_bar {
        global $DB;

        $record = $DB->get_record('stored_progress', ['id' => $id]);
        if ($record) {
            return self::load($record);
        } else {
            return null;
        }
    }

    /**
     * Load the stored progress bar object from its record in the database.
     *
     * @param stdClass $record
     * @return stored_progress_bar
     */
    public static function load(\stdClass $record): stored_progress_bar {
        $progress = new stored_progress_bar($record->idnumber);
        $progress->set_record_id($record->id);
        $progress->set_time_started($record->timestart);
        $progress->set_last_updated($record->lastupdate);
        $progress->set_percent($record->percentcompleted);
        $progress->set_message($record->message);
        $progress->set_haserrored($record->haserrored);
        return $progress;
    }

    /**
     * Set the DB record ID
     *
     * @param int $id
     * @return void
     */
    protected function set_record_id(int $id): void {
        $this->recordid = $id;
    }

    /**
     * Set the time we started the process.
     *
     * @param ?int $value
     * @return void
     */
    protected function set_time_started(?int $value): void {
        $this->timestart = $value;
    }

    /**
     * Set the time we started last updated the progress.
     *
     * @param int|null $value
     * @return void
     */
    protected function set_last_updated(?int $value = null): void {
        $this->lastupdate = $value;
    }

    /**
     * Set the percent completed.
     *
     * @param float|null $value
     * @return void
     */
    protected function set_percent($value = null): void {
        $this->percent = $value;
    }

    /**
     * Set the message.
     *
     * @param string|null $value
     * @return void
     */
    protected function set_message(?string $value = null): void {
        $this->message = $value;
    }

    /**
     * Set that the process running has errored and store that against the bar
     *
     * @param string $errormsg
     * @return void
     */
    public function error(string $errormsg): void {
        // Update the error variables.
        parent::error($errormsg);

        // Update the record.
        $this->update_record();
    }

    /**
     * Get the progress bar message.
     *
     * @return string|null
     */
    public function get_message(): ?string {
        return $this->message;
    }

    /**
     * Initialise Javascript for stored progress bars.
     *
     * The javascript polls the status of all progress bars on the page, so it only needs to be initialised once.
     *
     * @return void
     */
    public function init_js(): void {
        global $PAGE;
        if (self::$jsloaded) {
            return;
        }
        $PAGE->requires->js_call_amd('core/stored_progress', 'init', [
            self::get_timeout(),
        ]);
        self::$jsloaded = true;
    }

    /**
     * Get the content to display the progress bar and start polling via AJAX
     *
     * @return string
     */
    public function get_content(): string {
        global $OUTPUT;

        $this->init_js();

        $context = $this->export_for_template($OUTPUT);
        return $OUTPUT->render_from_template('core/progress_bar', $context);
    }

    /**
     * Export for template.
     *
     * @param  renderer_base $output The renderer.
     * @return array
     */
    public function export_for_template(\renderer_base $output): array {
        $class = 'stored-progress-bar';
        if (empty($this->timestart)) {
            $class .= ' stored-progress-notstarted';
        }
        return [
            'id' => $this->recordid,
            'idnumber' => $this->idnumber,
            'width' => $this->width,
            'class' => $class,
            'value' => $this->percent,
            'message' => $this->message,
            'error' => $this->haserrored,
        ];
    }

    /**
     * Start the recording of the progress and store in the database
     *
     * @return int ID of the DB record
     */
    public function start(): int {
        global $OUTPUT, $DB;

        // If we are running in an non-interactive CLI environment, call the progress bar renderer to avoid warnings
        // when we do an update.
        if (defined('STDOUT') && !stream_isatty(STDOUT)) {
            $OUTPUT->render_progress_bar($this);
        }

        $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->clear_records();
            }
        }

        // Create new progress record.
        $this->recordid = $DB->insert_record('stored_progress', [
            'idnumber' => $this->idnumber,
            'timestart' => (int)$this->timestart,
        ]);

        return $this->recordid;
    }

    /**
     * End the polling progress and delete the DB record.
     *
     * @return void
     */
    protected function clear_records(): void {
        global $DB;

        $DB->delete_records('stored_progress', [
            'idnumber' => $this->idnumber,
        ]);
    }

    /**
     * Update the database record with the percentage and message
     *
     * @param float $percent
     * @param string $msg
     * @return void
     */
    protected function update_raw($percent, $msg): void {
        $this->percent = $percent;
        $this->message = $msg;

        // Update the database record with the new data.
        $this->update_record();

        // Update any CLI script's progress with an ASCII progress bar.
        $this->render_update();
    }

    /**
     * Render an update to the CLI
     *
     * This will only work in CLI scripts, and not in scheduled/adhoc tasks even though they run via CLI,
     * as they seem to use a different renderer (core_renderer instead of core_renderer_cli).
     *
     * We also can't check this based on "CLI_SCRIPT" const as that is true for tasks.
     *
     * So this will just check a flag to see if we want auto rendering of updates.
     *
     * @return void
     */
    protected function render_update(): void {
        global $OUTPUT;

        // If no output buffering, don't render it at all.
        if (defined('NO_OUTPUT_BUFFERING') && NO_OUTPUT_BUFFERING) {
            $this->auto_update(false);
        }

        // If we want the screen to auto update, render it.
        if ($this->autoupdate) {
            echo $OUTPUT->render_progress_bar_update(
                $this->idnumber, $this->percent, $this->message, $this->get_estimate_message($this->percent)
            );
        }
    }

    /**
     * Update the database record
     *
     * @throws \moodle_exception
     * @return void
     */
    protected function update_record(): void {
        global $DB;

        if (is_null($this->recordid)) {
            throw new \moodle_exception('Polling has not been started. Cannot set iteration.');
        }

        // Update time.
        $this->lastupdate = $this->clock->time();

        // Update the database record.
        $record = new \stdClass();
        $record->id = $this->recordid;
        $record->lastupdate = (int)$this->lastupdate;
        $record->percentcompleted = $this->percent;
        $record->message = $this->message;
        $record->haserrored = $this->haserrored;
        $DB->update_record('stored_progress', $record);
    }

    /**
     * We need a way to specify a unique idnumber for processes being monitored, so that
     * firstly we don't accidentally overwrite a running process, and secondly so we can
     * automatically load them in some cases, without having to manually code in its name.
     *
     * So this uses the classname of the object being monitored, along with its id.
     *
     * This method should be used when creating the stored_progress record to set it's idnumber.
     *
     * @param string $class Class name of the object being monitored, e.g. \local_something\task\my_task
     * @param int|null $id ID of an object from database, e.g. 123
     * @return string Converted string, e.g. local_something_task_my_task_123
     */
    public static function convert_to_idnumber(string $class, ?int $id = null): string {
        $idnumber = preg_replace("/[^a-z0-9_]/", "_", ltrim($class, '\\'));
        if (!is_null($id)) {
            $idnumber .= '_' . $id;
        }

        return $idnumber;
    }

    /**
     * Get the polling timeout in seconds. Default: 5.
     *
     * @return int
     */
    public static function get_timeout(): int {
        global $CFG;
        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->clear_records();

        // Create new progress record.
        $this->recordid = $DB->insert_record('stored_progress', [
            'idnumber' => $this->idnumber,
            'timestart' => $this->timestart,
            'message' => '',
        ]);

        return $this->recordid;
    }

}