Proyectos de Subversion Moodle

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

declare(strict_types = 1);

namespace core_completion;

use cm_info;

use coding_exception;

use moodle_exception;

/**

 * Base class for defining an activity module's custom completion rules.

 *

 * Class for defining an activity module's custom completion rules and fetching the completion statuses

 * of the custom completion rules for a given module instance and a user.

 *

 * @package   core_completion

 * @copyright 2021 Jun Pataleta <jun@moodle.com>

 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

abstract class activity_custom_completion {

    /** @var cm_info The course module information object. */

    protected $cm;

    /** @var int The user's ID. */

    protected $userid;

    /** @var array The current state of core completion */

    protected $completionstate;

    /**

     * activity_custom_completion constructor.

     *

     * @param cm_info $cm

     * @param int $userid

     * @param array|null $completionstate The current state of the core completion criteria

     */

    public function __construct(cm_info $cm, int $userid, ?array $completionstate = null) {

        $this->cm = $cm;

        $this->userid = $userid;

        $this->completionstate = $completionstate;

    }

    /**

     * Validates that the custom rule is defined by this plugin and is enabled for this activity instance.

     *

     * @param string $rule The custom completion rule.

     */

    public function validate_rule(string $rule): void {

        // Check that this custom completion rule is defined.

        if (!$this->is_defined($rule)) {

            throw new coding_exception("Undefined custom completion rule '$rule'");

        }

        // Check that this custom rule is included in the course module's custom completion rules.

        if (!$this->is_available($rule)) {

            throw new moodle_exception("Custom completion rule '$rule' is not used by this activity.");

        }

    }

    /**

     * Whether this module defines this custom rule.

     *

     * @param string $rule The custom completion rule.

     * @return bool

     */

    public function is_defined(string $rule): bool {

        return in_array($rule, static::get_defined_custom_rules());

    }

    /**

     * Checks whether the custom completion rule is being used by the activity module instance.

     *

     * @param string $rule The custom completion rule.

     * @return bool

     */

    public function is_available(string $rule): bool {

        return in_array($rule, $this->get_available_custom_rules());

    }

    /**

     * Fetches the list of custom completion rules that are being used by this activity module instance.

     *

     * @return array

     */

    public function get_available_custom_rules(): array {

        $rules = static::get_defined_custom_rules();

        $availablerules = [];

        $customdata = (array)$this->cm->customdata;

        foreach ($rules as $rule) {

            $customrule = $customdata['customcompletionrules'][$rule] ?? false;

            if (!empty($customrule)) {

                $availablerules[] = $rule;

            }

        }

        return $availablerules;

    }

    /**

     * Fetches the overall completion status of this activity instance for a user based on its available custom completion rules.

     *

     * @return int The completion state (e.g. COMPLETION_COMPLETE, COMPLETION_INCOMPLETE, COMPLETION_COMPLETE_FAIL).

     */

    public function get_overall_completion_state(): int {

        $iscompletefail = false;

        foreach ($this->get_available_custom_rules() as $rule) {

            $state = $this->get_state($rule);

            // Return early if one of the custom completion rules is not yet complete.

            if ($state == COMPLETION_INCOMPLETE) {

                return $state;

            }

            if (!$iscompletefail) {

                $iscompletefail = ($state === COMPLETION_COMPLETE_FAIL || $state === COMPLETION_COMPLETE_FAIL_HIDDEN);

            }

        }

        if ($iscompletefail) {

            return COMPLETION_COMPLETE_FAIL;

        }

        // If this was reached, then all custom rules have been marked complete.

        return COMPLETION_COMPLETE;

    }

    /**

     * Fetches the description for a given custom completion rule.

     *

     * @param string $rule The custom completion rule.

     * @return string

     */

    public function get_custom_rule_description(string $rule): string {

        $descriptions = $this->get_custom_rule_descriptions();

        if (!isset($descriptions[$rule])) {

            // Lang string not found for this custom completion rule. Just return it.

            return $rule;

        }

        return $descriptions[$rule];

    }

    /**

     * Show the manual completion or not regardless of the course's showcompletionconditions setting.

     * Returns false by default for plugins that don't need to override the course's showcompletionconditions setting.

     * Activity plugins that need to always show manual completion need to override this function.

     *

     * @return bool

     */

    public function manual_completion_always_shown(): bool {

        return false;

    }

    /**

     * Fetches the module's custom completion class implementation if it's available.

     *

     * @param string $modname The activity module name. Usually from cm_info::modname.

     * @return string|null

     */

    public static function get_cm_completion_class(string $modname): ?string {

        $cmcompletionclass = "mod_{$modname}\\completion\\custom_completion";

        if (class_exists($cmcompletionclass) && is_subclass_of($cmcompletionclass, self::class)) {

            return $cmcompletionclass;

        }

        return null;

    }

    /**

     * Fetches the completion state for a given completion rule.

     *

     * @param string $rule The completion rule.

     * @return int The completion state.

     */

    abstract public function get_state(string $rule): int;

    /**

     * Fetch the list of custom completion rules that this module defines.

     *

     * @return array

     */

    abstract public static function get_defined_custom_rules(): array;

    /**

     * Returns an associative array of the descriptions of custom completion rules.

     *

     * @return array

     */

    abstract public function get_custom_rule_descriptions(): array;

    /**

     * Returns an array of all completion rules, in the order they should be displayed to users.

     *

     * @return array

     */

    abstract public function get_sort_order(): array;

}