locallib.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/>.

use assignsubmission_dta\dta_db_utils;
use assignsubmission_dta\dta_backend_utils;
use assignsubmission_dta\dta_view_submission_utils;
use assignsubmission_dta\models\dta_result;
use assignsubmission_dta\models\dta_result_summary;
use assignsubmission_dta\models\dta_recommendation;

/**
 * Library class for DTA submission plugin extending assign submission plugin base class.
 *
 * @package    assignsubmission_dta
 * @copyright  2023 Your Name or Organization
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
class assign_submission_dta extends assign_submission_plugin {

    /**
     * Broadly used in logic, parametrized for easier change.
     */
    public const ASSIGNSUBMISSION_DTA_COMPONENT_NAME = 'assignsubmission_dta';

    /**
     * Draft file area for DTA tests to be uploaded by the teacher.
     */
    public const ASSIGNSUBMISSION_DTA_DRAFT_FILEAREA_TEST = 'tests_draft_dta';

    /**
     * File area for DTA tests to be uploaded by the teacher.
     */
    public const ASSIGNSUBMISSION_DTA_FILEAREA_TEST = 'tests_dta';

    /**
     * File area for DTA submission assignment.
     */
    public const ASSIGNSUBMISSION_DTA_FILEAREA_SUBMISSION = 'submissions_dta';

    /**
     * Get plugin name.
     *
     * @return string
     */
    public function assignsubmission_dta_get_name(): string {
        return get_string('pluginname', self::ASSIGNSUBMISSION_DTA_COMPONENT_NAME);
    }

    /**
     * Get default settings for assignment submission settings.
     *
     * @param MoodleQuickForm $mform Form to add elements to.
     * @return void
     */
    public function assignsubmission_dta_get_settings(MoodleQuickForm $mform): void {
        // Add draft filemanager to form.
        $mform->addElement(
            'filemanager',
            self::ASSIGNSUBMISSION_DTA_DRAFT_FILEAREA_TEST,
            get_string(
                'submission_settings_label',
                self::ASSIGNSUBMISSION_DTA_COMPONENT_NAME
            ),
            null,
            $this->get_file_options(true)
        );

        // Add help button to added filemanager.
        $mform->addHelpButton(
            // Form-unique element id to which to add button.
            self::ASSIGNSUBMISSION_DTA_DRAFT_FILEAREA_TEST,
            // Key.
            'submission_settings_label',
            // Language file to use.
            self::ASSIGNSUBMISSION_DTA_COMPONENT_NAME
        );

        // Only show filemanager if plugin is enabled.
        $mform->hideIf(
            // Form-unique element id to hide.
            self::ASSIGNSUBMISSION_DTA_DRAFT_FILEAREA_TEST,
            // Condition to check.
            self::ASSIGNSUBMISSION_DTA_COMPONENT_NAME . '_enabled',
            // State to match for hiding.
            'notchecked'
        );
    }

    /**
     * Allows the plugin to update the default values passed into
     * the settings form (needed to set up draft areas for editor
     * and filemanager elements).
     *
     * @param array $defaultvalues Default values to update.
     */
    public function data_preprocessing(&$defaultvalues): void {
        // Get id of draft area for file manager creation.
        $draftitemid = file_get_submitted_draft_itemid(
            self::ASSIGNSUBMISSION_DTA_DRAFT_FILEAREA_TEST
        );

        // Prepare draft area with created draft filearea.
        file_prepare_draft_area(
            $draftitemid,
            $this->assignment->get_context()->id,
            self::ASSIGNSUBMISSION_DTA_COMPONENT_NAME,
            self::ASSIGNSUBMISSION_DTA_FILEAREA_TEST,
            0,
            ['subdirs' => 0]
        );

        $defaultvalues[self::ASSIGNSUBMISSION_DTA_DRAFT_FILEAREA_TEST] = $draftitemid;
    }

    /**
     * Save settings of assignment submission settings.
     *
     * @param stdClass $data Form data.
     * @return bool
     */
    public function assignsubmission_dta_save_settings(stdClass $data): bool {
        // If the assignment has no filemanager for our plugin, just leave.
        $draftfilemanagerid = self::ASSIGNSUBMISSION_DTA_DRAFT_FILEAREA_TEST;
        if (!isset($data->$draftfilemanagerid)) {
            return true;
        }

        // Store files from draft filearea to final one.
        file_save_draft_area_files(
            // Form-unique element id of draft filemanager from the edit.
            $data->$draftfilemanagerid,
            // Id of the assignment in edit.
            $this->assignment->get_context()->id,
            self::ASSIGNSUBMISSION_DTA_COMPONENT_NAME,
            self::ASSIGNSUBMISSION_DTA_FILEAREA_TEST,
            0
        );

        // Get files from proper filearea.
        $fs = get_file_storage();
        $files = $fs->get_area_files(
            // Id of the current assignment.
            $this->assignment->get_context()->id,
            self::ASSIGNSUBMISSION_DTA_COMPONENT_NAME,
            self::ASSIGNSUBMISSION_DTA_FILEAREA_TEST,
            0,
            'id',
            false
        );

        // Check if a file was uploaded.
        if (empty($files)) {
            \core\notification::error(
                get_string('no_testfile_warning', self::ASSIGNSUBMISSION_DTA_COMPONENT_NAME)
            );
            return true;
        }

        // Get the file.
        $file = reset($files);

        // Send file to backend.
        return dta_backend_utils::assignsubmission_dta_send_testconfig_to_backend(
            $this->assignment,
            $file
        );
    }

    /**
     * Add elements to submission form.
     *
     * @param stdClass|null $submissionorgrade Submission or grade to show in the form.
     * @param MoodleQuickForm $mform Form for adding elements.
     * @param stdClass $data Data for filling the elements.
     * @param int $userid Current user.
     * @return bool True if form elements added.
     */
    public function get_form_elements_for_user(
        $submissionorgrade,
        MoodleQuickForm $mform,
        stdClass $data,
        $userid
    ): bool {
        // Prepare submission filearea.
        $data = file_prepare_standard_filemanager(
            $data,
            'tasks',
            $this->get_file_options(false),
            $this->assignment->get_context(),
            self::ASSIGNSUBMISSION_DTA_COMPONENT_NAME,
            self::ASSIGNSUBMISSION_DTA_FILEAREA_SUBMISSION,
            $submissionorgrade ? $submissionorgrade->id : 0
        );

        // Add filemanager to form.
        $mform->addElement(
            'filemanager',
            // Form-unique identifier.
            'tasks_filemanager',
            // Label to show next to the filemanager.
            get_string('submission_label', self::ASSIGNSUBMISSION_DTA_COMPONENT_NAME),
            null,
            $this->get_file_options(false)
        );

        // Add help button.
        $mform->addHelpButton(
            'tasks_filemanager',
            'submission_label',
            self::ASSIGNSUBMISSION_DTA_COMPONENT_NAME
        );

        return true;
    }

    /**
     * Determines if a submission file area contains any files.
     *
     * @param stdClass $submission Submission to check.
     * @return bool True if file count is zero.
     */
    public function assignsubmission_dta_is_empty(stdClass $submission): bool {
        return ($this->assignsubmission_dta_count_files(
            $submission->id,
            self::ASSIGNSUBMISSION_DTA_FILEAREA_SUBMISSION
        ) === 0);
    }

    /**
     * Counts the number of files in a filearea.
     *
     * @param int $submissionid Submission id to check.
     * @param string $areaid Filearea id to count.
     * @return int Number of files submitted in the filearea.
     */
    private function assignsubmission_dta_count_files(int $submissionid, $areaid): int {
        $fs = get_file_storage();
        $files = $fs->get_area_files(
            $this->assignment->get_context()->id,
            self::ASSIGNSUBMISSION_DTA_COMPONENT_NAME,
            $areaid,
            $submissionid,
            'id',
            false
        );

        return count($files);
    }

    /**
     * Save data to the database.
     *
     * @param stdClass $submission Submission object.
     * @param stdClass $data Data from the form.
     * @return bool True if saved successfully.
     */
    public function save(stdClass $submission, stdClass $data): bool {
        $data = file_postupdate_standard_filemanager(
            $data,
            'tasks',
            $this->get_file_options(false),
            $this->assignment->get_context(),
            self::ASSIGNSUBMISSION_DTA_COMPONENT_NAME,
            self::ASSIGNSUBMISSION_DTA_FILEAREA_SUBMISSION,
            $submission->id
        );

        // If submission is empty, leave directly.
        if ($this->assignsubmission_dta_is_empty($submission)) {
            return true;
        }

        // Get submitted files.
        $fs = get_file_storage();
        $files = $fs->get_area_files(
            $this->assignment->get_context()->id,
            self::ASSIGNSUBMISSION_DTA_COMPONENT_NAME,
            self::ASSIGNSUBMISSION_DTA_FILEAREA_SUBMISSION,
            $submission->id,
            'id',
            false
        );

        // Check if a file is uploaded.
        if (empty($files)) {
            \core\notification::error(
                get_string('no_submissionfile_warning', self::ASSIGNSUBMISSION_DTA_COMPONENT_NAME)
            );
            return true;
        }

        // Get the file.
        $file = reset($files);

        // Send file to backend (split across lines to avoid exceeding length).
        $response = \assignsubmission_dta\dta_backend_utils::
            assignsubmission_dta_send_submission_to_backend(
                $this->assignment,
                $submission->id,
                $file
            );

        // With a null response, return an error.
        if (is_null($response)) {
            return false;
        }

        // Convert received JSON to valid class instances.
        $resultsummary = dta_result_summary::assignsubmission_dta_decode_json($response);

        // Decode recommendations from response.
        $recommendations = dta_recommendation::assignsubmission_dta_decode_json_recommendations($response);

        // Use Moodle debugging instead of error_log/print_r.
        debugging('Recommendations: ' . json_encode($recommendations), DEBUG_DEVELOPER);

        // Persist new results to database (split long lines).
        dta_db_utils::assignsubmission_dta_store_result_summary_to_database(
            $this->assignment->get_instance()->id,
            $submission->id,
            $resultsummary
        );

        // Store the array of recommendations in the database.
        dta_db_utils::assignsubmission_dta_store_recommendations_to_database(
            $this->assignment->get_instance()->id,
            $submission->id,
            $recommendations
        );

        return true;
    }

    /**
     * Display a short summary of the test results of the submission.
     *
     * @param stdClass $submission Submission to show.
     * @param bool $showviewlink Whether to show expand option.
     * @return string Summary results HTML.
     */
    public function view_summary(stdClass $submission, &$showviewlink): string {
        $showviewlink = true;
        return dta_view_submission_utils::assignsubmission_dta_generate_summary_html(
            $this->assignment->get_instance()->id,
            $submission->id
        );
    }

    /**
     * Display detailed results.
     *
     * @param stdClass $submission The submission for which to show results.
     * @return string Detailed results HTML.
     */
    public function view(stdClass $submission): string {
        return dta_view_submission_utils::assignsubmission_dta_generate_detail_html(
            $this->assignment->get_instance()->id,
            $submission->id
        );
    }

    /**
     * Generate array of allowed file types to upload.
     *
     * @param bool $settings Whether this is for assignment settings or active submission.
     * @return array
     */
    private function get_file_options(bool $settings): array {
        $fileoptions = [
            'subdirs' => 0,
            'maxfiles' => 1,
            'accepted_types' => (
                $settings
                ? ['.txt']
                : [
                    '.txt',
                    '.zip',
                ]
            ),
            'return_types' => FILE_INTERNAL,
        ];
        return $fileoptions;
    }

    /**
     * Get file areas returns a list of areas this plugin stores files.
     *
     * @return array An array of fileareas (keys) and descriptions (values).
     */
    public function get_file_areas(): array {
        return [
            self::ASSIGNSUBMISSION_DTA_FILEAREA_SUBMISSION =>
                get_string('dta_submissions_fa', self::ASSIGNSUBMISSION_DTA_COMPONENT_NAME),
            self::ASSIGNSUBMISSION_DTA_FILEAREA_TEST =>
                get_string('dta_tests_fa', self::ASSIGNSUBMISSION_DTA_COMPONENT_NAME),
        ];
    }

    /**
     * Produce a list of files suitable for export that represent this feedback or submission.
     *
     * @param stdClass $submission The submission object.
     * @param stdClass $user The user record (unused).
     * @return array An array of files indexed by filename.
     */
    public function get_files(stdClass $submission, stdClass $user): array {
        $result = [];
        $fs = get_file_storage();
        $files = $fs->get_area_files(
            $this->assignment->get_context()->id,
            self::ASSIGNSUBMISSION_DTA_COMPONENT_NAME,
            self::ASSIGNSUBMISSION_DTA_FILEAREA_SUBMISSION,
            $submission->id,
            'timemodified',
            false
        );

        foreach ($files as $fileobj) {
            // Do we return the full folder path or just the file name?
            if (isset($submission->exportfullpath) && $submission->exportfullpath === false) {
                $result[$fileobj->get_filename()] = $fileobj;
            } else {
                $result[$fileobj->get_filepath() . $fileobj->get_filename()] = $fileobj;
            }
        }
        return $result;
    }

    /**
     * The plugin is being uninstalled - cleanup.
     *
     * @return bool
     */
    public function delete_instance(): bool {
        dta_db_utils::assignsubmission_dta_uninstall_plugin_cleaup();
        return true;
    }
}