[Summary view]

   1  <?php
   2  // This file is part of Moodle - http://moodle.org/
   3  //
   4  // Moodle is free software: you can redistribute it and/or modify
   5  // it under the terms of the GNU General Public License as published by
   6  // the Free Software Foundation, either version 3 of the License, or
   7  // (at your option) any later version.
   8  //
   9  // Moodle is distributed in the hope that it will be useful,
  10  // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  // GNU General Public License for more details.
  13  //
  14  // You should have received a copy of the GNU General Public License
  15  // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16  
  17  /**
  18   * Evidence persistent file.
  19   *
  20   * @package    core_competency
  21   * @copyright  2015 Frédéric Massart - FMCorz.net
  22   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23   */
  24  
  25  namespace core_competency;
  26  defined('MOODLE_INTERNAL') || die();
  27  
  28  use coding_exception;
  29  use context;
  30  use context_user;
  31  use lang_string;
  32  use moodle_exception;
  33  use stdClass;
  34  
  35  /**
  36   * Evidence persistent class.
  37   *
  38   * @package    core_competency
  39   * @copyright  2015 Frédéric Massart - FMCorz.net
  40   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  41   */
  42  class evidence extends persistent {
  43  
  44      const TABLE = 'competency_evidence';
  45  
  46      /** Action logging. */
  47      const ACTION_LOG = 0;
  48      /** Action rating a competency when no rating is set. */
  49      const ACTION_COMPLETE = 2;
  50      /** Action rating a competency. */
  51      const ACTION_OVERRIDE = 3;
  52  
  53      /**
  54       * Return the definition of the properties of this model.
  55       *
  56       * @return array
  57       */
  58      protected static function define_properties() {
  59          return array(
  60              'usercompetencyid' => array(
  61                  'type' => PARAM_INT
  62              ),
  63              'contextid' => array(
  64                  'type' => PARAM_INT
  65              ),
  66              'action' => array(
  67                  'type' => PARAM_INT,
  68                  'choices' => array(self::ACTION_LOG, self::ACTION_COMPLETE, self::ACTION_OVERRIDE)
  69              ),
  70              'actionuserid' => array(
  71                  'type' => PARAM_INT,
  72                  'default' => null,
  73                  'null' => NULL_ALLOWED
  74              ),
  75              'descidentifier' => array(
  76                  'type' => PARAM_STRINGID
  77              ),
  78              'desccomponent' => array(
  79                  'type' => PARAM_COMPONENT
  80              ),
  81              'desca' => array(
  82                  'type' => PARAM_RAW,
  83                  'default' => null,
  84                  'null' => NULL_ALLOWED
  85              ),
  86              'url' => array(
  87                  'type' => PARAM_URL,
  88                  'default' => null,
  89                  'null' => NULL_ALLOWED
  90              ),
  91              'grade' => array(
  92                  'type' => PARAM_INT,
  93                  'default' => null,
  94                  'null' => NULL_ALLOWED
  95              ),
  96              'note' => array(
  97                  'type' => PARAM_NOTAGS,
  98                  'default' => null,
  99                  'null' => NULL_ALLOWED
 100              )
 101          );
 102      }
 103  
 104      /**
 105       * Return the competency linked to this.
 106       *
 107       * @return competency
 108       */
 109      public function get_competency() {
 110          return user_competency::get_competency_by_usercompetencyid($this->get('usercompetencyid'));
 111      }
 112  
 113      /**
 114       * Return the evidence's context.
 115       *
 116       * @return context
 117       */
 118      public function get_context() {
 119          return context::instance_by_id($this->get('contextid'));
 120      }
 121  
 122      /**
 123       * Convenience method to get the description $a.
 124       *
 125       * @return mixed
 126       */
 127      protected function get_desca() {
 128          $value = $this->raw_get('desca');
 129          if ($value !== null) {
 130              $value = json_decode($value);
 131          }
 132          return $value;
 133      }
 134  
 135      /**
 136       * Convenience method to get the description.
 137       *
 138       * @return lang_string
 139       */
 140      public function get_description() {
 141          return new lang_string($this->get('descidentifier'), $this->get('desccomponent'), $this->get_desca());
 142      }
 143  
 144      /**
 145       * Convenience method to set the description $a.
 146       *
 147       * @param mixed $value
 148       * @return mixed
 149       */
 150      protected function set_desca($value) {
 151          if ($value !== null) {
 152              if (!is_scalar($value) && !is_array($value) && !($value instanceof stdClass)) {
 153                  throw new coding_exception('$a format not supported.');
 154              }
 155              $value = json_encode($value);
 156          }
 157          $this->raw_set('desca', $value);
 158      }
 159  
 160      /**
 161       * Convenience method handling moodle_urls.
 162       *
 163       * @param null|string|moodle_url $url The URL.
 164       */
 165      protected function set_url($url) {
 166          if ($url instanceof \moodle_url) {
 167              $url = $url->out(false);
 168          }
 169          $this->raw_set('url', $url);
 170      }
 171  
 172      /**
 173       * Validate the action user ID.
 174       *
 175       * @param  int $value A user ID.
 176       * @return true|lang_string
 177       */
 178      protected function validate_actionuserid($value) {
 179          if ($value !== null && !\core_user::is_real_user($value)) {
 180              return new lang_string('invaliddata', 'error');
 181          }
 182          return true;
 183      }
 184  
 185      /**
 186       * Validate the context ID.
 187       *
 188       * @param  int $value
 189       * @return true|lang_string
 190       */
 191      protected function validate_contextid($value) {
 192          try {
 193              context::instance_by_id($value);
 194          } catch (moodle_exception $e) {
 195              // That does not look good...
 196              return new lang_string('invaliddata', 'error');
 197          }
 198          return true;
 199      }
 200  
 201      /**
 202       * Validate the description $a.
 203       *
 204       * @param string $value
 205       * @return true|lang_string
 206       */
 207      protected function validate_desca($value) {
 208          if ($value === null) {
 209              return true;
 210          }
 211  
 212          $desc = json_decode($value);
 213          if ($desc === null && json_last_error() !== JSON_ERROR_NONE) {
 214              return new lang_string('invaliddata', 'error');
 215          }
 216  
 217          return true;
 218      }
 219  
 220      /**
 221       * Validate the description identifier.
 222       *
 223       * Only validate string existence during create. If the string is removed later on we should
 224       * not prevent this model from being updated. Alternatively we could check if the string has
 225       * changed before performing the check but this overhead is not required for now.
 226       * An evidence should usually never be updated anyway.
 227       *
 228       * @param  string $value
 229       * @return true|lang_string
 230       */
 231      protected function validate_descidentifier($value) {
 232          if (!$this->get('id') && !get_string_manager()->string_exists($value, $this->get('desccomponent'))) {
 233              return new lang_string('invalidevidencedesc', 'core_competency');
 234          }
 235  
 236          return true;
 237      }
 238  
 239      /**
 240       * Validate the grade.
 241       *
 242       * For performance reason we do not validate that the grade is a valid item of the
 243       * scale associated with the competency or framework.
 244       *
 245       * @param int $value The value.
 246       * @return true|lang_string
 247       */
 248      protected function validate_grade($value) {
 249          if ($value !== null && $value <= 0) {
 250              return new lang_string('invalidgrade', 'core_competency');
 251          }
 252  
 253          $action = $this->get('action');
 254          if ($value === null && $action == self::ACTION_COMPLETE) {
 255              return new lang_string('invalidgrade', 'core_competency');
 256  
 257          } else if ($value !== null && $action == self::ACTION_LOG) {
 258              return new lang_string('invalidgrade', 'core_competency');
 259          }
 260  
 261          if ($value !== null) {
 262              // TODO MDL-52243 Use a core method to validate the grade_scale item.
 263              // Check if grade exist in the scale item values.
 264              $competency = $this->get_competency();
 265              if (!array_key_exists($value - 1, $competency->get_scale()->scale_items)) {
 266                  return new lang_string('invalidgrade', 'core_competency');
 267              }
 268          }
 269  
 270          return true;
 271      }
 272  
 273      /**
 274       * Validate the user competency.
 275       *
 276       * @param  int $value
 277       * @return true|lang_string
 278       */
 279      protected function validate_usercompetencyid($value) {
 280          if (!user_competency::record_exists($value)) {
 281              return new lang_string('invaliddata', 'error');
 282          }
 283          return true;
 284      }
 285  
 286      /**
 287       * Whether the current user can delete an evidence in the context of a user.
 288       *
 289       * @param int $userid The user ID the evidence belongs to.
 290       * @return bool
 291       */
 292      public static function can_delete_user($userid) {
 293          return has_capability('moodle/competency:evidencedelete', context_user::instance($userid));
 294      }
 295  
 296      /**
 297       * Load a list of records in a context for a user competency.
 298       *
 299       * @param int $usercompetencyid The id of the user competency.
 300       * @param context $context Context to filter the evidence list.
 301       * @param string $sort The field from the evidence table to sort on.
 302       * @param string $order The sort direction
 303       * @param int $skip Limitstart.
 304       * @param int $limit Number of rows to return.
 305       *
 306       * @return \core_competency\persistent[]
 307       */
 308      public static function get_records_for_usercompetency($usercompetencyid,
 309                                                            \context $context,
 310                                                            $sort = '',
 311                                                            $order = 'ASC',
 312                                                            $skip = 0,
 313                                                            $limit = 0) {
 314          global $DB;
 315  
 316          $params = array(
 317              'usercompid' => $usercompetencyid,
 318              'path' => $context->path . '/%',
 319              'contextid' => $context->id
 320          );
 321  
 322          if (!empty($sort)) {
 323              $sort = ' ORDER BY e.' . $sort . ' ' . $order . ', e.id ASC';
 324          } else {
 325              $sort = ' ORDER BY e.id ASC';
 326          }
 327  
 328          $sql = 'SELECT e.*
 329                    FROM {' . static::TABLE . '} e
 330                    JOIN {context} c ON c.id = e.contextid
 331                   WHERE (c.path LIKE :path OR c.id = :contextid)
 332                     AND e.usercompetencyid = :usercompid
 333                   ' . $sort;
 334          $records = $DB->get_records_sql($sql, $params, $skip, $limit);
 335          $instances = array();
 336  
 337          foreach ($records as $record) {
 338              $newrecord = new static(0, $record);
 339              array_push($instances, $newrecord);
 340          }
 341          return $instances;
 342      }
 343  
 344  }