Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.

Differences Between: [Versions 310 and 401]

   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   * Competency data generator.
  19   *
  20   * @package    core_competency
  21   * @category   test
  22   * @copyright  2015 Frédéric Massart - FMCorz.net
  23   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24   */
  25  
  26  use core_competency\competency;
  27  use core_competency\competency_framework;
  28  use core_competency\course_competency;
  29  use core_competency\course_module_competency;
  30  use core_competency\evidence;
  31  use core_competency\external;
  32  use core_competency\plan;
  33  use core_competency\plan_competency;
  34  use core_competency\related_competency;
  35  use core_competency\template;
  36  use core_competency\template_cohort;
  37  use core_competency\template_competency;
  38  use core_competency\user_competency;
  39  use core_competency\user_competency_course;
  40  use core_competency\user_competency_plan;
  41  use core_competency\user_evidence;
  42  use core_competency\user_evidence_competency;
  43  
  44  
  45  defined('MOODLE_INTERNAL') || die();
  46  
  47  global $CFG;
  48  require_once($CFG->libdir . '/grade/grade_scale.php');
  49  
  50  /**
  51   * Competency data generator class.
  52   *
  53   * @package    core_competency
  54   * @category   test
  55   * @copyright  2015 Frédéric Massart - FMCorz.net
  56   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  57   */
  58  class core_competency_generator extends component_generator_base {
  59  
  60      /** @var int Number of created competencies. */
  61      protected $competencycount = 0;
  62  
  63      /** @var int Number of created frameworks. */
  64      protected $frameworkcount = 0;
  65  
  66      /** @var int Number of created plans. */
  67      protected $plancount = 0;
  68  
  69      /** @var int Number of created templates. */
  70      protected $templatecount = 0;
  71  
  72      /** @var int Number of created user_evidence. */
  73      protected $userevidencecount = 0;
  74  
  75      /** @var stdClass Scale that we might need. */
  76      protected $scale;
  77  
  78      /**
  79       * Reset process.
  80       *
  81       * Do not call directly.
  82       *
  83       * @return void
  84       */
  85      public function reset() {
  86          $this->competencycount = 0;
  87          $this->frameworkcount = 0;
  88          $this->scale = null;
  89      }
  90  
  91      /**
  92       * Create a new competency.
  93       *
  94       * @param array|stdClass $record
  95       * @return competency
  96       */
  97      public function create_competency($record = null) {
  98          $this->competencycount++;
  99          $i = $this->competencycount;
 100          $record = (object) $record;
 101  
 102          if (!isset($record->competencyframeworkid)) {
 103              throw new coding_exception('The competencyframeworkid value is required.');
 104          }
 105          if (!isset($record->shortname)) {
 106              $record->shortname = "Competency shortname $i";
 107          }
 108          if (!isset($record->idnumber)) {
 109              $record->idnumber = "cmp{$i}";
 110          }
 111          if (!isset($record->description)) {
 112              $record->description = "Competency $i description ";
 113          }
 114          if (!isset($record->descriptionformat)) {
 115              $record->descriptionformat = FORMAT_HTML;
 116          }
 117          if (!isset($record->scaleconfiguration) && isset($record->scaleid)) {
 118              $record->scaleconfiguration = json_encode($this->make_default_scale_configuration($record->scaleid));
 119          }
 120          if (isset($record->scaleconfiguration)
 121                  && (is_array($record->scaleconfiguration) || is_object($record->scaleconfiguration))) {
 122              // Conveniently encode the config.
 123              $record->scaleconfiguration = json_encode($record->scaleconfiguration);
 124          }
 125  
 126          $competency = new competency(0, $record);
 127          $competency->create();
 128  
 129          return $competency;
 130      }
 131  
 132      /**
 133       * Create a new framework.
 134       *
 135       * @param array|stdClass $record
 136       * @return competency_framework
 137       */
 138      public function create_framework($record = null) {
 139          if (defined('BEHAT_TEST') && BEHAT_TEST) {
 140              $generator = behat_util::get_data_generator();
 141          } else {
 142              $generator = phpunit_util::get_data_generator();
 143          }
 144          $this->frameworkcount++;
 145          $i = $this->frameworkcount;
 146          $record = (object) $record;
 147  
 148          if (!isset($record->shortname)) {
 149              $record->shortname = "Framework shortname $i";
 150          }
 151          if (!isset($record->idnumber)) {
 152              $record->idnumber = "frm{$i}";
 153          }
 154          if (!isset($record->description)) {
 155              $record->description = "Framework $i description ";
 156          }
 157          if (!isset($record->descriptionformat)) {
 158              $record->descriptionformat = FORMAT_HTML;
 159          }
 160          if (!isset($record->visible)) {
 161              $record->visible = 1;
 162          }
 163          if (!isset($record->scaleid)) {
 164              if (isset($record->scaleconfiguration)) {
 165                  throw new coding_exception('Scale configuration must be provided with a scale.');
 166              }
 167              if (!$this->scale) {
 168                  $this->scale = $generator->create_scale(array('scale' => 'A,B,C,D'));
 169              }
 170              $record->scaleid = $this->scale->id;
 171          }
 172          if (!isset($record->scaleconfiguration)) {
 173              $record->scaleconfiguration = json_encode($this->make_default_scale_configuration($record->scaleid));
 174          }
 175          if (is_array($record->scaleconfiguration) || is_object($record->scaleconfiguration)) {
 176              // Conveniently encode the config.
 177              $record->scaleconfiguration = json_encode($record->scaleconfiguration);
 178          }
 179          if (!isset($record->contextid)) {
 180              $record->contextid = context_system::instance()->id;
 181          }
 182  
 183          $framework = new competency_framework(0, $record);
 184          $framework->create();
 185  
 186          return $framework;
 187      }
 188  
 189      /**
 190       * Create a related competency.
 191       *
 192       * @param array|stdClass $record
 193       * @return related_competency
 194       */
 195      public function create_related_competency($record = null) {
 196          $record = (object) $record;
 197  
 198          if (!isset($record->competencyid)) {
 199              throw new coding_exception('Property competencyid is required.');
 200          }
 201          if (!isset($record->relatedcompetencyid)) {
 202              throw new coding_exception('Property relatedcompetencyid is required.');
 203          }
 204  
 205          $relation = related_competency::get_relation($record->competencyid, $record->relatedcompetencyid);
 206          if ($relation->get('id')) {
 207              throw new coding_exception('Relation already exists');
 208          }
 209          $relation->create();
 210  
 211          return $relation;
 212      }
 213  
 214      /**
 215       * Create a template.
 216       *
 217       * @param array|stdClass $record
 218       * @return template
 219       */
 220      public function create_template($record = null) {
 221          $this->templatecount++;
 222          $i = $this->templatecount;
 223          $record = (object) $record;
 224  
 225          if (!isset($record->shortname)) {
 226              $record->shortname = "Template shortname $i";
 227          }
 228          if (!isset($record->description)) {
 229              $record->description = "Template $i description ";
 230          }
 231          if (!isset($record->contextid)) {
 232              $record->contextid = context_system::instance()->id;
 233          }
 234  
 235          $template = new template(0, $record);
 236          $template->create();
 237  
 238          return $template;
 239      }
 240  
 241      /**
 242       * Create a template competency.
 243       *
 244       * @param array|stdClass $record
 245       * @return template_competency
 246       */
 247      public function create_template_competency($record = null) {
 248          $record = (object) $record;
 249  
 250          if (!isset($record->competencyid)) {
 251              throw new coding_exception('Property competencyid is required.');
 252          }
 253          if (!isset($record->templateid)) {
 254              throw new coding_exception('Property templateid is required.');
 255          }
 256  
 257          $relation = new template_competency(0, $record);
 258          $relation->create();
 259  
 260          return $relation;
 261      }
 262  
 263      /**
 264       * Create a new user competency.
 265       *
 266       * @param array|stdClass $record
 267       * @return user_competency
 268       */
 269      public function create_user_competency($record = null) {
 270          $record = (object) $record;
 271  
 272          if (!isset($record->userid)) {
 273              throw new coding_exception('The userid value is required.');
 274          }
 275          if (!isset($record->competencyid)) {
 276              throw new coding_exception('The competencyid value is required.');
 277          }
 278  
 279          $usercompetency = new user_competency(0, $record);
 280          $usercompetency->create();
 281  
 282          return $usercompetency;
 283      }
 284  
 285      /**
 286       * Create a new plan.
 287       *
 288       * @param array|stdClass $record
 289       * @return plan
 290       */
 291      public function create_plan($record = null) {
 292          $this->plancount++;
 293          $i = $this->plancount;
 294          $record = (object) $record;
 295  
 296          if (!isset($record->name)) {
 297              $record->name = "Plan shortname $i";
 298          }
 299          if (!isset($record->description)) {
 300              $record->description = "Plan $i description";
 301          }
 302          if (!isset($record->descriptionformat)) {
 303              $record->descriptionformat = FORMAT_HTML;
 304          }
 305          if (!isset($record->userid)) {
 306              throw new coding_exception('The userid value is required.');
 307          }
 308  
 309          $plan = new plan(0, $record);
 310          $plan->create();
 311  
 312          return $plan;
 313      }
 314  
 315      /**
 316       * Create a new user competency course.
 317       *
 318       * @param array|stdClass $record
 319       * @return user_competency_course
 320       */
 321      public function create_user_competency_course($record = null) {
 322          $record = (object) $record;
 323  
 324          if (!isset($record->userid)) {
 325              throw new coding_exception('The userid value is required.');
 326          }
 327          if (!isset($record->competencyid)) {
 328              throw new coding_exception('The competencyid value is required.');
 329          }
 330  
 331          if (!isset($record->courseid)) {
 332              throw new coding_exception('The courseid value is required.');
 333          }
 334  
 335          $usercompetencycourse = new user_competency_course(0, $record);
 336          $usercompetencycourse->create();
 337  
 338          return $usercompetencycourse;
 339      }
 340  
 341      /**
 342       * Create a new user competency plan.
 343       *
 344       * @param array|stdClass $record
 345       * @return user_competency_plan
 346       */
 347      public function create_user_competency_plan($record = null) {
 348          $record = (object) $record;
 349  
 350          if (!isset($record->userid)) {
 351              throw new coding_exception('The userid value is required.');
 352          }
 353          if (!isset($record->competencyid)) {
 354              throw new coding_exception('The competencyid value is required.');
 355          }
 356  
 357          if (!isset($record->planid)) {
 358              throw new coding_exception('The planid value is required.');
 359          }
 360  
 361          if (!isset($record->sortorder)) {
 362              $record->sortorder = 0;
 363          }
 364  
 365          $usercompetencyplan = new user_competency_plan(0, $record);
 366          $usercompetencyplan->create();
 367  
 368          return $usercompetencyplan;
 369      }
 370  
 371      /**
 372       * Create a new plan competency.
 373       *
 374       * @param array|stdClass $record
 375       * @return plan_competency
 376       */
 377      public function create_plan_competency($record = null) {
 378          $record = (object) $record;
 379  
 380          if (!isset($record->planid)) {
 381              throw new coding_exception('The planid value is required.');
 382          }
 383          if (!isset($record->competencyid)) {
 384              throw new coding_exception('The competencyid value is required.');
 385          }
 386  
 387          $plancompetency = new plan_competency(0, $record);
 388          $plancompetency->create();
 389  
 390          return $plancompetency;
 391      }
 392  
 393      /**
 394       * Create a new template cohort.
 395       *
 396       * @param array|stdClass $record
 397       * @return template_cohort
 398       */
 399      public function create_template_cohort($record = null) {
 400          $record = (object) $record;
 401  
 402          if (!isset($record->templateid)) {
 403              throw new coding_exception('The templateid value is required.');
 404          }
 405          if (!isset($record->cohortid)) {
 406              throw new coding_exception('The cohortid value is required.');
 407          }
 408  
 409          $tplcohort = new template_cohort(0, $record);
 410          $tplcohort->create();
 411  
 412          return $tplcohort;
 413      }
 414  
 415      /**
 416       * Create a new evidence.
 417       *
 418       * @param array|stdClass $record
 419       * @return evidence
 420       */
 421      public function create_evidence($record = null) {
 422          $record = (object) $record;
 423  
 424          if (!isset($record->usercompetencyid)) {
 425              throw new coding_exception('The usercompetencyid value is required.');
 426          }
 427          if (!isset($record->action) && !isset($record->grade)) {
 428              $record->action = evidence::ACTION_LOG;
 429          }
 430          if (!isset($record->action)) {
 431              throw new coding_exception('The action value is required with a grade.');
 432          }
 433  
 434          if (!isset($record->contextid)) {
 435              $record->contextid = context_system::instance()->id;
 436          }
 437          if (!isset($record->descidentifier)) {
 438              $record->descidentifier = 'invalidevidencedesc';
 439          }
 440          if (!isset($record->desccomponent)) {
 441              $record->desccomponent = 'core_competency';
 442          }
 443          $evidence = new evidence(0, $record);
 444          $evidence->create();
 445  
 446          return $evidence;
 447      }
 448  
 449      /**
 450       * Create a new course competency.
 451       *
 452       * @param array|stdClass $record
 453       * @return user_competency
 454       */
 455      public function create_course_competency($record = null) {
 456          $record = (object) $record;
 457  
 458          if (!isset($record->courseid)) {
 459              throw new coding_exception('The courseid value is required.');
 460          }
 461          if (!isset($record->competencyid)) {
 462              throw new coding_exception('The competencyid value is required.');
 463          }
 464  
 465          $cc = new course_competency(0, $record);
 466          $cc->create();
 467  
 468          return $cc;
 469      }
 470  
 471      /**
 472       * Create a new course module competency.
 473       *
 474       * @param array|stdClass $record
 475       * @return course_module_competency
 476       */
 477      public function create_course_module_competency($record = null) {
 478          $record = (object) $record;
 479  
 480          if (!isset($record->cmid)) {
 481              throw new coding_exception('The cmid value is required.');
 482          }
 483          if (!isset($record->competencyid)) {
 484              throw new coding_exception('The competencyid value is required.');
 485          }
 486  
 487          $cc = new course_module_competency(0, $record);
 488          $cc->create();
 489  
 490          return $cc;
 491      }
 492  
 493      /**
 494       * Create a new user_evidence.
 495       *
 496       * @param array|stdClass $record
 497       * @return evidence
 498       */
 499      public function create_user_evidence($record = null) {
 500          $this->userevidencecount++;
 501          $i = $this->userevidencecount;
 502          $record = (object) $record;
 503  
 504          if (!isset($record->userid)) {
 505              throw new coding_exception('The userid value is required.');
 506          }
 507          if (!isset($record->name)) {
 508              $record->name = "Evidence $i name";
 509          }
 510          if (!isset($record->description)) {
 511              $record->description = "Evidence $i description";
 512          }
 513          if (!isset($record->descriptionformat)) {
 514              $record->descriptionformat = FORMAT_HTML;
 515          }
 516  
 517          $ue = new user_evidence(0, $record);
 518          $ue->create();
 519  
 520          return $ue;
 521      }
 522  
 523      /**
 524       * Create a new user_evidence_comp.
 525       *
 526       * @param array|stdClass $record
 527       * @return evidence
 528       */
 529      public function create_user_evidence_competency($record = null) {
 530          $record = (object) $record;
 531  
 532          if (!isset($record->userevidenceid)) {
 533              throw new coding_exception('The userevidenceid value is required.');
 534          }
 535          if (!isset($record->competencyid)) {
 536              throw new coding_exception('The competencyid value is required.');
 537          }
 538  
 539          $uec = new user_evidence_competency(0, $record);
 540          $uec->create();
 541  
 542          return $uec;
 543      }
 544  
 545      /**
 546       * Make a default scale configuration.
 547       *
 548       * The last and second-last item will be flagged proficient. The
 549       * second-last item will be flagged as default.
 550       *
 551       * @param int $scaleid The scale ID.
 552       * @return array Configuration as array.
 553       */
 554      protected function make_default_scale_configuration($scaleid) {
 555          $scale = grade_scale::fetch(array('id' => $scaleid));
 556          $values = $scale->load_items();
 557  
 558          foreach ($values as $key => $value) {
 559              // Add a key (make the first value 1).
 560              $values[$key] = array('id' => $key + 1, 'name' => $value);
 561          }
 562  
 563          if (count($values) < 2) {
 564              throw new coding_exception('Please provide the scale configuration for one-item scales.');
 565          }
 566  
 567          $scaleconfig = array();
 568  
 569          // Last item is proficient.
 570          $item = array_pop($values);
 571          array_unshift($scaleconfig, array(
 572              'id' => $item['id'],
 573              'proficient' => 1
 574          ));
 575  
 576          // Second-last item is default and proficient.
 577          $item = array_pop($values);
 578          array_unshift($scaleconfig, array(
 579              'id' => $item['id'],
 580              'scaledefault' => 1,
 581              'proficient' => 1
 582          ));
 583  
 584          // Add the scale ID.
 585          array_unshift($scaleconfig, array('scaleid' => $scaleid));
 586  
 587          return $scaleconfig;
 588      }
 589  
 590  }