moodle/grade/classes/penalty_manager.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_grades;

use core\context;
use core\plugininfo\gradepenalty;
use core_plugin_manager;
use grade_grade;
use grade_item;
use moodle_url;
use navigation_node;
use pix_icon;
use settings_navigation;
use stdClass;

/**
 * Manager class for grade penalty.
 *
 * @package   core_grades
 * @copyright 2024 Catalyst IT Australia Pty Ltd
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
class penalty_manager {
    /**
     * List the modules that support the grade penalty feature.
     *
     * @return array list of supported modules.
     */
    public static function get_supported_modules(): array {
        $plugintype = 'mod';
        $mods = \core_component::get_plugin_list($plugintype);
        $supported = [];
        foreach ($mods as $mod => $plugindir) {
            if (plugin_supports($plugintype, $mod, FEATURE_GRADE_HAS_PENALTY)) {
                $supported[] = $mod;
            }
        }
        return $supported;
    }

    /**
     * List the modules that currently have the grade penalty feature enabled.
     *
     * @return array List of enabled modules.
     */
    public static function get_enabled_modules(): array {
        return array_filter(explode(',', get_config('core', 'gradepenalty_enabledmodules')));
    }

    /**
     * Enable the grade penalty feature for a module.
     *
     * @param string $module The module name (e.g. 'assign').
     */
    public static function enable_module(string $module): void {
        self::enable_modules([$module]);
    }

    /**
     * Enable the grade penalty feature for multiple modules.
     *
     * @param array $modules List of module names.
     */
    public static function enable_modules(array $modules): void {
        $result = array_unique(array_merge(self::get_enabled_modules(), $modules));
        set_config('gradepenalty_enabledmodules', implode(',', $result));
    }

    /**
     * Disable the grade penalty feature for a module.
     *
     * @param string $module The module name (e.g. 'assign').
     */
    public static function disable_module(string $module): void {
        self::disable_modules([$module]);
    }

    /**
     * Disable the grade penalty feature for multiple modules.
     *
     * @param array $modules List of module names.
     */
    public static function disable_modules(array $modules): void {
        $result = array_diff(self::get_enabled_modules(), $modules);
        set_config('gradepenalty_enabledmodules', implode(',', $result));
    }

    /**
     * Check if the module has the grade penalty feature enabled.
     *
     * @param string $module The module name (e.g. 'assign').
     * @return bool Whether grade penalties are enabled for the module.
     */
    public static function is_penalty_enabled_for_module(string $module): bool {
        return in_array($module, self::get_enabled_modules());
    }

    /**
     * Whether the grade penalty feature is enabled for a grade.
     *
     * @param grade_grade $grade
     * @return bool
     */
    private static function is_penalty_enabled_for_grade(grade_grade $grade): bool {
        if (empty($grade)) {
            return false;
        }

        $grademin = $grade->get_grade_min();

        // No penalty for minimum grades.
        if ($grade->rawgrade <= $grademin) {
            return false;
        }

        if ($grade->finalgrade <= $grademin) {
            return false;
        }

        // No penalty for overridden grades.
        // We may need a separate setting to allow grade penalties for overridden grades.
        if (!empty($grade->overridden)) {
            return false;
        }

        // No penalty for locked grades.
        if (!empty($grade->locked)) {
            return false;
        }

        return true;
    }

    /**
     * Calculate grade penalties for a user and their grade via the enabled penalty plugins.
     *
     * @param penalty_container $container The penalty container.
     * @return penalty_container The penalty container with the calculated penalties.
     */
    private static function calculate_penalties(penalty_container $container): penalty_container {
        // Iterate through all the penalty plugins to calculate the total penalty.
        foreach (core_plugin_manager::instance()->get_plugins_of_type('gradepenalty') as $pluginname => $plugin) {
            if (gradepenalty::is_plugin_enabled($pluginname)) {
                $classname = "\\gradepenalty_{$pluginname}\\penalty_calculator";
                if (class_exists($classname)) {
                    $classname::calculate_penalty($container);
                }
            }
        }
        // Returning the container is not strictly necessary but makes it clear the container is being modified.
        return $container;
    }

    /**
     * Apply grade penalties to a user.
     *
     * Grade penalties are determined by the enabled penalty plugin.
     * This function should be called each time a module creates or updates a grade item for a user.
     *
     * @param int $userid The user ID
     * @param grade_item $gradeitem grade item
     * @param int $submissiondate submission date
     * @param int $duedate due date
     * @param bool $previewonly do not update the grade if true, only return the penalty
     * @return penalty_container Information about the applied penalty.
     */
    public static function apply_grade_penalty_to_user(
        int $userid,
        grade_item $gradeitem,
        int $submissiondate,
        int $duedate,
        bool $previewonly = false
    ): penalty_container {

        try {
            $container = self::apply_penalty($userid, $gradeitem, $submissiondate, $duedate, $previewonly);
        } catch (\core\exception\moodle_exception $e) {
            debugging($e->getMessage(), DEBUG_DEVELOPER);
        }
        return $container;
    }

    /**
     * Fetch the penalty for a user based on the submission date and due date and deduct marks from the grade item accordingly.
     *
     * @param int $userid The user ID.
     * @param grade_item $gradeitem The grade item.
     * @param int $submissiondate The date and time of the user submission.
     * @param int $duedate The date and time the submission is due.
     * @param bool $previewonly If true, the grade will not be updated.
     * @return penalty_container The penalty container containing information about the applied penalty.
     */
    private static function apply_penalty(
        int $userid,
        grade_item $gradeitem,
        int $submissiondate,
        int $duedate,
        bool $previewonly = false
    ): penalty_container {

        // Get the grade and create a penalty container.
        $grade = $gradeitem->get_grade($userid);
        $container = new penalty_container($gradeitem, $grade, $submissiondate, $duedate);

        // Do not apply penalties if the module is disabled.
        if (!self::is_penalty_enabled_for_module($gradeitem->itemmodule)) {
            return $container;
        }

        // Do not apply penalties if the grade is not eligible.
        if (!self::is_penalty_enabled_for_grade($grade)) {
            return $container;
        }

        // Call all penalty plugins to calculate the penalty.
        $container = self::calculate_penalties($container);

        // Update the grade if not in preview mode.
        if (!$previewonly) {
            // Update the raw grade and store the deducted mark.
            $gradeitem->update_raw_grade($userid, $container->get_grade_after_penalties(), 'gradepenalty');
            $gradeitem->update_deducted_mark($userid, $container->get_penalty());
        }

        return $container;
    }

    /**
     * Returns the penalty indicator HTML code if a penalty is applied to the grade.
     * Otherwise, returns an empty string.
     *
     * @param grade_grade $grade Grade object
     * @return string HTML code for penalty indicator
     */
    public static function show_penalty_indicator(grade_grade $grade): string {
        global $PAGE;

        // Show penalty indicator if penalty is greater than 0.
        if ($grade->is_penalty_applied_to_final_grade()) {
            $indicator = new \core_grades\output\penalty_indicator(2, $grade);
            $renderer = $PAGE->get_renderer('core_grades');
            return $renderer->render_penalty_indicator($indicator);
        }

        return '';
    }

    /**
     * Allow penalty plugin to extend course navigation.
     *
     * @param navigation_node $navigation The navigation node
     * @param stdClass $course The course object
     * @param context $coursecontext The course context
     */
    public static function extend_navigation_course(navigation_node $navigation,
                                                    stdClass $course,
                                                    context $coursecontext): void {
        // Create new navigation node for grade penalty.
        $penaltynav = $navigation->add(get_string('gradepenalty', 'core_grades'),
            new moodle_url('/grade/penalty/view.php', ['contextid' => $coursecontext->id]),
            navigation_node::TYPE_CONTAINER, null, 'gradepenalty', new pix_icon('i/grades', ''));

        // Allow plugins to extend the navigation.
        $pluginfunctions = get_plugin_list_with_function('gradepenalty', 'extend_navigation_course');
        foreach ($pluginfunctions as $plugin => $function) {
            if (gradepenalty::is_plugin_enabled($plugin)) {
                $function($penaltynav, $course, $coursecontext);
            }
        }

        // Do not display the node if there are no children.
        if (!$penaltynav->has_children()) {
            $penaltynav->remove();
        }
    }

    /**
     * Allow penalty plugin to extend navigation module.
     *
     * @param settings_navigation $settings The settings navigation object
     * @param navigation_node $navref The navigation node
     * @return void
     */
    public static function extend_navigation_module(settings_navigation $settings, navigation_node $navref): void {
        $context = $settings->get_page()->context;
        $cm = $settings->get_page()->cm;

        // Create new navigation node for grade penalty.
        $penaltynav = $navref->add(get_string('gradepenalty', 'core_grades'),
            new moodle_url('/grade/penalty/view.php', ['contextid' => $context->id, 'cm' => $cm->id]),
            navigation_node::TYPE_CONTAINER, null, 'gradepenalty', new pix_icon('i/grades', ''));

        // Allow plugins to extend the navigation.
        $pluginfunctions = get_plugin_list_with_function('gradepenalty', 'extend_navigation_module');
        foreach ($pluginfunctions as $plugin => $function) {
            if (gradepenalty::is_plugin_enabled($plugin) && self::is_penalty_enabled_for_module($cm->modname)) {
                $function($penaltynav, $cm);
            }
        }

        // Do not display the node if there are no children.
        if (!$penaltynav->has_children()) {
            $penaltynav->remove();
        }
    }

    /**
     * Recalculate grade penalties
     *
     * @param context $context The context
     * @param int $usermodified The user who triggered the recalculation
     * return void
     */
    public static function recalculate_penalty(context $context, int $usermodified = 0): void {
        if ($usermodified == 0) {
            global $USER;
            $usermodified = $USER->id;
        }

        // Get enabled modules.
        $enabledmodules = self::get_enabled_modules();

        foreach ($enabledmodules as $module) {
            // If it is in a module context, make sure the module is the same as the enabled module.
            if ($context->contextlevel == CONTEXT_MODULE) {
                $cmid = $context->instanceid;
                $cm = get_coursemodule_from_id($module, $cmid);
                if (empty($cm)) {
                    continue;
                }
            }

            // Check if the module supports has penalty recalculator class.
            $classname = "\\mod_{$module}\\penalty_recalculator";
            if (class_exists($classname)) {
                $classname::recalculate_penalty($context, $usermodified);
            }
        }
    }
}