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

/**
 * Class for loading/storing competencies from the DB.
 *
 * @package    core_competency
 * @copyright  2015 Damyon Wiese
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
namespace core_competency;
defined('MOODLE_INTERNAL') || die();

use coding_exception;
use context_system;
use lang_string;
use stdClass;

require_once($CFG->libdir . '/grade/grade_scale.php');

/**
 * Class for loading/storing competencies from the DB.
 *
 * @copyright  2015 Damyon Wiese
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
class competency extends persistent {

    const TABLE = 'competency';

    /** Outcome none. */
    const OUTCOME_NONE = 0;
    /** Outcome evidence. */
    const OUTCOME_EVIDENCE = 1;
    /** Outcome complete. */
    const OUTCOME_COMPLETE = 2;
    /** Outcome recommend. */
    const OUTCOME_RECOMMEND = 3;

    /** @var competency Object before update. */
    protected $beforeupdate = null;

    /**
     * Return the definition of the properties of this model.
     *
     * @return array
     */
    protected static function define_properties() {
        return array(
            'shortname' => array(
                'type' => PARAM_TEXT
            ),
            'idnumber' => array(
                'type' => PARAM_RAW
            ),
            'description' => array(
                'default' => '',
                'type' => PARAM_CLEANHTML
            ),
            'descriptionformat' => array(
                'choices' => array(FORMAT_HTML, FORMAT_MOODLE, FORMAT_PLAIN, FORMAT_MARKDOWN),
                'type' => PARAM_INT,
                'default' => FORMAT_HTML
            ),
            'sortorder' => array(
                'default' => 0,
                'type' => PARAM_INT
            ),
            'parentid' => array(
                'default' => 0,
                'type' => PARAM_INT
            ),
            'path' => array(
                'default' => '/0/',
                'type' => PARAM_RAW
            ),
            'ruleoutcome' => array(
                'choices' => array(self::OUTCOME_NONE, self::OUTCOME_EVIDENCE, self::OUTCOME_COMPLETE, self::OUTCOME_RECOMMEND),
                'default' => self::OUTCOME_NONE,
                'type' => PARAM_INT
            ),
            'ruletype' => array(
                'type' => PARAM_RAW,
                'default' => null,
                'null' => NULL_ALLOWED
            ),
            'ruleconfig' => array(
                'default' => null,
                'type' => PARAM_RAW,
                'null' => NULL_ALLOWED
            ),
            'scaleid' => array(
                'default' => null,
                'type' => PARAM_INT,
                'null' => NULL_ALLOWED
            ),
            'scaleconfiguration' => array(
                'default' => null,
                'type' => PARAM_RAW,
                'null' => NULL_ALLOWED
            ),
            'competencyframeworkid' => array(
                'default' => 0,
                'type' => PARAM_INT
            ),
        );
    }

    /**
     * Hook to execute before validate.
     *
     * @return void
     */
    protected function before_validate() {
        $this->beforeupdate = null;
        $this->newparent = null;

        // During update.
        if ($this->get('id')) {
            $this->beforeupdate = new competency($this->get('id'));

            // The parent ID has changed.
            if ($this->beforeupdate->get('parentid') != $this->get('parentid')) {
                $this->newparent = $this->get_parent();

                // Update path and sortorder.
                $this->set_new_path($this->newparent);
                $this->set_new_sortorder();
            }

        } else {
            // During create.

            $this->set_new_path();
            // Always generate new sortorder when we create new competency.
            $this->set_new_sortorder();

        }
    }

    /**
     * Hook to execute after an update.
     *
     * @param bool $result Whether or not the update was successful.
     * @return void
     */
    protected function after_update($result) {
        global $DB;

        if (!$result) {
            $this->beforeupdate = null;
            return;
        }

        // The parent ID has changed, we need to fix all the paths of the children.
        if ($this->beforeupdate->get('parentid') != $this->get('parentid')) {
            $beforepath = $this->beforeupdate->get('path') . $this->get('id') . '/';

            $like = $DB->sql_like('path', '?');
            $likesearch = $DB->sql_like_escape($beforepath) . '%';

            $table = '{' . self::TABLE . '}';
            $sql = "UPDATE $table SET path = REPLACE(path, ?, ?) WHERE " . $like;
            $DB->execute($sql, array(
                $beforepath,
                $this->get('path') . $this->get('id') . '/',
                $likesearch
            ));

            // Resolving sortorder holes left after changing parent.
            $table = '{' . self::TABLE . '}';
            $sql = "UPDATE $table SET sortorder = sortorder -1 "
                    . " WHERE  competencyframeworkid = ? AND parentid = ? AND sortorder > ?";
            $DB->execute($sql, array($this->get('competencyframeworkid'),
                                        $this->beforeupdate->get('parentid'),
                                        $this->beforeupdate->get('sortorder')
                                    ));
        }

        $this->beforeupdate = null;
    }


    /**
     * Hook to execute after a delete.
     *
     * @param bool $result Whether or not the delete was successful.
     * @return void
     */
    protected function after_delete($result) {
        global $DB;
        if (!$result) {
            return;
        }

        // Resolving sortorder holes left after delete.
        $table = '{' . self::TABLE . '}';
        $sql = "UPDATE $table SET sortorder = sortorder -1  WHERE  competencyframeworkid = ? AND parentid = ? AND sortorder > ?";
        $DB->execute($sql, array($this->get('competencyframeworkid'), $this->get('parentid'), $this->get('sortorder')));
    }

    /**
     * Extracts the default grade from the scale configuration.
     *
     * Returns an array where the first element is the grade, and the second
     * is a boolean representing whether or not this grade is considered 'proficient'.
     *
     * @return array(int grade, bool proficient)
     */
    public function get_default_grade() {
        $scaleid = $this->get('scaleid');
        $scaleconfig = $this->get('scaleconfiguration');
        if ($scaleid === null) {
            $scaleconfig = $this->get_framework()->get('scaleconfiguration');
        }
        return competency_framework::get_default_grade_from_scale_configuration($scaleconfig);
    }

    /**
     * Get the competency framework.
     *
     * @return competency_framework
     */
    public function get_framework() {
        return new competency_framework($this->get('competencyframeworkid'));
    }

    /**
     * Get the competency level.
     *
     * @return int
     */
    public function get_level() {
        $path = $this->get('path');
        $path = trim($path, '/');
        return substr_count($path, '/') + 1;
    }

    /**
     * Return the parent competency.
     *
     * @return null|competency
     */
    public function get_parent() {
        $parentid = $this->get('parentid');
        if (!$parentid) {
            return null;
        }
        return new competency($parentid);
    }

    /**
     * Extracts the proficiency of a grade from the scale configuration.
     *
     * @param int $grade The grade (scale item ID).
     * @return array(int grade, bool proficient)
     */
    public function get_proficiency_of_grade($grade) {
        $scaleid = $this->get('scaleid');
        $scaleconfig = $this->get('scaleconfiguration');
        if ($scaleid === null) {
            $scaleconfig = $this->get_framework()->get('scaleconfiguration');
        }
        return competency_framework::get_proficiency_of_grade_from_scale_configuration($scaleconfig, $grade);
    }

    /**
     * Return the related competencies.
     *
     * @return competency[]
     */
    public function get_related_competencies() {
        return related_competency::get_related_competencies($this->get('id'));
    }

    /**
     * Get the rule object.
     *
     * @return null|competency_rule
     */
    public function get_rule_object() {
        $rule = $this->get('ruletype');

        if (!$rule || !is_subclass_of($rule, 'core_competency\\competency_rule')) {
            // Double check that the rule is extending the right class to avoid bad surprises.
            return null;
        }

        return new $rule($this);
    }

    /**
     * Return the scale.
     *
     * @return \grade_scale
     */
    public function get_scale() {
        $scaleid = $this->get('scaleid');
        if ($scaleid === null) {
            return $this->get_framework()->get_scale();
        }
        $scale = \grade_scale::fetch(array('id' => $scaleid));
        $scale->load_items();
        return $scale;
    }

    /**
     * Returns true when the competency has user competencies.
     *
     * This is useful to determine if the competency, or part of it, should be locked down.
     *
     * @return boolean
     */
    public function has_user_competencies() {
        return user_competency::has_records_for_competency($this->get('id')) ||
            user_competency_plan::has_records_for_competency($this->get('id'));
    }

    /**
     * Check if the competency is the parent of passed competencies.
     *
     * @param  array $ids IDs of supposedly direct children.
     * @return boolean
     */
    public function is_parent_of(array $ids) {
        global $DB;

        list($insql, $params) = $DB->get_in_or_equal($ids, SQL_PARAMS_NAMED);
        $params['parentid'] = $this->get('id');

        return $DB->count_records_select(self::TABLE, "id $insql AND parentid = :parentid", $params) == count($ids);
    }

    /**
     * Reset the rule.
     *
     * @return void
     */
    public function reset_rule() {
        $this->raw_set('ruleoutcome', static::OUTCOME_NONE);
        $this->raw_set('ruletype', null);
        $this->raw_set('ruleconfig', null);
    }

    /**
     * Helper method to set the path.
     *
     * @param competency $parent The parent competency object.
     * @return void
     */
    protected function set_new_path(competency $parent = null) {
        $path = '/0/';
        if ($this->get('parentid')) {
            $parent = $parent !== null ? $parent : $this->get_parent();
            $path = $parent->get('path') . $this->get('parentid') . '/';
        }
        $this->raw_set('path', $path);
    }

    /**
     * Helper method to set the sortorder.
     *
     * @return void
     */
    protected function set_new_sortorder() {
        $search = array('parentid' => $this->get('parentid'), 'competencyframeworkid' => $this->get('competencyframeworkid'));
        $this->raw_set('sortorder', $this->count_records($search));
    }

    /**
     * This does a specialised search that finds all nodes in the tree with matching text on any text like field,
     * and returns this node and all its parents in a displayable sort order.
     *
     * @param string $searchtext The text to search for.
     * @param int $competencyframeworkid The competency framework to limit the search.
     * @return persistent[]
     */
    public static function search($searchtext, $competencyframeworkid) {
        global $DB;

        $like1 = $DB->sql_like('shortname', ':like1', false);
        $like2 = $DB->sql_like('idnumber', ':like2', false);
        $like3 = $DB->sql_like('description', ':like3', false);

        $params = array(
            'like1' => '%' . $DB->sql_like_escape($searchtext) . '%',
            'like2' => '%' . $DB->sql_like_escape($searchtext) . '%',
            'like3' => '%' . $DB->sql_like_escape($searchtext) . '%',
            'frameworkid' => $competencyframeworkid
        );

        $sql = 'competencyframeworkid = :frameworkid AND ((' . $like1 . ') OR (' . $like2 . ') OR (' . $like3 . '))';
        $records = $DB->get_records_select(self::TABLE, $sql, $params, 'path, sortorder ASC', '*');

        // Now get all the parents.
        $parents = array();
        foreach ($records as $record) {
            $split = explode('/', trim($record->path, '/'));
            foreach ($split as $parent) {
                $parents[intval($parent)] = true;
            }
        }
        $parents = array_keys($parents);

        // Skip ones we already fetched.
        foreach ($parents as $idx => $parent) {
            if ($parent == 0 || isset($records[$parent])) {
                unset($parents[$idx]);
            }
        }

        if (count($parents)) {
            list($parentsql, $parentparams) = $DB->get_in_or_equal($parents, SQL_PARAMS_NAMED);

            $parentrecords = $DB->get_records_select(self::TABLE, 'id ' . $parentsql,
                    $parentparams, 'path, sortorder ASC', '*');

            foreach ($parentrecords as $id => $record) {
                $records[$id] = $record;
            }
        }

        $instances = array();
        // Convert to instances of this class.
        foreach ($records as $record) {
            $newrecord = new static(0, $record);
            $instances[$newrecord->get('id')] = $newrecord;
        }
        return $instances;
    }

    /**
     * Validate the competency framework ID.
     *
     * @param int $value The framework ID.
     * @return true|lang_string
     */
    protected function validate_competencyframeworkid($value) {

        // During update.
        if ($this->get('id')) {

            // Ensure that we are not trying to move the competency across frameworks.
            if ($this->beforeupdate->get('competencyframeworkid') != $value) {
                return new lang_string('invaliddata', 'error');
            }

        } else {
            // During create.

            // Check that the framework exists.
            if (!competency_framework::record_exists($value)) {
                return new lang_string('invaliddata', 'error');
            }
        }

        return true;
    }

    /**
     * Validate the ID number.
     *
     * @param string $value The ID number.
     * @return true|lang_string
     */
    protected function validate_idnumber($value) {
        global $DB;
        $sql = 'idnumber = :idnumber AND competencyframeworkid = :competencyframeworkid AND id <> :id';
        $params = array(
            'id' => $this->get('id'),
            'idnumber' => $value,
            'competencyframeworkid' => $this->get('competencyframeworkid')
        );
        if ($DB->record_exists_select(self::TABLE, $sql, $params)) {
            return new lang_string('idnumbertaken', 'error');
        }
        return true;
    }

    /**
     * Validate the path.
     *
     * @param string $value The path.
     * @return true|lang_string
     */
    protected function validate_path($value) {

        // The last item should be the parent ID.
        $id = $this->get('parentid');
        if (substr($value, -(strlen($id) + 2)) != '/' . $id . '/') {
            return new lang_string('invaliddata', 'error');

        } else if (!preg_match('@/([0-9]+/)+@', $value)) {
            // The format of the path is not correct.
            return new lang_string('invaliddata', 'error');
        }

        return true;
    }

    /**
     * Validate the parent ID.
     *
     * @param string $value The ID.
     * @return true|lang_string
     */
    protected function validate_parentid($value) {

        // Check that the parent exists. But only if we don't have it already, and we actually have a parent.
        if (!empty($value) && !$this->newparent && !self::record_exists($value)) {
            return new lang_string('invaliddata', 'error');
        }

        // During update.
        if ($this->get('id')) {

            // If there is a new parent.
            if ($this->beforeupdate->get('parentid') != $value && $this->newparent) {

                // Check that the new parent belongs to the same framework.
                if ($this->newparent->get('competencyframeworkid') != $this->get('competencyframeworkid')) {
                    return new lang_string('invaliddata', 'error');
                }
            }
        }

        return true;
    }

    /**
     * Validate the rule.
     *
     * @param string $value The ID.
     * @return true|lang_string
     */
    protected function validate_ruletype($value) {
        if ($value === null) {
            return true;
        }

        if (!class_exists($value) || !is_subclass_of($value, 'core_competency\\competency_rule')) {
            return new lang_string('invaliddata', 'error');
        }

        return true;
    }

    /**
     * Validate the rule config.
     *
     * @param string $value The ID.
     * @return true|lang_string
     */
    protected function validate_ruleconfig($value) {
        $rule = $this->get_rule_object();

        // We don't have a rule.
        if (empty($rule)) {
            if ($value === null) {
                // No config, perfect.
                return true;
            }
            // Config but no rules, whoops!
            return new lang_string('invaliddata', 'error');
        }

        $valid = $rule->validate_config($value);
        if ($valid !== true) {
            // Whoops!
            return new lang_string('invaliddata', 'error');
        }

        return true;
    }

    /**
     * Validate the scale ID.
     *
     * Note that the value for a scale can never be 0, null has to be used when
     * the framework's scale has to be used.
     *
     * @param  int $value
     * @return true|lang_string
     */
    protected function validate_scaleid($value) {
        global $DB;

        if ($value === null) {
            return true;
        }

        // Always validate that the scale exists.
        if (!$DB->record_exists_select('scale', 'id = :id', array('id' => $value))) {
            return new lang_string('invalidscaleid', 'error');
        }

        // During update.
        if ($this->get('id')) {

            // Validate that we can only change the scale when it is not used yet.
            if ($this->beforeupdate->get('scaleid') != $value) {
                if ($this->has_user_competencies()) {
                    return new lang_string('errorscalealreadyused', 'core_competency');
                }
            }

        }

        return true;
    }

    /**
     * Validate the scale configuration.
     *
     * This logic is adapted from {@link \core_competency\competency_framework::validate_scaleconfiguration()}.
     *
     * @param  string $value The scale configuration.
     * @return bool|lang_string
     */
    protected function validate_scaleconfiguration($value) {
        $scaleid = $this->get('scaleid');
        if ($scaleid === null && $value === null) {
            return true;
        }

        $scaledefaultselected = false;
        $proficientselected = false;
        $scaleconfigurations = json_decode($value);

        if (is_array($scaleconfigurations)) {

            // The first element of the array contains the scale ID.
            $scaleinfo = array_shift($scaleconfigurations);
            if (empty($scaleinfo) || !isset($scaleinfo->scaleid) || $scaleinfo->scaleid != $scaleid) {
                // This should never happen.
                return new lang_string('errorscaleconfiguration', 'core_competency');
            }

            // Walk through the array to find proficient and default values.
            foreach ($scaleconfigurations as $scaleconfiguration) {
                if (isset($scaleconfiguration->scaledefault) && $scaleconfiguration->scaledefault) {
                    $scaledefaultselected = true;
                }
                if (isset($scaleconfiguration->proficient) && $scaleconfiguration->proficient) {
                    $proficientselected = true;
                }
            }
        }

        if (!$scaledefaultselected || !$proficientselected) {
            return new lang_string('errorscaleconfiguration', 'core_competency');
        }

        return true;
    }

    /**
     * Return whether or not the competency IDs share the same framework.
     *
     * @param  array  $ids Competency IDs
     * @return bool
     */
    public static function share_same_framework(array $ids) {
        global $DB;
        list($insql, $params) = $DB->get_in_or_equal($ids);
        $sql = "SELECT COUNT('x') FROM (SELECT DISTINCT(competencyframeworkid) FROM {" . self::TABLE . "} WHERE id {$insql}) f";
        return $DB->count_records_sql($sql, $params) == 1;
    }

    /**
     * Get the available rules.
     *
     * @return array Keys are the class names, values are the name of the rule.
     */
    public static function get_available_rules() {
        // Fully qualified class names without leading slashes because get_class() does not add them either.
        $rules = array(
            'core_competency\\competency_rule_all' => competency_rule_all::get_name(),
            'core_competency\\competency_rule_points' => competency_rule_points::get_name(),
        );
        return $rules;
    }

    /**
     * Return the current depth of a competency framework.
     *
     * @param int $frameworkid The framework ID.
     * @return int
     */
    public static function get_framework_depth($frameworkid) {
        global $DB;
        $totallength = $DB->sql_length('path');
        $trimmedlength = $DB->sql_length("REPLACE(path, '/', '')");
        $sql = "SELECT ($totallength - $trimmedlength - 1) AS depth
                  FROM {" . self::TABLE . "}
                 WHERE competencyframeworkid = :id
              ORDER BY depth DESC";
        $record = $DB->get_record_sql($sql, array('id' => $frameworkid), IGNORE_MULTIPLE);
        if (!$record) {
            $depth = 0;
        } else {
            $depth = $record->depth;
        }
        return $depth;
    }

    /**
     * Build a framework tree with competency nodes.
     *
     * @param  int  $frameworkid the framework id
     * @return node[] tree of framework competency nodes
     */
    public static function get_framework_tree($frameworkid) {
        $competencies = self::search('', $frameworkid);
        return self::build_tree($competencies, 0);
    }

    /**
     * Get the context from the framework.
     *
     * @return context
     */
    public function get_context() {
        return $this->get_framework()->get_context();
    }

    /**
     * Recursively build up the tree of nodes.
     *
     * @param array $all - List of all competency classes.
     * @param int $parentid - The current parent ID. Pass 0 to build the tree from the top.
     * @return node[] $tree tree of nodes
     */
    protected static function build_tree($all, $parentid) {
        $tree = array();
        foreach ($all as $one) {
            if ($one->get('parentid') == $parentid) {
                $node = new stdClass();
                $node->competency = $one;
                $node->children = self::build_tree($all, $one->get('id'));
                $tree[] = $node;
            }
        }
        return $tree;
    }

    /**
     * Check if we can delete competencies safely.
     *
     * This moethod does not check any capablities.
     * Check if competency is used in a plan and user competency.
     * Check if competency is used in a template.
     * Check if competency is linked to a course.
     *
     * @param array $ids Array of competencies ids.
     * @return bool True if we can delete the competencies.
     */
    public static function can_all_be_deleted($ids) {
        global $CFG;

        if (empty($ids)) {
            return true;
        }
        // Check if competency is used in template.
        if (template_competency::has_records_for_competencies($ids)) {
            return false;
        }
        // Check if competency is used in plan.
        if (plan_competency::has_records_for_competencies($ids)) {
            return false;
        }
        // Check if competency is used in course.
        if (course_competency::has_records_for_competencies($ids)) {
            return false;
        }
        // Check if competency is used in user_competency.
        if (user_competency::has_records_for_competencies($ids)) {
            return false;
        }
        // Check if competency is used in user_competency_plan.
        if (user_competency_plan::has_records_for_competencies($ids)) {
            return false;
        }

        require_once($CFG->libdir . '/badgeslib.php');
        // Check if competency is used in a badge.
        if (badge_award_criteria_competency_has_records_for_competencies($ids)) {
            return false;
        }

        return true;
    }

    /**
     * Delete the competencies.
     *
     * This method is reserved to core usage.
     * This method does not trigger the after_delete event.
     * This method does not delete related objects such as related competencies and evidences.
     *
     * @param array $ids The competencies ids.
     * @return bool True if the competencies were deleted successfully.
     */
    public static function delete_multiple($ids) {
        global $DB;
        list($insql, $params) = $DB->get_in_or_equal($ids, SQL_PARAMS_NAMED);
        return $DB->delete_records_select(self::TABLE, "id $insql", $params);
    }

    /**
     * Get descendant ids.
     *
     * @param competency $competency The competency.
     * @return array Array of competencies ids.
     */
    public static function get_descendants_ids($competency) {
        global $DB;

        $path = $DB->sql_like_escape($competency->get('path') . $competency->get('id') . '/') . '%';
        $like = $DB->sql_like('path', ':likepath');
        return $DB->get_fieldset_select(self::TABLE, 'id', $like, array('likepath' => $path));
    }

    /**
     * Get competencyids by frameworkid.
     *
     * @param int $frameworkid The competency framework ID.
     * @return array Array of competency ids.
     */
    public static function get_ids_by_frameworkid($frameworkid) {
        global $DB;

        return $DB->get_fieldset_select(self::TABLE, 'id', 'competencyframeworkid = :frmid', array('frmid' => $frameworkid));
    }

    /**
     * Delete competencies by framework ID.
     *
     * This method is reserved to core usage.
     * This method does not trigger the after_delete event.
     * This method does not delete related objects such as related competencies and evidences.
     *
     * @param int $id the framework ID
     * @return bool Return true if delete was successful.
     */
    public static function delete_by_frameworkid($id) {
        global $DB;
        return $DB->delete_records(self::TABLE, array('competencyframeworkid' => $id));
    }

    /**
     * Get competency ancestors.
     *
     * @return competency[] Return array of ancestors.
     */
    public function get_ancestors() {
        global $DB;
        $ancestors = array();
        $ancestorsids = explode('/', trim($this->get('path'), '/'));
        // Drop the root item from the array /0/.
        array_shift($ancestorsids);
        if (!empty($ancestorsids)) {
            list($insql, $params) = $DB->get_in_or_equal($ancestorsids, SQL_PARAMS_NAMED);
            $ancestors = self::get_records_select("id $insql", $params);
        }
        return $ancestors;
    }

}