Search moodle.org's
Developer Documentation
Developer Documentation
- Bug fixes for general core bugs in 4.2.x will end 22 April 2024 (12 months).
- Bug fixes for security issues in 4.2.x will end 7 October 2024 (18 months).
- PHP version: minimum PHP 8.0.0 Note: minimum PHP version has increased since Moodle 4.1. PHP 8.1.x is supported too.
/competency/classes/ -> api.php (source)
Differences Between: [Versions 310 and 402] [Versions 311 and 402] [Versions 39 and 402] [Versions 400 and 402] [Versions 401 and 402]
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 * Class for loading/storing competency frameworks from the DB. 19 * 20 * @package core_competency 21 * @copyright 2015 Damyon Wiese 22 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 23 */ 24 namespace core_competency; 25 defined('MOODLE_INTERNAL') || die(); 26 27 use stdClass; 28 use cm_info; 29 use context; 30 use context_helper; 31 use context_system; 32 use context_course; 33 use context_module; 34 use context_user; 35 use coding_exception; 36 use require_login_exception; 37 use moodle_exception; 38 use moodle_url; 39 use required_capability_exception; 40 41 /** 42 * Class for doing things with competency frameworks. 43 * 44 * @copyright 2015 Damyon Wiese 45 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 46 */ 47 class api { 48 49 /** @var boolean Allow api functions even if competencies are not enabled for the site. */ 50 private static $skipenabled = false; 51 52 /** 53 * Returns whether competencies are enabled. 54 * 55 * This method should never do more than checking the config setting, the reason 56 * being that some other code could be checking the config value directly 57 * to avoid having to load this entire file into memory. 58 * 59 * @return boolean True when enabled. 60 */ 61 public static function is_enabled() { 62 return self::$skipenabled || get_config('core_competency', 'enabled'); 63 } 64 65 /** 66 * When competencies used to be enabled, we can show the text but do not include links. 67 * 68 * @return boolean True means show links. 69 */ 70 public static function show_links() { 71 return isloggedin() && !isguestuser() && get_config('core_competency', 'enabled'); 72 } 73 74 /** 75 * Allow calls to competency api functions even if competencies are not currently enabled. 76 */ 77 public static function skip_enabled() { 78 self::$skipenabled = true; 79 } 80 81 /** 82 * Restore the checking that competencies are enabled with any api function. 83 */ 84 public static function check_enabled() { 85 self::$skipenabled = false; 86 } 87 88 /** 89 * Throws an exception if competencies are not enabled. 90 * 91 * @return void 92 * @throws moodle_exception 93 */ 94 public static function require_enabled() { 95 if (!static::is_enabled()) { 96 throw new moodle_exception('competenciesarenotenabled', 'core_competency'); 97 } 98 } 99 100 /** 101 * Checks whether a scale is used anywhere in the plugin. 102 * 103 * This public API has two exceptions: 104 * - It MUST NOT perform any capability checks. 105 * - It MUST ignore whether competencies are enabled or not ({@link self::is_enabled()}). 106 * 107 * @param int $scaleid The scale ID. 108 * @return bool 109 */ 110 public static function is_scale_used_anywhere($scaleid) { 111 global $DB; 112 $sql = "SELECT s.id 113 FROM {scale} s 114 LEFT JOIN {" . competency_framework::TABLE ."} f 115 ON f.scaleid = :scaleid1 116 LEFT JOIN {" . competency::TABLE ."} c 117 ON c.scaleid = :scaleid2 118 WHERE f.id IS NOT NULL 119 OR c.id IS NOT NULL"; 120 return $DB->record_exists_sql($sql, ['scaleid1' => $scaleid, 'scaleid2' => $scaleid]); 121 } 122 123 /** 124 * Validate if current user have acces to the course_module if hidden. 125 * 126 * @param mixed $cmmixed The cm_info class, course module record or its ID. 127 * @param bool $throwexception Throw an exception or not. 128 * @return bool 129 */ 130 protected static function validate_course_module($cmmixed, $throwexception = true) { 131 $cm = $cmmixed; 132 if (!is_object($cm)) { 133 $cmrecord = get_coursemodule_from_id(null, $cmmixed); 134 $modinfo = get_fast_modinfo($cmrecord->course); 135 $cm = $modinfo->get_cm($cmmixed); 136 } else if (!$cm instanceof cm_info) { 137 // Assume we got a course module record. 138 $modinfo = get_fast_modinfo($cm->course); 139 $cm = $modinfo->get_cm($cm->id); 140 } 141 142 if (!$cm->uservisible) { 143 if ($throwexception) { 144 throw new require_login_exception('Course module is hidden'); 145 } else { 146 return false; 147 } 148 } 149 150 return true; 151 } 152 153 /** 154 * Validate if current user have acces to the course if hidden. 155 * 156 * @param mixed $courseorid The course or it ID. 157 * @param bool $throwexception Throw an exception or not. 158 * @return bool 159 */ 160 protected static function validate_course($courseorid, $throwexception = true) { 161 $course = $courseorid; 162 if (!is_object($course)) { 163 $course = get_course($course); 164 } 165 166 $coursecontext = context_course::instance($course->id); 167 if (!$course->visible and !has_capability('moodle/course:viewhiddencourses', $coursecontext)) { 168 if ($throwexception) { 169 throw new require_login_exception('Course is hidden'); 170 } else { 171 return false; 172 } 173 } 174 175 return true; 176 } 177 178 /** 179 * Create a competency from a record containing all the data for the class. 180 * 181 * Requires moodle/competency:competencymanage capability at the system context. 182 * 183 * @param stdClass $record Record containing all the data for an instance of the class. 184 * @return competency 185 */ 186 public static function create_competency(stdClass $record) { 187 static::require_enabled(); 188 $competency = new competency(0, $record); 189 190 // First we do a permissions check. 191 require_capability('moodle/competency:competencymanage', $competency->get_context()); 192 193 // Reset the sortorder, use reorder instead. 194 $competency->set('sortorder', 0); 195 $competency->create(); 196 197 \core\event\competency_created::create_from_competency($competency)->trigger(); 198 199 // Reset the rule of the parent. 200 $parent = $competency->get_parent(); 201 if ($parent) { 202 $parent->reset_rule(); 203 $parent->update(); 204 } 205 206 return $competency; 207 } 208 209 /** 210 * Delete a competency by id. 211 * 212 * Requires moodle/competency:competencymanage capability at the system context. 213 * 214 * @param int $id The record to delete. This will delete alot of related data - you better be sure. 215 * @return boolean 216 */ 217 public static function delete_competency($id) { 218 global $DB; 219 static::require_enabled(); 220 $competency = new competency($id); 221 222 // First we do a permissions check. 223 require_capability('moodle/competency:competencymanage', $competency->get_context()); 224 225 $events = array(); 226 $competencyids = array(intval($competency->get('id'))); 227 $contextid = $competency->get_context()->id; 228 $competencyids = array_merge(competency::get_descendants_ids($competency), $competencyids); 229 if (!competency::can_all_be_deleted($competencyids)) { 230 return false; 231 } 232 $transaction = $DB->start_delegated_transaction(); 233 234 try { 235 236 // Reset the rule of the parent. 237 $parent = $competency->get_parent(); 238 if ($parent) { 239 $parent->reset_rule(); 240 $parent->update(); 241 } 242 243 // Delete the competency separately so the after_delete event can be triggered. 244 $competency->delete(); 245 246 // Delete the competencies. 247 competency::delete_multiple($competencyids); 248 249 // Delete the competencies relation. 250 related_competency::delete_multiple_relations($competencyids); 251 252 // Delete competency evidences. 253 user_evidence_competency::delete_by_competencyids($competencyids); 254 255 // Register the competencies deleted events. 256 $events = \core\event\competency_deleted::create_multiple_from_competencyids($competencyids, $contextid); 257 258 } catch (\Exception $e) { 259 $transaction->rollback($e); 260 } 261 262 $transaction->allow_commit(); 263 // Trigger events. 264 foreach ($events as $event) { 265 $event->trigger(); 266 } 267 268 return true; 269 } 270 271 /** 272 * Reorder this competency. 273 * 274 * Requires moodle/competency:competencymanage capability at the system context. 275 * 276 * @param int $id The id of the competency to move. 277 * @return boolean 278 */ 279 public static function move_down_competency($id) { 280 static::require_enabled(); 281 $current = new competency($id); 282 283 // First we do a permissions check. 284 require_capability('moodle/competency:competencymanage', $current->get_context()); 285 286 $max = self::count_competencies(array('parentid' => $current->get('parentid'), 287 'competencyframeworkid' => $current->get('competencyframeworkid'))); 288 if ($max > 0) { 289 $max--; 290 } 291 292 $sortorder = $current->get('sortorder'); 293 if ($sortorder >= $max) { 294 return false; 295 } 296 $sortorder = $sortorder + 1; 297 $current->set('sortorder', $sortorder); 298 299 $filters = array('parentid' => $current->get('parentid'), 300 'competencyframeworkid' => $current->get('competencyframeworkid'), 301 'sortorder' => $sortorder); 302 $children = self::list_competencies($filters, 'id'); 303 foreach ($children as $needtoswap) { 304 $needtoswap->set('sortorder', $sortorder - 1); 305 $needtoswap->update(); 306 } 307 308 // OK - all set. 309 $result = $current->update(); 310 311 return $result; 312 } 313 314 /** 315 * Reorder this competency. 316 * 317 * Requires moodle/competency:competencymanage capability at the system context. 318 * 319 * @param int $id The id of the competency to move. 320 * @return boolean 321 */ 322 public static function move_up_competency($id) { 323 static::require_enabled(); 324 $current = new competency($id); 325 326 // First we do a permissions check. 327 require_capability('moodle/competency:competencymanage', $current->get_context()); 328 329 $sortorder = $current->get('sortorder'); 330 if ($sortorder == 0) { 331 return false; 332 } 333 334 $sortorder = $sortorder - 1; 335 $current->set('sortorder', $sortorder); 336 337 $filters = array('parentid' => $current->get('parentid'), 338 'competencyframeworkid' => $current->get('competencyframeworkid'), 339 'sortorder' => $sortorder); 340 $children = self::list_competencies($filters, 'id'); 341 foreach ($children as $needtoswap) { 342 $needtoswap->set('sortorder', $sortorder + 1); 343 $needtoswap->update(); 344 } 345 346 // OK - all set. 347 $result = $current->update(); 348 349 return $result; 350 } 351 352 /** 353 * Move this competency so it sits in a new parent. 354 * 355 * Requires moodle/competency:competencymanage capability at the system context. 356 * 357 * @param int $id The id of the competency to move. 358 * @param int $newparentid The new parent id for the competency. 359 * @return boolean 360 */ 361 public static function set_parent_competency($id, $newparentid) { 362 global $DB; 363 static::require_enabled(); 364 $current = new competency($id); 365 366 // First we do a permissions check. 367 require_capability('moodle/competency:competencymanage', $current->get_context()); 368 if ($id == $newparentid) { 369 throw new coding_exception('Can not set a competency as a parent of itself.'); 370 } if ($newparentid == $current->get('parentid')) { 371 throw new coding_exception('Can not move a competency to the same location.'); 372 } 373 374 // Some great variable assignment right here. 375 $currentparent = $current->get_parent(); 376 $parent = !empty($newparentid) ? new competency($newparentid) : null; 377 $parentpath = !empty($parent) ? $parent->get('path') : '/0/'; 378 379 // We're going to change quite a few things. 380 $transaction = $DB->start_delegated_transaction(); 381 382 // If we are moving a node to a child of itself: 383 // - promote all the child nodes by one level. 384 // - remove the rule on self. 385 // - re-read the parent. 386 $newparents = explode('/', $parentpath); 387 if (in_array($current->get('id'), $newparents)) { 388 $children = competency::get_records(array('parentid' => $current->get('id')), 'id'); 389 foreach ($children as $child) { 390 $child->set('parentid', $current->get('parentid')); 391 $child->update(); 392 } 393 394 // Reset the rule on self as our children have changed. 395 $current->reset_rule(); 396 397 // The destination parent is one of our descendants, we need to re-fetch its values (path, parentid). 398 $parent->read(); 399 } 400 401 // Reset the rules of initial parent and destination. 402 if (!empty($currentparent)) { 403 $currentparent->reset_rule(); 404 $currentparent->update(); 405 } 406 if (!empty($parent)) { 407 $parent->reset_rule(); 408 $parent->update(); 409 } 410 411 // Do the actual move. 412 $current->set('parentid', $newparentid); 413 $result = $current->update(); 414 415 // All right, let's commit this. 416 $transaction->allow_commit(); 417 418 return $result; 419 } 420 421 /** 422 * Update the details for a competency. 423 * 424 * Requires moodle/competency:competencymanage capability at the system context. 425 * 426 * @param stdClass $record The new details for the competency. 427 * Note - must contain an id that points to the competency to update. 428 * 429 * @return boolean 430 */ 431 public static function update_competency($record) { 432 static::require_enabled(); 433 $competency = new competency($record->id); 434 435 // First we do a permissions check. 436 require_capability('moodle/competency:competencymanage', $competency->get_context()); 437 438 // Some things should not be changed in an update - they should use a more specific method. 439 $record->sortorder = $competency->get('sortorder'); 440 $record->parentid = $competency->get('parentid'); 441 $record->competencyframeworkid = $competency->get('competencyframeworkid'); 442 443 $competency->from_record($record); 444 require_capability('moodle/competency:competencymanage', $competency->get_context()); 445 446 // OK - all set. 447 $result = $competency->update(); 448 449 // Trigger the update event. 450 \core\event\competency_updated::create_from_competency($competency)->trigger(); 451 452 return $result; 453 } 454 455 /** 456 * Read a the details for a single competency and return a record. 457 * 458 * Requires moodle/competency:competencyview capability at the system context. 459 * 460 * @param int $id The id of the competency to read. 461 * @param bool $includerelated Include related tags or not. 462 * @return competency 463 */ 464 public static function read_competency($id, $includerelated = false) { 465 static::require_enabled(); 466 $competency = new competency($id); 467 468 // First we do a permissions check. 469 $context = $competency->get_context(); 470 if (!has_any_capability(array('moodle/competency:competencyview', 'moodle/competency:competencymanage'), $context)) { 471 throw new required_capability_exception($context, 'moodle/competency:competencyview', 'nopermissions', ''); 472 } 473 474 // OK - all set. 475 if ($includerelated) { 476 $relatedcompetency = new related_competency(); 477 if ($related = $relatedcompetency->list_relations($id)) { 478 $competency->relatedcompetencies = $related; 479 } 480 } 481 482 return $competency; 483 } 484 485 /** 486 * Perform a text search based and return all results and their parents. 487 * 488 * Requires moodle/competency:competencyview capability at the framework context. 489 * 490 * @param string $textsearch A string to search for. 491 * @param int $competencyframeworkid The id of the framework to limit the search. 492 * @return array of competencies 493 */ 494 public static function search_competencies($textsearch, $competencyframeworkid) { 495 static::require_enabled(); 496 $framework = new competency_framework($competencyframeworkid); 497 498 // First we do a permissions check. 499 $context = $framework->get_context(); 500 if (!has_any_capability(array('moodle/competency:competencyview', 'moodle/competency:competencymanage'), $context)) { 501 throw new required_capability_exception($context, 'moodle/competency:competencyview', 'nopermissions', ''); 502 } 503 504 // OK - all set. 505 $competencies = competency::search($textsearch, $competencyframeworkid); 506 return $competencies; 507 } 508 509 /** 510 * Perform a search based on the provided filters and return a paginated list of records. 511 * 512 * Requires moodle/competency:competencyview capability at some context. 513 * 514 * @param array $filters A list of filters to apply to the list. 515 * @param string $sort The column to sort on 516 * @param string $order ('ASC' or 'DESC') 517 * @param int $skip Number of records to skip (pagination) 518 * @param int $limit Max of records to return (pagination) 519 * @return array of competencies 520 */ 521 public static function list_competencies($filters, $sort = '', $order = 'ASC', $skip = 0, $limit = 0) { 522 static::require_enabled(); 523 if (!isset($filters['competencyframeworkid'])) { 524 $context = context_system::instance(); 525 } else { 526 $framework = new competency_framework($filters['competencyframeworkid']); 527 $context = $framework->get_context(); 528 } 529 530 // First we do a permissions check. 531 if (!has_any_capability(array('moodle/competency:competencyview', 'moodle/competency:competencymanage'), $context)) { 532 throw new required_capability_exception($context, 'moodle/competency:competencyview', 'nopermissions', ''); 533 } 534 535 // OK - all set. 536 return competency::get_records($filters, $sort, $order, $skip, $limit); 537 } 538 539 /** 540 * Perform a search based on the provided filters and return a paginated list of records. 541 * 542 * Requires moodle/competency:competencyview capability at some context. 543 * 544 * @param array $filters A list of filters to apply to the list. 545 * @return int 546 */ 547 public static function count_competencies($filters) { 548 static::require_enabled(); 549 if (!isset($filters['competencyframeworkid'])) { 550 $context = context_system::instance(); 551 } else { 552 $framework = new competency_framework($filters['competencyframeworkid']); 553 $context = $framework->get_context(); 554 } 555 556 // First we do a permissions check. 557 if (!has_any_capability(array('moodle/competency:competencyview', 'moodle/competency:competencymanage'), $context)) { 558 throw new required_capability_exception($context, 'moodle/competency:competencyview', 'nopermissions', ''); 559 } 560 561 // OK - all set. 562 return competency::count_records($filters); 563 } 564 565 /** 566 * Create a competency framework from a record containing all the data for the class. 567 * 568 * Requires moodle/competency:competencymanage capability at the system context. 569 * 570 * @param stdClass $record Record containing all the data for an instance of the class. 571 * @return competency_framework 572 */ 573 public static function create_framework(stdClass $record) { 574 static::require_enabled(); 575 $framework = new competency_framework(0, $record); 576 require_capability('moodle/competency:competencymanage', $framework->get_context()); 577 578 // Account for different formats of taxonomies. 579 if (isset($record->taxonomies)) { 580 $framework->set('taxonomies', $record->taxonomies); 581 } 582 583 $framework = $framework->create(); 584 585 // Trigger a competency framework created event. 586 \core\event\competency_framework_created::create_from_framework($framework)->trigger(); 587 588 return $framework; 589 } 590 591 /** 592 * Duplicate a competency framework by id. 593 * 594 * Requires moodle/competency:competencymanage capability at the system context. 595 * 596 * @param int $id The record to duplicate. All competencies associated and related will be duplicated. 597 * @return competency_framework the framework duplicated 598 */ 599 public static function duplicate_framework($id) { 600 global $DB; 601 static::require_enabled(); 602 603 $framework = new competency_framework($id); 604 require_capability('moodle/competency:competencymanage', $framework->get_context()); 605 // Starting transaction. 606 $transaction = $DB->start_delegated_transaction(); 607 608 try { 609 // Get a uniq idnumber based on the origin framework. 610 $idnumber = competency_framework::get_unused_idnumber($framework->get('idnumber')); 611 $framework->set('idnumber', $idnumber); 612 // Adding the suffix copy to the shortname. 613 $framework->set('shortname', get_string('duplicateditemname', 'core_competency', $framework->get('shortname'))); 614 $framework->set('id', 0); 615 $framework = $framework->create(); 616 617 // Array that match the old competencies ids with the new one to use when copying related competencies. 618 $frameworkcompetency = competency::get_framework_tree($id); 619 $matchids = self::duplicate_competency_tree($framework->get('id'), $frameworkcompetency, 0, 0); 620 621 // Copy the related competencies. 622 $relcomps = related_competency::get_multiple_relations(array_keys($matchids)); 623 624 foreach ($relcomps as $relcomp) { 625 $compid = $relcomp->get('competencyid'); 626 $relcompid = $relcomp->get('relatedcompetencyid'); 627 if (isset($matchids[$compid]) && isset($matchids[$relcompid])) { 628 $newcompid = $matchids[$compid]->get('id'); 629 $newrelcompid = $matchids[$relcompid]->get('id'); 630 if ($newcompid < $newrelcompid) { 631 $relcomp->set('competencyid', $newcompid); 632 $relcomp->set('relatedcompetencyid', $newrelcompid); 633 } else { 634 $relcomp->set('competencyid', $newrelcompid); 635 $relcomp->set('relatedcompetencyid', $newcompid); 636 } 637 $relcomp->set('id', 0); 638 $relcomp->create(); 639 } else { 640 // Debugging message when there is no match found. 641 debugging('related competency id not found'); 642 } 643 } 644 645 // Setting rules on duplicated competencies. 646 self::migrate_competency_tree_rules($frameworkcompetency, $matchids); 647 648 $transaction->allow_commit(); 649 650 } catch (\Exception $e) { 651 $transaction->rollback($e); 652 } 653 654 // Trigger a competency framework created event. 655 \core\event\competency_framework_created::create_from_framework($framework)->trigger(); 656 657 return $framework; 658 } 659 660 /** 661 * Delete a competency framework by id. 662 * 663 * Requires moodle/competency:competencymanage capability at the system context. 664 * 665 * @param int $id The record to delete. This will delete alot of related data - you better be sure. 666 * @return boolean 667 */ 668 public static function delete_framework($id) { 669 global $DB; 670 static::require_enabled(); 671 $framework = new competency_framework($id); 672 require_capability('moodle/competency:competencymanage', $framework->get_context()); 673 674 $events = array(); 675 $competenciesid = competency::get_ids_by_frameworkid($id); 676 $contextid = $framework->get('contextid'); 677 if (!competency::can_all_be_deleted($competenciesid)) { 678 return false; 679 } 680 $transaction = $DB->start_delegated_transaction(); 681 try { 682 if (!empty($competenciesid)) { 683 // Delete competencies. 684 competency::delete_by_frameworkid($id); 685 686 // Delete the related competencies. 687 related_competency::delete_multiple_relations($competenciesid); 688 689 // Delete the evidences for competencies. 690 user_evidence_competency::delete_by_competencyids($competenciesid); 691 } 692 693 // Create a competency framework deleted event. 694 $event = \core\event\competency_framework_deleted::create_from_framework($framework); 695 $result = $framework->delete(); 696 697 // Register the deleted events competencies. 698 $events = \core\event\competency_deleted::create_multiple_from_competencyids($competenciesid, $contextid); 699 700 } catch (\Exception $e) { 701 $transaction->rollback($e); 702 } 703 704 // Commit the transaction. 705 $transaction->allow_commit(); 706 707 // If all operations are successfull then trigger the delete event. 708 $event->trigger(); 709 710 // Trigger deleted event competencies. 711 foreach ($events as $event) { 712 $event->trigger(); 713 } 714 715 return $result; 716 } 717 718 /** 719 * Update the details for a competency framework. 720 * 721 * Requires moodle/competency:competencymanage capability at the system context. 722 * 723 * @param stdClass $record The new details for the framework. Note - must contain an id that points to the framework to update. 724 * @return boolean 725 */ 726 public static function update_framework($record) { 727 static::require_enabled(); 728 $framework = new competency_framework($record->id); 729 730 // Check the permissions before update. 731 require_capability('moodle/competency:competencymanage', $framework->get_context()); 732 733 // Account for different formats of taxonomies. 734 $framework->from_record($record); 735 if (isset($record->taxonomies)) { 736 $framework->set('taxonomies', $record->taxonomies); 737 } 738 739 // Trigger a competency framework updated event. 740 \core\event\competency_framework_updated::create_from_framework($framework)->trigger(); 741 742 return $framework->update(); 743 } 744 745 /** 746 * Read a the details for a single competency framework and return a record. 747 * 748 * Requires moodle/competency:competencyview capability at the system context. 749 * 750 * @param int $id The id of the framework to read. 751 * @return competency_framework 752 */ 753 public static function read_framework($id) { 754 static::require_enabled(); 755 $framework = new competency_framework($id); 756 if (!has_any_capability(array('moodle/competency:competencyview', 'moodle/competency:competencymanage'), 757 $framework->get_context())) { 758 throw new required_capability_exception($framework->get_context(), 'moodle/competency:competencyview', 759 'nopermissions', ''); 760 } 761 return $framework; 762 } 763 764 /** 765 * Logg the competency framework viewed event. 766 * 767 * @param competency_framework|int $frameworkorid The competency_framework object or competency framework id 768 * @return bool 769 */ 770 public static function competency_framework_viewed($frameworkorid) { 771 static::require_enabled(); 772 $framework = $frameworkorid; 773 if (!is_object($framework)) { 774 $framework = new competency_framework($framework); 775 } 776 if (!has_any_capability(array('moodle/competency:competencyview', 'moodle/competency:competencymanage'), 777 $framework->get_context())) { 778 throw new required_capability_exception($framework->get_context(), 'moodle/competency:competencyview', 779 'nopermissions', ''); 780 } 781 \core\event\competency_framework_viewed::create_from_framework($framework)->trigger(); 782 return true; 783 } 784 785 /** 786 * Logg the competency viewed event. 787 * 788 * @param competency|int $competencyorid The competency object or competency id 789 * @return bool 790 */ 791 public static function competency_viewed($competencyorid) { 792 static::require_enabled(); 793 $competency = $competencyorid; 794 if (!is_object($competency)) { 795 $competency = new competency($competency); 796 } 797 798 if (!has_any_capability(array('moodle/competency:competencyview', 'moodle/competency:competencymanage'), 799 $competency->get_context())) { 800 throw new required_capability_exception($competency->get_context(), 'moodle/competency:competencyview', 801 'nopermissions', ''); 802 } 803 804 \core\event\competency_viewed::create_from_competency($competency)->trigger(); 805 return true; 806 } 807 808 /** 809 * Perform a search based on the provided filters and return a paginated list of records. 810 * 811 * Requires moodle/competency:competencyview capability at the system context. 812 * 813 * @param string $sort The column to sort on 814 * @param string $order ('ASC' or 'DESC') 815 * @param int $skip Number of records to skip (pagination) 816 * @param int $limit Max of records to return (pagination) 817 * @param context $context The parent context of the frameworks. 818 * @param string $includes Defines what other contexts to fetch frameworks from. 819 * Accepted values are: 820 * - children: All descendants 821 * - parents: All parents, grand parents, etc... 822 * - self: Context passed only. 823 * @param bool $onlyvisible If true return only visible frameworks 824 * @param string $query A string to use to filter down the frameworks. 825 * @return array of competency_framework 826 */ 827 public static function list_frameworks($sort, $order, $skip, $limit, $context, $includes = 'children', 828 $onlyvisible = false, $query = '') { 829 global $DB; 830 static::require_enabled(); 831 832 // Get all the relevant contexts. 833 $contexts = self::get_related_contexts($context, $includes, 834 array('moodle/competency:competencyview', 'moodle/competency:competencymanage')); 835 836 if (empty($contexts)) { 837 throw new required_capability_exception($context, 'moodle/competency:competencyview', 'nopermissions', ''); 838 } 839 840 // OK - all set. 841 list($insql, $inparams) = $DB->get_in_or_equal(array_keys($contexts), SQL_PARAMS_NAMED); 842 $select = "contextid $insql"; 843 if ($onlyvisible) { 844 $select .= " AND visible = :visible"; 845 $inparams['visible'] = 1; 846 } 847 848 if (!empty($query) || is_numeric($query)) { 849 $sqlnamelike = $DB->sql_like('shortname', ':namelike', false); 850 $sqlidnlike = $DB->sql_like('idnumber', ':idnlike', false); 851 852 $select .= " AND ($sqlnamelike OR $sqlidnlike) "; 853 $inparams['namelike'] = '%' . $DB->sql_like_escape($query) . '%'; 854 $inparams['idnlike'] = '%' . $DB->sql_like_escape($query) . '%'; 855 } 856 857 return competency_framework::get_records_select($select, $inparams, $sort . ' ' . $order, '*', $skip, $limit); 858 } 859 860 /** 861 * Perform a search based on the provided filters and return a paginated list of records. 862 * 863 * Requires moodle/competency:competencyview capability at the system context. 864 * 865 * @param context $context The parent context of the frameworks. 866 * @param string $includes Defines what other contexts to fetch frameworks from. 867 * Accepted values are: 868 * - children: All descendants 869 * - parents: All parents, grand parents, etc... 870 * - self: Context passed only. 871 * @return int 872 */ 873 public static function count_frameworks($context, $includes) { 874 global $DB; 875 static::require_enabled(); 876 877 // Get all the relevant contexts. 878 $contexts = self::get_related_contexts($context, $includes, 879 array('moodle/competency:competencyview', 'moodle/competency:competencymanage')); 880 881 if (empty($contexts)) { 882 throw new required_capability_exception($context, 'moodle/competency:competencyview', 'nopermissions', ''); 883 } 884 885 // OK - all set. 886 list($insql, $inparams) = $DB->get_in_or_equal(array_keys($contexts), SQL_PARAMS_NAMED); 887 return competency_framework::count_records_select("contextid $insql", $inparams); 888 } 889 890 /** 891 * Fetches all the relevant contexts. 892 * 893 * Note: This currently only supports system, category and user contexts. However user contexts 894 * behave a bit differently and will fallback on the system context. This is what makes the most 895 * sense because a user context does not have descendants, and only has system as a parent. 896 * 897 * @param context $context The context to start from. 898 * @param string $includes Defines what other contexts to find. 899 * Accepted values are: 900 * - children: All descendants 901 * - parents: All parents, grand parents, etc... 902 * - self: Context passed only. 903 * @param array $hasanycapability Array of capabilities passed to {@link has_any_capability()} in each context. 904 * @return context[] An array of contexts where keys are context IDs. 905 */ 906 public static function get_related_contexts($context, $includes, array $hasanycapability = null) { 907 global $DB; 908 static::require_enabled(); 909 910 if (!in_array($includes, array('children', 'parents', 'self'))) { 911 throw new coding_exception('Invalid parameter value for \'includes\'.'); 912 } 913 914 // If context user swap it for the context_system. 915 if ($context->contextlevel == CONTEXT_USER) { 916 $context = context_system::instance(); 917 } 918 919 $contexts = array($context->id => $context); 920 921 if ($includes == 'children') { 922 $params = array('coursecatlevel' => CONTEXT_COURSECAT, 'path' => $context->path . '/%'); 923 $pathlike = $DB->sql_like('path', ':path'); 924 $sql = "contextlevel = :coursecatlevel AND $pathlike"; 925 $rs = $DB->get_recordset_select('context', $sql, $params); 926 foreach ($rs as $record) { 927 $ctxid = $record->id; 928 context_helper::preload_from_record($record); 929 $contexts[$ctxid] = context::instance_by_id($ctxid); 930 } 931 $rs->close(); 932 933 } else if ($includes == 'parents') { 934 $children = $context->get_parent_contexts(); 935 foreach ($children as $ctx) { 936 $contexts[$ctx->id] = $ctx; 937 } 938 } 939 940 // Filter according to the capabilities required. 941 if (!empty($hasanycapability)) { 942 foreach ($contexts as $key => $ctx) { 943 if (!has_any_capability($hasanycapability, $ctx)) { 944 unset($contexts[$key]); 945 } 946 } 947 } 948 949 return $contexts; 950 } 951 952 /** 953 * Count all the courses using a competency. 954 * 955 * @param int $competencyid The id of the competency to check. 956 * @return int 957 */ 958 public static function count_courses_using_competency($competencyid) { 959 static::require_enabled(); 960 961 // OK - all set. 962 $courses = course_competency::list_courses_min($competencyid); 963 $count = 0; 964 965 // Now check permissions on each course. 966 foreach ($courses as $course) { 967 if (!self::validate_course($course, false)) { 968 continue; 969 } 970 971 $context = context_course::instance($course->id); 972 $capabilities = array('moodle/competency:coursecompetencyview', 'moodle/competency:coursecompetencymanage'); 973 if (!has_any_capability($capabilities, $context)) { 974 continue; 975 } 976 977 $count++; 978 } 979 980 return $count; 981 } 982 983 /** 984 * List all the courses modules using a competency in a course. 985 * 986 * @param int $competencyid The id of the competency to check. 987 * @param int $courseid The id of the course to check. 988 * @return array[int] Array of course modules ids. 989 */ 990 public static function list_course_modules_using_competency($competencyid, $courseid) { 991 static::require_enabled(); 992 993 $result = array(); 994 self::validate_course($courseid); 995 996 $coursecontext = context_course::instance($courseid); 997 998 // We will not check each module - course permissions should be enough. 999 $capabilities = array('moodle/competency:coursecompetencyview', 'moodle/competency:coursecompetencymanage'); 1000 if (!has_any_capability($capabilities, $coursecontext)) { 1001 throw new required_capability_exception($coursecontext, 'moodle/competency:coursecompetencyview', 'nopermissions', ''); 1002 } 1003 1004 $cmlist = course_module_competency::list_course_modules($competencyid, $courseid); 1005 foreach ($cmlist as $cmid) { 1006 if (self::validate_course_module($cmid, false)) { 1007 array_push($result, $cmid); 1008 } 1009 } 1010 1011 return $result; 1012 } 1013 1014 /** 1015 * List all the competencies linked to a course module. 1016 * 1017 * @param mixed $cmorid The course module, or its ID. 1018 * @return array[competency] Array of competency records. 1019 */ 1020 public static function list_course_module_competencies_in_course_module($cmorid) { 1021 static::require_enabled(); 1022 $cm = $cmorid; 1023 if (!is_object($cmorid)) { 1024 $cm = get_coursemodule_from_id('', $cmorid, 0, true, MUST_EXIST); 1025 } 1026 1027 // Check the user have access to the course module. 1028 self::validate_course_module($cm); 1029 $context = context_module::instance($cm->id); 1030 1031 $capabilities = array('moodle/competency:coursecompetencyview', 'moodle/competency:coursecompetencymanage'); 1032 if (!has_any_capability($capabilities, $context)) { 1033 throw new required_capability_exception($context, 'moodle/competency:coursecompetencyview', 'nopermissions', ''); 1034 } 1035 1036 $result = array(); 1037 1038 $cmclist = course_module_competency::list_course_module_competencies($cm->id); 1039 foreach ($cmclist as $id => $cmc) { 1040 array_push($result, $cmc); 1041 } 1042 1043 return $result; 1044 } 1045 1046 /** 1047 * List all the courses using a competency. 1048 * 1049 * @param int $competencyid The id of the competency to check. 1050 * @return array[stdClass] Array of stdClass containing id and shortname. 1051 */ 1052 public static function list_courses_using_competency($competencyid) { 1053 static::require_enabled(); 1054 1055 // OK - all set. 1056 $courses = course_competency::list_courses($competencyid); 1057 $result = array(); 1058 1059 // Now check permissions on each course. 1060 foreach ($courses as $id => $course) { 1061 $context = context_course::instance($course->id); 1062 $capabilities = array('moodle/competency:coursecompetencyview', 'moodle/competency:coursecompetencymanage'); 1063 if (!has_any_capability($capabilities, $context)) { 1064 unset($courses[$id]); 1065 continue; 1066 } 1067 if (!self::validate_course($course, false)) { 1068 unset($courses[$id]); 1069 continue; 1070 } 1071 array_push($result, $course); 1072 } 1073 1074 return $result; 1075 } 1076 1077 /** 1078 * Count the proficient competencies in a course for one user. 1079 * 1080 * @param int $courseid The id of the course to check. 1081 * @param int $userid The id of the user to check. 1082 * @return int 1083 */ 1084 public static function count_proficient_competencies_in_course_for_user($courseid, $userid) { 1085 static::require_enabled(); 1086 // Check the user have access to the course. 1087 self::validate_course($courseid); 1088 1089 // First we do a permissions check. 1090 $context = context_course::instance($courseid); 1091 1092 $capabilities = array('moodle/competency:coursecompetencyview', 'moodle/competency:coursecompetencymanage'); 1093 if (!has_any_capability($capabilities, $context)) { 1094 throw new required_capability_exception($context, 'moodle/competency:coursecompetencyview', 'nopermissions', ''); 1095 } 1096 1097 // OK - all set. 1098 return user_competency_course::count_proficient_competencies($courseid, $userid); 1099 } 1100 1101 /** 1102 * Count all the competencies in a course. 1103 * 1104 * @param int $courseid The id of the course to check. 1105 * @return int 1106 */ 1107 public static function count_competencies_in_course($courseid) { 1108 static::require_enabled(); 1109 // Check the user have access to the course. 1110 self::validate_course($courseid); 1111 1112 // First we do a permissions check. 1113 $context = context_course::instance($courseid); 1114 1115 $capabilities = array('moodle/competency:coursecompetencyview', 'moodle/competency:coursecompetencymanage'); 1116 if (!has_any_capability($capabilities, $context)) { 1117 throw new required_capability_exception($context, 'moodle/competency:coursecompetencyview', 'nopermissions', ''); 1118 } 1119 1120 // OK - all set. 1121 return course_competency::count_competencies($courseid); 1122 } 1123 1124 /** 1125 * List the competencies associated to a course. 1126 * 1127 * @param mixed $courseorid The course, or its ID. 1128 * @return array( array( 1129 * 'competency' => \core_competency\competency, 1130 * 'coursecompetency' => \core_competency\course_competency 1131 * )) 1132 */ 1133 public static function list_course_competencies($courseorid) { 1134 static::require_enabled(); 1135 $course = $courseorid; 1136 if (!is_object($courseorid)) { 1137 $course = get_course($courseorid); 1138 } 1139 1140 // Check the user have access to the course. 1141 self::validate_course($course); 1142 $context = context_course::instance($course->id); 1143 1144 $capabilities = array('moodle/competency:coursecompetencyview', 'moodle/competency:coursecompetencymanage'); 1145 if (!has_any_capability($capabilities, $context)) { 1146 throw new required_capability_exception($context, 'moodle/competency:coursecompetencyview', 'nopermissions', ''); 1147 } 1148 1149 $result = array(); 1150 1151 // TODO We could improve the performance of this into one single query. 1152 $coursecompetencies = course_competency::list_course_competencies($course->id); 1153 $competencies = course_competency::list_competencies($course->id); 1154 1155 // Build the return values. 1156 foreach ($coursecompetencies as $key => $coursecompetency) { 1157 $result[] = array( 1158 'competency' => $competencies[$coursecompetency->get('competencyid')], 1159 'coursecompetency' => $coursecompetency 1160 ); 1161 } 1162 1163 return $result; 1164 } 1165 1166 /** 1167 * Get a user competency. 1168 * 1169 * @param int $userid The user ID. 1170 * @param int $competencyid The competency ID. 1171 * @return user_competency 1172 */ 1173 public static function get_user_competency($userid, $competencyid) { 1174 static::require_enabled(); 1175 $existing = user_competency::get_multiple($userid, array($competencyid)); 1176 $uc = array_pop($existing); 1177 1178 if (!$uc) { 1179 $uc = user_competency::create_relation($userid, $competencyid); 1180 $uc->create(); 1181 } 1182 1183 if (!$uc->can_read()) { 1184 throw new required_capability_exception($uc->get_context(), 'moodle/competency:usercompetencyview', 1185 'nopermissions', ''); 1186 } 1187 return $uc; 1188 } 1189 1190 /** 1191 * Get a user competency by ID. 1192 * 1193 * @param int $usercompetencyid The user competency ID. 1194 * @return user_competency 1195 */ 1196 public static function get_user_competency_by_id($usercompetencyid) { 1197 static::require_enabled(); 1198 $uc = new user_competency($usercompetencyid); 1199 if (!$uc->can_read()) { 1200 throw new required_capability_exception($uc->get_context(), 'moodle/competency:usercompetencyview', 1201 'nopermissions', ''); 1202 } 1203 return $uc; 1204 } 1205 1206 /** 1207 * Count the competencies associated to a course module. 1208 * 1209 * @param mixed $cmorid The course module, or its ID. 1210 * @return int 1211 */ 1212 public static function count_course_module_competencies($cmorid) { 1213 static::require_enabled(); 1214 $cm = $cmorid; 1215 if (!is_object($cmorid)) { 1216 $cm = get_coursemodule_from_id('', $cmorid, 0, true, MUST_EXIST); 1217 } 1218 1219 // Check the user have access to the course module. 1220 self::validate_course_module($cm); 1221 $context = context_module::instance($cm->id); 1222 1223 $capabilities = array('moodle/competency:coursecompetencyview', 'moodle/competency:coursecompetencymanage'); 1224 if (!has_any_capability($capabilities, $context)) { 1225 throw new required_capability_exception($context, 'moodle/competency:coursecompetencyview', 'nopermissions', ''); 1226 } 1227 1228 return course_module_competency::count_competencies($cm->id); 1229 } 1230 1231 /** 1232 * List the competencies associated to a course module. 1233 * 1234 * @param mixed $cmorid The course module, or its ID. 1235 * @return array( array( 1236 * 'competency' => \core_competency\competency, 1237 * 'coursemodulecompetency' => \core_competency\course_module_competency 1238 * )) 1239 */ 1240 public static function list_course_module_competencies($cmorid) { 1241 static::require_enabled(); 1242 $cm = $cmorid; 1243 if (!is_object($cmorid)) { 1244 $cm = get_coursemodule_from_id('', $cmorid, 0, true, MUST_EXIST); 1245 } 1246 1247 // Check the user have access to the course module. 1248 self::validate_course_module($cm); 1249 $context = context_module::instance($cm->id); 1250 1251 $capabilities = array('moodle/competency:coursecompetencyview', 'moodle/competency:coursecompetencymanage'); 1252 if (!has_any_capability($capabilities, $context)) { 1253 throw new required_capability_exception($context, 'moodle/competency:coursecompetencyview', 'nopermissions', ''); 1254 } 1255 1256 $result = array(); 1257 1258 // TODO We could improve the performance of this into one single query. 1259 $coursemodulecompetencies = course_module_competency::list_course_module_competencies($cm->id); 1260 $competencies = course_module_competency::list_competencies($cm->id); 1261 1262 // Build the return values. 1263 foreach ($coursemodulecompetencies as $key => $coursemodulecompetency) { 1264 $result[] = array( 1265 'competency' => $competencies[$coursemodulecompetency->get('competencyid')], 1266 'coursemodulecompetency' => $coursemodulecompetency 1267 ); 1268 } 1269 1270 return $result; 1271 } 1272 1273 /** 1274 * Get a user competency in a course. 1275 * 1276 * @param int $courseid The id of the course to check. 1277 * @param int $userid The id of the course to check. 1278 * @param int $competencyid The id of the competency. 1279 * @return user_competency_course 1280 */ 1281 public static function get_user_competency_in_course($courseid, $userid, $competencyid) { 1282 static::require_enabled(); 1283 // First we do a permissions check. 1284 $context = context_course::instance($courseid); 1285 1286 $capabilities = array('moodle/competency:coursecompetencyview', 'moodle/competency:coursecompetencymanage'); 1287 if (!has_any_capability($capabilities, $context)) { 1288 throw new required_capability_exception($context, 'moodle/competency:coursecompetencyview', 'nopermissions', ''); 1289 } else if (!user_competency::can_read_user_in_course($userid, $courseid)) { 1290 throw new required_capability_exception($context, 'moodle/competency:usercompetencyview', 'nopermissions', ''); 1291 } 1292 1293 // This will throw an exception if the competency does not belong to the course. 1294 $competency = course_competency::get_competency($courseid, $competencyid); 1295 1296 $params = array('courseid' => $courseid, 'userid' => $userid, 'competencyid' => $competencyid); 1297 $exists = user_competency_course::get_record($params); 1298 // Create missing. 1299 if ($exists) { 1300 $ucc = $exists; 1301 } else { 1302 $ucc = user_competency_course::create_relation($userid, $competency->get('id'), $courseid); 1303 $ucc->create(); 1304 } 1305 1306 return $ucc; 1307 } 1308 1309 /** 1310 * List all the user competencies in a course. 1311 * 1312 * @param int $courseid The id of the course to check. 1313 * @param int $userid The id of the course to check. 1314 * @return array of user_competency_course objects 1315 */ 1316 public static function list_user_competencies_in_course($courseid, $userid) { 1317 static::require_enabled(); 1318 // First we do a permissions check. 1319 $context = context_course::instance($courseid); 1320 $onlyvisible = 1; 1321 1322 $capabilities = array('moodle/competency:coursecompetencyview', 'moodle/competency:coursecompetencymanage'); 1323 if (!has_any_capability($capabilities, $context)) { 1324 throw new required_capability_exception($context, 'moodle/competency:coursecompetencyview', 'nopermissions', ''); 1325 } else if (!user_competency::can_read_user_in_course($userid, $courseid)) { 1326 throw new required_capability_exception($context, 'moodle/competency:usercompetencyview', 'nopermissions', ''); 1327 } 1328 1329 // OK - all set. 1330 $competencylist = course_competency::list_competencies($courseid, false); 1331 1332 $existing = user_competency_course::get_multiple($userid, $courseid, $competencylist); 1333 // Create missing. 1334 $orderedusercompetencycourses = array(); 1335 1336 $somemissing = false; 1337 foreach ($competencylist as $coursecompetency) { 1338 $found = false; 1339 foreach ($existing as $usercompetencycourse) { 1340 if ($usercompetencycourse->get('competencyid') == $coursecompetency->get('id')) { 1341 $found = true; 1342 $orderedusercompetencycourses[$usercompetencycourse->get('id')] = $usercompetencycourse; 1343 break; 1344 } 1345 } 1346 if (!$found) { 1347 $ucc = user_competency_course::create_relation($userid, $coursecompetency->get('id'), $courseid); 1348 $ucc->create(); 1349 $orderedusercompetencycourses[$ucc->get('id')] = $ucc; 1350 } 1351 } 1352 1353 return $orderedusercompetencycourses; 1354 } 1355 1356 /** 1357 * List the user competencies to review. 1358 * 1359 * The method returns values in this format: 1360 * 1361 * array( 1362 * 'competencies' => array( 1363 * (stdClass)( 1364 * 'usercompetency' => (user_competency), 1365 * 'competency' => (competency), 1366 * 'user' => (user) 1367 * ) 1368 * ), 1369 * 'count' => (int) 1370 * ) 1371 * 1372 * @param int $skip The number of records to skip. 1373 * @param int $limit The number of results to return. 1374 * @param int $userid The user we're getting the competencies to review for. 1375 * @return array Containing the keys 'count', and 'competencies'. The 'competencies' key contains an object 1376 * which contains 'competency', 'usercompetency' and 'user'. 1377 */ 1378 public static function list_user_competencies_to_review($skip = 0, $limit = 50, $userid = null) { 1379 global $DB, $USER; 1380 static::require_enabled(); 1381 if ($userid === null) { 1382 $userid = $USER->id; 1383 } 1384 1385 $capability = 'moodle/competency:usercompetencyreview'; 1386 $ucfields = user_competency::get_sql_fields('uc', 'uc_'); 1387 $compfields = competency::get_sql_fields('c', 'c_'); 1388 $usercols = array('id') + get_user_fieldnames(); 1389 $userfields = array(); 1390 foreach ($usercols as $field) { 1391 $userfields[] = "u." . $field . " AS usr_" . $field; 1392 } 1393 $userfields = implode(',', $userfields); 1394 1395 $select = "SELECT $ucfields, $compfields, $userfields"; 1396 $countselect = "SELECT COUNT('x')"; 1397 $sql = " FROM {" . user_competency::TABLE . "} uc 1398 JOIN {" . competency::TABLE . "} c 1399 ON c.id = uc.competencyid 1400 JOIN {user} u 1401 ON u.id = uc.userid 1402 WHERE (uc.status = :waitingforreview 1403 OR (uc.status = :inreview AND uc.reviewerid = :reviewerid)) 1404 AND u.deleted = 0"; 1405 $ordersql = " ORDER BY c.shortname ASC"; 1406 $params = array( 1407 'inreview' => user_competency::STATUS_IN_REVIEW, 1408 'reviewerid' => $userid, 1409 'waitingforreview' => user_competency::STATUS_WAITING_FOR_REVIEW, 1410 ); 1411 $countsql = $countselect . $sql; 1412 1413 // Primary check to avoid the hard work of getting the users in which the user has permission. 1414 $count = $DB->count_records_sql($countselect . $sql, $params); 1415 if ($count < 1) { 1416 return array('count' => 0, 'competencies' => array()); 1417 } 1418 1419 // TODO MDL-52243 Use core function. 1420 list($insql, $inparams) = self::filter_users_with_capability_on_user_context_sql( 1421 $capability, $userid, SQL_PARAMS_NAMED); 1422 $params += $inparams; 1423 $countsql = $countselect . $sql . " AND uc.userid $insql"; 1424 $getsql = $select . $sql . " AND uc.userid $insql " . $ordersql; 1425 1426 // Extracting the results. 1427 $competencies = array(); 1428 $records = $DB->get_recordset_sql($getsql, $params, $skip, $limit); 1429 foreach ($records as $record) { 1430 $objects = (object) array( 1431 'usercompetency' => new user_competency(0, user_competency::extract_record($record, 'uc_')), 1432 'competency' => new competency(0, competency::extract_record($record, 'c_')), 1433 'user' => persistent::extract_record($record, 'usr_'), 1434 ); 1435 $competencies[] = $objects; 1436 } 1437 $records->close(); 1438 1439 return array( 1440 'count' => $DB->count_records_sql($countsql, $params), 1441 'competencies' => $competencies 1442 ); 1443 } 1444 1445 /** 1446 * Add a competency to this course module. 1447 * 1448 * @param mixed $cmorid The course module, or id of the course module 1449 * @param int $competencyid The id of the competency 1450 * @return bool 1451 */ 1452 public static function add_competency_to_course_module($cmorid, $competencyid) { 1453 static::require_enabled(); 1454 $cm = $cmorid; 1455 if (!is_object($cmorid)) { 1456 $cm = get_coursemodule_from_id('', $cmorid, 0, true, MUST_EXIST); 1457 } 1458 1459 // Check the user have access to the course module. 1460 self::validate_course_module($cm); 1461 1462 // First we do a permissions check. 1463 $context = context_module::instance($cm->id); 1464 1465 require_capability('moodle/competency:coursecompetencymanage', $context); 1466 1467 // Check that the competency belongs to the course. 1468 $exists = course_competency::get_records(array('courseid' => $cm->course, 'competencyid' => $competencyid)); 1469 if (!$exists) { 1470 throw new coding_exception('Cannot add a competency to a module if it does not belong to the course'); 1471 } 1472 1473 $record = new stdClass(); 1474 $record->cmid = $cm->id; 1475 $record->competencyid = $competencyid; 1476 1477 $coursemodulecompetency = new course_module_competency(); 1478 $exists = $coursemodulecompetency->get_records(array('cmid' => $cm->id, 'competencyid' => $competencyid)); 1479 if (!$exists) { 1480 $coursemodulecompetency->from_record($record); 1481 if ($coursemodulecompetency->create()) { 1482 return true; 1483 } 1484 } 1485 return false; 1486 } 1487 1488 /** 1489 * Remove a competency from this course module. 1490 * 1491 * @param mixed $cmorid The course module, or id of the course module 1492 * @param int $competencyid The id of the competency 1493 * @return bool 1494 */ 1495 public static function remove_competency_from_course_module($cmorid, $competencyid) { 1496 static::require_enabled(); 1497 $cm = $cmorid; 1498 if (!is_object($cmorid)) { 1499 $cm = get_coursemodule_from_id('', $cmorid, 0, true, MUST_EXIST); 1500 } 1501 // Check the user have access to the course module. 1502 self::validate_course_module($cm); 1503 1504 // First we do a permissions check. 1505 $context = context_module::instance($cm->id); 1506 1507 require_capability('moodle/competency:coursecompetencymanage', $context); 1508 1509 $record = new stdClass(); 1510 $record->cmid = $cm->id; 1511 $record->competencyid = $competencyid; 1512 1513 $competency = new competency($competencyid); 1514 $exists = course_module_competency::get_record(array('cmid' => $cm->id, 'competencyid' => $competencyid)); 1515 if ($exists) { 1516 return $exists->delete(); 1517 } 1518 return false; 1519 } 1520 1521 /** 1522 * Move the course module competency up or down in the display list. 1523 * 1524 * Requires moodle/competency:coursecompetencymanage capability at the course module context. 1525 * 1526 * @param mixed $cmorid The course module, or id of the course module 1527 * @param int $competencyidfrom The id of the competency we are moving. 1528 * @param int $competencyidto The id of the competency we are moving to. 1529 * @return boolean 1530 */ 1531 public static function reorder_course_module_competency($cmorid, $competencyidfrom, $competencyidto) { 1532 static::require_enabled(); 1533 $cm = $cmorid; 1534 if (!is_object($cmorid)) { 1535 $cm = get_coursemodule_from_id('', $cmorid, 0, true, MUST_EXIST); 1536 } 1537 // Check the user have access to the course module. 1538 self::validate_course_module($cm); 1539 1540 // First we do a permissions check. 1541 $context = context_module::instance($cm->id); 1542 1543 require_capability('moodle/competency:coursecompetencymanage', $context); 1544 1545 $down = true; 1546 $matches = course_module_competency::get_records(array('cmid' => $cm->id, 'competencyid' => $competencyidfrom)); 1547 if (count($matches) == 0) { 1548 throw new coding_exception('The link does not exist'); 1549 } 1550 1551 $competencyfrom = array_pop($matches); 1552 $matches = course_module_competency::get_records(array('cmid' => $cm->id, 'competencyid' => $competencyidto)); 1553 if (count($matches) == 0) { 1554 throw new coding_exception('The link does not exist'); 1555 } 1556 1557 $competencyto = array_pop($matches); 1558 1559 $all = course_module_competency::get_records(array('cmid' => $cm->id), 'sortorder', 'ASC', 0, 0); 1560 1561 if ($competencyfrom->get('sortorder') > $competencyto->get('sortorder')) { 1562 // We are moving up, so put it before the "to" item. 1563 $down = false; 1564 } 1565 1566 foreach ($all as $id => $coursemodulecompetency) { 1567 $sort = $coursemodulecompetency->get('sortorder'); 1568 if ($down && $sort > $competencyfrom->get('sortorder') && $sort <= $competencyto->get('sortorder')) { 1569 $coursemodulecompetency->set('sortorder', $coursemodulecompetency->get('sortorder') - 1); 1570 $coursemodulecompetency->update(); 1571 } else if (!$down && $sort >= $competencyto->get('sortorder') && $sort < $competencyfrom->get('sortorder')) { 1572 $coursemodulecompetency->set('sortorder', $coursemodulecompetency->get('sortorder') + 1); 1573 $coursemodulecompetency->update(); 1574 } 1575 } 1576 $competencyfrom->set('sortorder', $competencyto->get('sortorder')); 1577 return $competencyfrom->update(); 1578 } 1579 1580 /** 1581 * Update ruleoutcome value for a course module competency. 1582 * 1583 * @param int|course_module_competency $coursemodulecompetencyorid The course_module_competency, or its ID. 1584 * @param int $ruleoutcome The value of ruleoutcome. 1585 * @param bool $overridegrade If true, will override existing grades in related competencies. 1586 * @return bool True on success. 1587 */ 1588 public static function set_course_module_competency_ruleoutcome($coursemodulecompetencyorid, $ruleoutcome, 1589 $overridegrade = false) { 1590 static::require_enabled(); 1591 $coursemodulecompetency = $coursemodulecompetencyorid; 1592 if (!is_object($coursemodulecompetency)) { 1593 $coursemodulecompetency = new course_module_competency($coursemodulecompetencyorid); 1594 } 1595 1596 $cm = get_coursemodule_from_id('', $coursemodulecompetency->get('cmid'), 0, true, MUST_EXIST); 1597 1598 self::validate_course_module($cm); 1599 $context = context_module::instance($cm->id); 1600 1601 require_capability('moodle/competency:coursecompetencymanage', $context); 1602 1603 $coursemodulecompetency->set('ruleoutcome', $ruleoutcome); 1604 $coursemodulecompetency->set('overridegrade', $overridegrade); 1605 1606 return $coursemodulecompetency->update(); 1607 } 1608 1609 /** 1610 * Add a competency to this course. 1611 * 1612 * @param int $courseid The id of the course 1613 * @param int $competencyid The id of the competency 1614 * @return bool 1615 */ 1616 public static function add_competency_to_course($courseid, $competencyid) { 1617 static::require_enabled(); 1618 // Check the user have access to the course. 1619 self::validate_course($courseid); 1620 1621 // First we do a permissions check. 1622 $context = context_course::instance($courseid); 1623 1624 require_capability('moodle/competency:coursecompetencymanage', $context); 1625 1626 $record = new stdClass(); 1627 $record->courseid = $courseid; 1628 $record->competencyid = $competencyid; 1629 1630 $competency = new competency($competencyid); 1631 1632 // Can not add a competency that belong to a hidden framework. 1633 if ($competency->get_framework()->get('visible') == false) { 1634 throw new coding_exception('A competency belonging to hidden framework can not be linked to course'); 1635 } 1636 1637 $coursecompetency = new course_competency(); 1638 $exists = $coursecompetency->get_records(array('courseid' => $courseid, 'competencyid' => $competencyid)); 1639 if (!$exists) { 1640 $coursecompetency->from_record($record); 1641 if ($coursecompetency->create()) { 1642 return true; 1643 } 1644 } 1645 return false; 1646 } 1647 1648 /** 1649 * Remove a competency from this course. 1650 * 1651 * @param int $courseid The id of the course 1652 * @param int $competencyid The id of the competency 1653 * @return bool 1654 */ 1655 public static function remove_competency_from_course($courseid, $competencyid) { 1656 static::require_enabled(); 1657 // Check the user have access to the course. 1658 self::validate_course($courseid); 1659 1660 // First we do a permissions check. 1661 $context = context_course::instance($courseid); 1662 1663 require_capability('moodle/competency:coursecompetencymanage', $context); 1664 1665 $record = new stdClass(); 1666 $record->courseid = $courseid; 1667 $record->competencyid = $competencyid; 1668 1669 $coursecompetency = new course_competency(); 1670 $exists = course_competency::get_record(array('courseid' => $courseid, 'competencyid' => $competencyid)); 1671 if ($exists) { 1672 // Delete all course_module_competencies for this competency in this course. 1673 $cmcs = course_module_competency::get_records_by_competencyid_in_course($competencyid, $courseid); 1674 foreach ($cmcs as $cmc) { 1675 $cmc->delete(); 1676 } 1677 return $exists->delete(); 1678 } 1679 return false; 1680 } 1681 1682 /** 1683 * Move the course competency up or down in the display list. 1684 * 1685 * Requires moodle/competency:coursecompetencymanage capability at the course context. 1686 * 1687 * @param int $courseid The course 1688 * @param int $competencyidfrom The id of the competency we are moving. 1689 * @param int $competencyidto The id of the competency we are moving to. 1690 * @return boolean 1691 */ 1692 public static function reorder_course_competency($courseid, $competencyidfrom, $competencyidto) { 1693 static::require_enabled(); 1694 // Check the user have access to the course. 1695 self::validate_course($courseid); 1696 1697 // First we do a permissions check. 1698 $context = context_course::instance($courseid); 1699 1700 require_capability('moodle/competency:coursecompetencymanage', $context); 1701 1702 $down = true; 1703 $coursecompetency = new course_competency(); 1704 $matches = $coursecompetency->get_records(array('courseid' => $courseid, 'competencyid' => $competencyidfrom)); 1705 if (count($matches) == 0) { 1706 throw new coding_exception('The link does not exist'); 1707 } 1708 1709 $competencyfrom = array_pop($matches); 1710 $matches = $coursecompetency->get_records(array('courseid' => $courseid, 'competencyid' => $competencyidto)); 1711 if (count($matches) == 0) { 1712 throw new coding_exception('The link does not exist'); 1713 } 1714 1715 $competencyto = array_pop($matches); 1716 1717 $all = $coursecompetency->get_records(array('courseid' => $courseid), 'sortorder', 'ASC', 0, 0); 1718 1719 if ($competencyfrom->get('sortorder') > $competencyto->get('sortorder')) { 1720 // We are moving up, so put it before the "to" item. 1721 $down = false; 1722 } 1723 1724 foreach ($all as $id => $coursecompetency) { 1725 $sort = $coursecompetency->get('sortorder'); 1726 if ($down && $sort > $competencyfrom->get('sortorder') && $sort <= $competencyto->get('sortorder')) { 1727 $coursecompetency->set('sortorder', $coursecompetency->get('sortorder') - 1); 1728 $coursecompetency->update(); 1729 } else if (!$down && $sort >= $competencyto->get('sortorder') && $sort < $competencyfrom->get('sortorder')) { 1730 $coursecompetency->set('sortorder', $coursecompetency->get('sortorder') + 1); 1731 $coursecompetency->update(); 1732 } 1733 } 1734 $competencyfrom->set('sortorder', $competencyto->get('sortorder')); 1735 return $competencyfrom->update(); 1736 } 1737 1738 /** 1739 * Update ruleoutcome value for a course competency. 1740 * 1741 * @param int|course_competency $coursecompetencyorid The course_competency, or its ID. 1742 * @param int $ruleoutcome The value of ruleoutcome. 1743 * @return bool True on success. 1744 */ 1745 public static function set_course_competency_ruleoutcome($coursecompetencyorid, $ruleoutcome) { 1746 static::require_enabled(); 1747 $coursecompetency = $coursecompetencyorid; 1748 if (!is_object($coursecompetency)) { 1749 $coursecompetency = new course_competency($coursecompetencyorid); 1750 } 1751 1752 $courseid = $coursecompetency->get('courseid'); 1753 self::validate_course($courseid); 1754 $coursecontext = context_course::instance($courseid); 1755 1756 require_capability('moodle/competency:coursecompetencymanage', $coursecontext); 1757 1758 $coursecompetency->set('ruleoutcome', $ruleoutcome); 1759 return $coursecompetency->update(); 1760 } 1761 1762 /** 1763 * Create a learning plan template from a record containing all the data for the class. 1764 * 1765 * Requires moodle/competency:templatemanage capability. 1766 * 1767 * @param stdClass $record Record containing all the data for an instance of the class. 1768 * @return template 1769 */ 1770 public static function create_template(stdClass $record) { 1771 static::require_enabled(); 1772 $template = new template(0, $record); 1773 1774 // First we do a permissions check. 1775 if (!$template->can_manage()) { 1776 throw new required_capability_exception($template->get_context(), 'moodle/competency:templatemanage', 1777 'nopermissions', ''); 1778 } 1779 1780 // OK - all set. 1781 $template = $template->create(); 1782 1783 // Trigger a template created event. 1784 \core\event\competency_template_created::create_from_template($template)->trigger(); 1785 1786 return $template; 1787 } 1788 1789 /** 1790 * Duplicate a learning plan template. 1791 * 1792 * Requires moodle/competency:templatemanage capability at the template context. 1793 * 1794 * @param int $id the template id. 1795 * @return template 1796 */ 1797 public static function duplicate_template($id) { 1798 static::require_enabled(); 1799 $template = new template($id); 1800 1801 // First we do a permissions check. 1802 if (!$template->can_manage()) { 1803 throw new required_capability_exception($template->get_context(), 'moodle/competency:templatemanage', 1804 'nopermissions', ''); 1805 } 1806 1807 // OK - all set. 1808 $competencies = template_competency::list_competencies($id, false); 1809 1810 // Adding the suffix copy. 1811 $template->set('shortname', get_string('duplicateditemname', 'core_competency', $template->get('shortname'))); 1812 $template->set('id', 0); 1813 1814 $duplicatedtemplate = $template->create(); 1815 1816 // Associate each competency for the duplicated template. 1817 foreach ($competencies as $competency) { 1818 self::add_competency_to_template($duplicatedtemplate->get('id'), $competency->get('id')); 1819 } 1820 1821 // Trigger a template created event. 1822 \core\event\competency_template_created::create_from_template($duplicatedtemplate)->trigger(); 1823 1824 return $duplicatedtemplate; 1825 } 1826 1827 /** 1828 * Delete a learning plan template by id. 1829 * If the learning plan template has associated cohorts they will be deleted. 1830 * 1831 * Requires moodle/competency:templatemanage capability. 1832 * 1833 * @param int $id The record to delete. 1834 * @param boolean $deleteplans True to delete plans associaated to template, false to unlink them. 1835 * @return boolean 1836 */ 1837 public static function delete_template($id, $deleteplans = true) { 1838 global $DB; 1839 static::require_enabled(); 1840 $template = new template($id); 1841 1842 // First we do a permissions check. 1843 if (!$template->can_manage()) { 1844 throw new required_capability_exception($template->get_context(), 'moodle/competency:templatemanage', 1845 'nopermissions', ''); 1846 } 1847 1848 $transaction = $DB->start_delegated_transaction(); 1849 $success = true; 1850 1851 // Check if there are cohorts associated. 1852 $templatecohorts = template_cohort::get_relations_by_templateid($template->get('id')); 1853 foreach ($templatecohorts as $templatecohort) { 1854 $success = $templatecohort->delete(); 1855 if (!$success) { 1856 break; 1857 } 1858 } 1859 1860 // Still OK, delete or unlink the plans from the template. 1861 if ($success) { 1862 $plans = plan::get_records(array('templateid' => $template->get('id'))); 1863 foreach ($plans as $plan) { 1864 $success = $deleteplans ? self::delete_plan($plan->get('id')) : self::unlink_plan_from_template($plan); 1865 if (!$success) { 1866 break; 1867 } 1868 } 1869 } 1870 1871 // Still OK, delete the template comptencies. 1872 if ($success) { 1873 $success = template_competency::delete_by_templateid($template->get('id')); 1874 } 1875 1876 // OK - all set. 1877 if ($success) { 1878 // Create a template deleted event. 1879 $event = \core\event\competency_template_deleted::create_from_template($template); 1880 1881 $success = $template->delete(); 1882 } 1883 1884 if ($success) { 1885 // Trigger a template deleted event. 1886 $event->trigger(); 1887 1888 // Commit the transaction. 1889 $transaction->allow_commit(); 1890 } else { 1891 $transaction->rollback(new moodle_exception('Error while deleting the template.')); 1892 } 1893 1894 return $success; 1895 } 1896 1897 /** 1898 * Update the details for a learning plan template. 1899 * 1900 * Requires moodle/competency:templatemanage capability. 1901 * 1902 * @param stdClass $record The new details for the template. Note - must contain an id that points to the template to update. 1903 * @return boolean 1904 */ 1905 public static function update_template($record) { 1906 global $DB; 1907 static::require_enabled(); 1908 $template = new template($record->id); 1909 1910 // First we do a permissions check. 1911 if (!$template->can_manage()) { 1912 throw new required_capability_exception($template->get_context(), 'moodle/competency:templatemanage', 1913 'nopermissions', ''); 1914 1915 } else if (isset($record->contextid) && $record->contextid != $template->get('contextid')) { 1916 // We can never change the context of a template. 1917 throw new coding_exception('Changing the context of an existing tempalte is forbidden.'); 1918 1919 } 1920 1921 $updateplans = false; 1922 $before = $template->to_record(); 1923 1924 $template->from_record($record); 1925 $after = $template->to_record(); 1926 1927 // Should we update the related plans? 1928 if ($before->duedate != $after->duedate || 1929 $before->shortname != $after->shortname || 1930 $before->description != $after->description || 1931 $before->descriptionformat != $after->descriptionformat) { 1932 $updateplans = true; 1933 } 1934 1935 $transaction = $DB->start_delegated_transaction(); 1936 $success = $template->update(); 1937 1938 if (!$success) { 1939 $transaction->rollback(new moodle_exception('Error while updating the template.')); 1940 return $success; 1941 } 1942 1943 // Trigger a template updated event. 1944 \core\event\competency_template_updated::create_from_template($template)->trigger(); 1945 1946 if ($updateplans) { 1947 plan::update_multiple_from_template($template); 1948 } 1949 1950 $transaction->allow_commit(); 1951 1952 return $success; 1953 } 1954 1955 /** 1956 * Read a the details for a single learning plan template and return a record. 1957 * 1958 * Requires moodle/competency:templateview capability at the system context. 1959 * 1960 * @param int $id The id of the template to read. 1961 * @return template 1962 */ 1963 public static function read_template($id) { 1964 static::require_enabled(); 1965 $template = new template($id); 1966 $context = $template->get_context(); 1967 1968 // First we do a permissions check. 1969 if (!$template->can_read()) { 1970 throw new required_capability_exception($template->get_context(), 'moodle/competency:templateview', 1971 'nopermissions', ''); 1972 } 1973 1974 // OK - all set. 1975 return $template; 1976 } 1977 1978 /** 1979 * Perform a search based on the provided filters and return a paginated list of records. 1980 * 1981 * Requires moodle/competency:templateview capability at the system context. 1982 * 1983 * @param string $sort The column to sort on 1984 * @param string $order ('ASC' or 'DESC') 1985 * @param int $skip Number of records to skip (pagination) 1986 * @param int $limit Max of records to return (pagination) 1987 * @param context $context The parent context of the frameworks. 1988 * @param string $includes Defines what other contexts to fetch frameworks from. 1989 * Accepted values are: 1990 * - children: All descendants 1991 * - parents: All parents, grand parents, etc... 1992 * - self: Context passed only. 1993 * @param bool $onlyvisible If should list only visible templates 1994 * @return array of competency_framework 1995 */ 1996 public static function list_templates($sort, $order, $skip, $limit, $context, $includes = 'children', $onlyvisible = false) { 1997 global $DB; 1998 static::require_enabled(); 1999 2000 // Get all the relevant contexts. 2001 $contexts = self::get_related_contexts($context, $includes, 2002 array('moodle/competency:templateview', 'moodle/competency:templatemanage')); 2003 2004 // First we do a permissions check. 2005 if (empty($contexts)) { 2006 throw new required_capability_exception($context, 'moodle/competency:templateview', 'nopermissions', ''); 2007 } 2008 2009 // Make the order by. 2010 $orderby = ''; 2011 if (!empty($sort)) { 2012 $orderby = $sort . ' ' . $order; 2013 } 2014 2015 // OK - all set. 2016 $template = new template(); 2017 list($insql, $params) = $DB->get_in_or_equal(array_keys($contexts), SQL_PARAMS_NAMED); 2018 $select = "contextid $insql"; 2019 2020 if ($onlyvisible) { 2021 $select .= " AND visible = :visible"; 2022 $params['visible'] = 1; 2023 } 2024 return $template->get_records_select($select, $params, $orderby, '*', $skip, $limit); 2025 } 2026 2027 /** 2028 * Perform a search based on the provided filters and return how many results there are. 2029 * 2030 * Requires moodle/competency:templateview capability at the system context. 2031 * 2032 * @param context $context The parent context of the frameworks. 2033 * @param string $includes Defines what other contexts to fetch frameworks from. 2034 * Accepted values are: 2035 * - children: All descendants 2036 * - parents: All parents, grand parents, etc... 2037 * - self: Context passed only. 2038 * @return int 2039 */ 2040 public static function count_templates($context, $includes) { 2041 global $DB; 2042 static::require_enabled(); 2043 2044 // First we do a permissions check. 2045 $contexts = self::get_related_contexts($context, $includes, 2046 array('moodle/competency:templateview', 'moodle/competency:templatemanage')); 2047 2048 if (empty($contexts)) { 2049 throw new required_capability_exception($context, 'moodle/competency:templateview', 'nopermissions', ''); 2050 } 2051 2052 // OK - all set. 2053 $template = new template(); 2054 list($insql, $inparams) = $DB->get_in_or_equal(array_keys($contexts), SQL_PARAMS_NAMED); 2055 return $template->count_records_select("contextid $insql", $inparams); 2056 } 2057 2058 /** 2059 * Count all the templates using a competency. 2060 * 2061 * @param int $competencyid The id of the competency to check. 2062 * @return int 2063 */ 2064 public static function count_templates_using_competency($competencyid) { 2065 static::require_enabled(); 2066 // First we do a permissions check. 2067 $context = context_system::instance(); 2068 $onlyvisible = 1; 2069 2070 $capabilities = array('moodle/competency:templateview', 'moodle/competency:templatemanage'); 2071 if (!has_any_capability($capabilities, $context)) { 2072 throw new required_capability_exception($context, 'moodle/competency:templateview', 'nopermissions', ''); 2073 } 2074 2075 if (has_capability('moodle/competency:templatemanage', $context)) { 2076 $onlyvisible = 0; 2077 } 2078 2079 // OK - all set. 2080 return template_competency::count_templates($competencyid, $onlyvisible); 2081 } 2082 2083 /** 2084 * List all the learning plan templatesd using a competency. 2085 * 2086 * @param int $competencyid The id of the competency to check. 2087 * @return array[stdClass] Array of stdClass containing id and shortname. 2088 */ 2089 public static function list_templates_using_competency($competencyid) { 2090 static::require_enabled(); 2091 // First we do a permissions check. 2092 $context = context_system::instance(); 2093 $onlyvisible = 1; 2094 2095 $capabilities = array('moodle/competency:templateview', 'moodle/competency:templatemanage'); 2096 if (!has_any_capability($capabilities, $context)) { 2097 throw new required_capability_exception($context, 'moodle/competency:templateview', 'nopermissions', ''); 2098 } 2099 2100 if (has_capability('moodle/competency:templatemanage', $context)) { 2101 $onlyvisible = 0; 2102 } 2103 2104 // OK - all set. 2105 return template_competency::list_templates($competencyid, $onlyvisible); 2106 2107 } 2108 2109 /** 2110 * Count all the competencies in a learning plan template. 2111 * 2112 * @param template|int $templateorid The template or its ID. 2113 * @return int 2114 */ 2115 public static function count_competencies_in_template($templateorid) { 2116 static::require_enabled(); 2117 // First we do a permissions check. 2118 $template = $templateorid; 2119 if (!is_object($template)) { 2120 $template = new template($template); 2121 } 2122 2123 if (!$template->can_read()) { 2124 throw new required_capability_exception($template->get_context(), 'moodle/competency:templateview', 2125 'nopermissions', ''); 2126 } 2127 2128 // OK - all set. 2129 return template_competency::count_competencies($template->get('id')); 2130 } 2131 2132 /** 2133 * Count all the competencies in a learning plan template with no linked courses. 2134 * 2135 * @param template|int $templateorid The template or its ID. 2136 * @return int 2137 */ 2138 public static function count_competencies_in_template_with_no_courses($templateorid) { 2139 // First we do a permissions check. 2140 $template = $templateorid; 2141 if (!is_object($template)) { 2142 $template = new template($template); 2143 } 2144 2145 if (!$template->can_read()) { 2146 throw new required_capability_exception($template->get_context(), 'moodle/competency:templateview', 2147 'nopermissions', ''); 2148 } 2149 2150 // OK - all set. 2151 return template_competency::count_competencies_with_no_courses($template->get('id')); 2152 } 2153 2154 /** 2155 * List all the competencies in a template. 2156 * 2157 * @param template|int $templateorid The template or its ID. 2158 * @return array of competencies 2159 */ 2160 public static function list_competencies_in_template($templateorid) { 2161 static::require_enabled(); 2162 // First we do a permissions check. 2163 $template = $templateorid; 2164 if (!is_object($template)) { 2165 $template = new template($template); 2166 } 2167 2168 if (!$template->can_read()) { 2169 throw new required_capability_exception($template->get_context(), 'moodle/competency:templateview', 2170 'nopermissions', ''); 2171 } 2172 2173 // OK - all set. 2174 return template_competency::list_competencies($template->get('id')); 2175 } 2176 2177 /** 2178 * Add a competency to this template. 2179 * 2180 * @param int $templateid The id of the template 2181 * @param int $competencyid The id of the competency 2182 * @return bool 2183 */ 2184 public static function add_competency_to_template($templateid, $competencyid) { 2185 static::require_enabled(); 2186 // First we do a permissions check. 2187 $template = new template($templateid); 2188 if (!$template->can_manage()) { 2189 throw new required_capability_exception($template->get_context(), 'moodle/competency:templatemanage', 2190 'nopermissions', ''); 2191 } 2192 2193 $record = new stdClass(); 2194 $record->templateid = $templateid; 2195 $record->competencyid = $competencyid; 2196 2197 $competency = new competency($competencyid); 2198 2199 // Can not add a competency that belong to a hidden framework. 2200 if ($competency->get_framework()->get('visible') == false) { 2201 throw new coding_exception('A competency belonging to hidden framework can not be added'); 2202 } 2203 2204 $exists = template_competency::get_records(array('templateid' => $templateid, 'competencyid' => $competencyid)); 2205 if (!$exists) { 2206 $templatecompetency = new template_competency(0, $record); 2207 $templatecompetency->create(); 2208 return true; 2209 } 2210 return false; 2211 } 2212 2213 /** 2214 * Remove a competency from this template. 2215 * 2216 * @param int $templateid The id of the template 2217 * @param int $competencyid The id of the competency 2218 * @return bool 2219 */ 2220 public static function remove_competency_from_template($templateid, $competencyid) { 2221 static::require_enabled(); 2222 // First we do a permissions check. 2223 $template = new template($templateid); 2224 if (!$template->can_manage()) { 2225 throw new required_capability_exception($template->get_context(), 'moodle/competency:templatemanage', 2226 'nopermissions', ''); 2227 } 2228 2229 $record = new stdClass(); 2230 $record->templateid = $templateid; 2231 $record->competencyid = $competencyid; 2232 2233 $competency = new competency($competencyid); 2234 2235 $exists = template_competency::get_records(array('templateid' => $templateid, 'competencyid' => $competencyid)); 2236 if ($exists) { 2237 $link = array_pop($exists); 2238 return $link->delete(); 2239 } 2240 return false; 2241 } 2242 2243 /** 2244 * Move the template competency up or down in the display list. 2245 * 2246 * Requires moodle/competency:templatemanage capability at the system context. 2247 * 2248 * @param int $templateid The template id 2249 * @param int $competencyidfrom The id of the competency we are moving. 2250 * @param int $competencyidto The id of the competency we are moving to. 2251 * @return boolean 2252 */ 2253 public static function reorder_template_competency($templateid, $competencyidfrom, $competencyidto) { 2254 static::require_enabled(); 2255 $template = new template($templateid); 2256 2257 // First we do a permissions check. 2258 if (!$template->can_manage()) { 2259 throw new required_capability_exception($template->get_context(), 'moodle/competency:templatemanage', 2260 'nopermissions', ''); 2261 } 2262 2263 $down = true; 2264 $matches = template_competency::get_records(array('templateid' => $templateid, 'competencyid' => $competencyidfrom)); 2265 if (count($matches) == 0) { 2266 throw new coding_exception('The link does not exist'); 2267 } 2268 2269 $competencyfrom = array_pop($matches); 2270 $matches = template_competency::get_records(array('templateid' => $templateid, 'competencyid' => $competencyidto)); 2271 if (count($matches) == 0) { 2272 throw new coding_exception('The link does not exist'); 2273 } 2274 2275 $competencyto = array_pop($matches); 2276 2277 $all = template_competency::get_records(array('templateid' => $templateid), 'sortorder', 'ASC', 0, 0); 2278 2279 if ($competencyfrom->get('sortorder') > $competencyto->get('sortorder')) { 2280 // We are moving up, so put it before the "to" item. 2281 $down = false; 2282 } 2283 2284 foreach ($all as $id => $templatecompetency) { 2285 $sort = $templatecompetency->get('sortorder'); 2286 if ($down && $sort > $competencyfrom->get('sortorder') && $sort <= $competencyto->get('sortorder')) { 2287 $templatecompetency->set('sortorder', $templatecompetency->get('sortorder') - 1); 2288 $templatecompetency->update(); 2289 } else if (!$down && $sort >= $competencyto->get('sortorder') && $sort < $competencyfrom->get('sortorder')) { 2290 $templatecompetency->set('sortorder', $templatecompetency->get('sortorder') + 1); 2291 $templatecompetency->update(); 2292 } 2293 } 2294 $competencyfrom->set('sortorder', $competencyto->get('sortorder')); 2295 return $competencyfrom->update(); 2296 } 2297 2298 /** 2299 * Create a relation between a template and a cohort. 2300 * 2301 * This silently ignores when the relation already existed. 2302 * 2303 * @param template|int $templateorid The template or its ID. 2304 * @param stdClass|int $cohortorid The cohort ot its ID. 2305 * @return template_cohort 2306 */ 2307 public static function create_template_cohort($templateorid, $cohortorid) { 2308 global $DB; 2309 static::require_enabled(); 2310 2311 $template = $templateorid; 2312 if (!is_object($template)) { 2313 $template = new template($template); 2314 } 2315 require_capability('moodle/competency:templatemanage', $template->get_context()); 2316 2317 $cohort = $cohortorid; 2318 if (!is_object($cohort)) { 2319 $cohort = $DB->get_record('cohort', array('id' => $cohort), '*', MUST_EXIST); 2320 } 2321 2322 // Replicate logic in cohort_can_view_cohort() because we can't use it directly as we don't have a course context. 2323 $cohortcontext = context::instance_by_id($cohort->contextid); 2324 if (!$cohort->visible && !has_capability('moodle/cohort:view', $cohortcontext)) { 2325 throw new required_capability_exception($cohortcontext, 'moodle/cohort:view', 'nopermissions', ''); 2326 } 2327 2328 $tplcohort = template_cohort::get_relation($template->get('id'), $cohort->id); 2329 if (!$tplcohort->get('id')) { 2330 $tplcohort->create(); 2331 } 2332 2333 return $tplcohort; 2334 } 2335 2336 /** 2337 * Remove a relation between a template and a cohort. 2338 * 2339 * @param template|int $templateorid The template or its ID. 2340 * @param stdClass|int $cohortorid The cohort ot its ID. 2341 * @return boolean True on success or when the relation did not exist. 2342 */ 2343 public static function delete_template_cohort($templateorid, $cohortorid) { 2344 global $DB; 2345 static::require_enabled(); 2346 2347 $template = $templateorid; 2348 if (!is_object($template)) { 2349 $template = new template($template); 2350 } 2351 require_capability('moodle/competency:templatemanage', $template->get_context()); 2352 2353 $cohort = $cohortorid; 2354 if (!is_object($cohort)) { 2355 $cohort = $DB->get_record('cohort', array('id' => $cohort), '*', MUST_EXIST); 2356 } 2357 2358 $tplcohort = template_cohort::get_relation($template->get('id'), $cohort->id); 2359 if (!$tplcohort->get('id')) { 2360 return true; 2361 } 2362 2363 return $tplcohort->delete(); 2364 } 2365 2366 /** 2367 * Lists user plans. 2368 * 2369 * @param int $userid 2370 * @return \core_competency\plan[] 2371 */ 2372 public static function list_user_plans($userid) { 2373 global $DB, $USER; 2374 static::require_enabled(); 2375 $select = 'userid = :userid'; 2376 $params = array('userid' => $userid); 2377 $context = context_user::instance($userid); 2378 2379 // Check that we can read something here. 2380 if (!plan::can_read_user($userid) && !plan::can_read_user_draft($userid)) { 2381 throw new required_capability_exception($context, 'moodle/competency:planview', 'nopermissions', ''); 2382 } 2383 2384 // The user cannot view the drafts. 2385 if (!plan::can_read_user_draft($userid)) { 2386 list($insql, $inparams) = $DB->get_in_or_equal(plan::get_draft_statuses(), SQL_PARAMS_NAMED, 'param', false); 2387 $select .= " AND status $insql"; 2388 $params += $inparams; 2389 } 2390 // The user cannot view the non-drafts. 2391 if (!plan::can_read_user($userid)) { 2392 list($insql, $inparams) = $DB->get_in_or_equal(array(plan::STATUS_ACTIVE, plan::STATUS_COMPLETE), 2393 SQL_PARAMS_NAMED, 'param', false); 2394 $select .= " AND status $insql"; 2395 $params += $inparams; 2396 } 2397 2398 return plan::get_records_select($select, $params, 'name ASC'); 2399 } 2400 2401 /** 2402 * List the plans to review. 2403 * 2404 * The method returns values in this format: 2405 * 2406 * array( 2407 * 'plans' => array( 2408 * (stdClass)( 2409 * 'plan' => (plan), 2410 * 'template' => (template), 2411 * 'owner' => (stdClass) 2412 * ) 2413 * ), 2414 * 'count' => (int) 2415 * ) 2416 * 2417 * @param int $skip The number of records to skip. 2418 * @param int $limit The number of results to return. 2419 * @param int $userid The user we're getting the plans to review for. 2420 * @return array Containing the keys 'count', and 'plans'. The 'plans' key contains an object 2421 * which contains 'plan', 'template' and 'owner'. 2422 */ 2423 public static function list_plans_to_review($skip = 0, $limit = 100, $userid = null) { 2424 global $DB, $USER; 2425 static::require_enabled(); 2426 2427 if ($userid === null) { 2428 $userid = $USER->id; 2429 } 2430 2431 $planfields = plan::get_sql_fields('p', 'plan_'); 2432 $tplfields = template::get_sql_fields('t', 'tpl_'); 2433 $usercols = array('id') + get_user_fieldnames(); 2434 $userfields = array(); 2435 foreach ($usercols as $field) { 2436 $userfields[] = "u." . $field . " AS usr_" . $field; 2437 } 2438 $userfields = implode(',', $userfields); 2439 2440 $select = "SELECT $planfields, $tplfields, $userfields"; 2441 $countselect = "SELECT COUNT('x')"; 2442 2443 $sql = " FROM {" . plan::TABLE . "} p 2444 JOIN {user} u 2445 ON u.id = p.userid 2446 LEFT JOIN {" . template::TABLE . "} t 2447 ON t.id = p.templateid 2448 WHERE (p.status = :waitingforreview 2449 OR (p.status = :inreview AND p.reviewerid = :reviewerid)) 2450 AND p.userid != :userid"; 2451 2452 $params = array( 2453 'waitingforreview' => plan::STATUS_WAITING_FOR_REVIEW, 2454 'inreview' => plan::STATUS_IN_REVIEW, 2455 'reviewerid' => $userid, 2456 'userid' => $userid 2457 ); 2458 2459 // Primary check to avoid the hard work of getting the users in which the user has permission. 2460 $count = $DB->count_records_sql($countselect . $sql, $params); 2461 if ($count < 1) { 2462 return array('count' => 0, 'plans' => array()); 2463 } 2464 2465 // TODO MDL-52243 Use core function. 2466 list($insql, $inparams) = self::filter_users_with_capability_on_user_context_sql('moodle/competency:planreview', 2467 $userid, SQL_PARAMS_NAMED); 2468 $sql .= " AND p.userid $insql"; 2469 $params += $inparams; 2470 2471 // Order by ID just to have some ordering in place. 2472 $ordersql = " ORDER BY p.id ASC"; 2473 2474 $plans = array(); 2475 $records = $DB->get_recordset_sql($select . $sql . $ordersql, $params, $skip, $limit); 2476 foreach ($records as $record) { 2477 $plan = new plan(0, plan::extract_record($record, 'plan_')); 2478 $template = null; 2479 2480 if ($plan->is_based_on_template()) { 2481 $template = new template(0, template::extract_record($record, 'tpl_')); 2482 } 2483 2484 $plans[] = (object) array( 2485 'plan' => $plan, 2486 'template' => $template, 2487 'owner' => persistent::extract_record($record, 'usr_'), 2488 ); 2489 } 2490 $records->close(); 2491 2492 return array( 2493 'count' => $DB->count_records_sql($countselect . $sql, $params), 2494 'plans' => $plans 2495 ); 2496 } 2497 2498 /** 2499 * Creates a learning plan based on the provided data. 2500 * 2501 * @param stdClass $record 2502 * @return \core_competency\plan 2503 */ 2504 public static function create_plan(stdClass $record) { 2505 global $USER; 2506 static::require_enabled(); 2507 $plan = new plan(0, $record); 2508 2509 if ($plan->is_based_on_template()) { 2510 throw new coding_exception('To create a plan from a template use api::create_plan_from_template().'); 2511 } else if ($plan->get('status') == plan::STATUS_COMPLETE) { 2512 throw new coding_exception('A plan cannot be created as complete.'); 2513 } 2514 2515 if (!$plan->can_manage()) { 2516 $context = context_user::instance($plan->get('userid')); 2517 throw new required_capability_exception($context, 'moodle/competency:planmanage', 'nopermissions', ''); 2518 } 2519 2520 $plan->create(); 2521 2522 // Trigger created event. 2523 \core\event\competency_plan_created::create_from_plan($plan)->trigger(); 2524 return $plan; 2525 } 2526 2527 /** 2528 * Create a learning plan from a template. 2529 * 2530 * @param mixed $templateorid The template object or ID. 2531 * @param int $userid 2532 * @return false|\core_competency\plan Returns false when the plan already exists. 2533 */ 2534 public static function create_plan_from_template($templateorid, $userid) { 2535 static::require_enabled(); 2536 $template = $templateorid; 2537 if (!is_object($template)) { 2538 $template = new template($template); 2539 } 2540 2541 // The user must be able to view the template to use it as a base for a plan. 2542 if (!$template->can_read()) { 2543 throw new required_capability_exception($template->get_context(), 'moodle/competency:templateview', 2544 'nopermissions', ''); 2545 } 2546 // Can not create plan from a hidden template. 2547 if ($template->get('visible') == false) { 2548 throw new coding_exception('A plan can not be created from a hidden template'); 2549 } 2550 2551 // Convert the template to a plan. 2552 $record = $template->to_record(); 2553 $record->templateid = $record->id; 2554 $record->userid = $userid; 2555 $record->name = $record->shortname; 2556 $record->status = plan::STATUS_ACTIVE; 2557 2558 unset($record->id); 2559 unset($record->timecreated); 2560 unset($record->timemodified); 2561 unset($record->usermodified); 2562 2563 // Remove extra keys. 2564 $properties = plan::properties_definition(); 2565 foreach ($record as $key => $value) { 2566 if (!array_key_exists($key, $properties)) { 2567 unset($record->$key); 2568 } 2569 } 2570 2571 $plan = new plan(0, $record); 2572 if (!$plan->can_manage()) { 2573 throw new required_capability_exception($plan->get_context(), 'moodle/competency:planmanage', 2574 'nopermissions', ''); 2575 } 2576 2577 // We first apply the permission checks as we wouldn't want to leak information by returning early that 2578 // the plan already exists. 2579 if (plan::record_exists_select('templateid = :templateid AND userid = :userid', array( 2580 'templateid' => $template->get('id'), 'userid' => $userid))) { 2581 return false; 2582 } 2583 2584 $plan->create(); 2585 2586 // Trigger created event. 2587 \core\event\competency_plan_created::create_from_plan($plan)->trigger(); 2588 return $plan; 2589 } 2590 2591 /** 2592 * Create learning plans from a template and cohort. 2593 * 2594 * @param mixed $templateorid The template object or ID. 2595 * @param int $cohortid The cohort ID. 2596 * @param bool $recreateunlinked When true the plans that were unlinked from this template will be re-created. 2597 * @return int The number of plans created. 2598 */ 2599 public static function create_plans_from_template_cohort($templateorid, $cohortid, $recreateunlinked = false) { 2600 global $DB, $CFG; 2601 static::require_enabled(); 2602 require_once($CFG->dirroot . '/cohort/lib.php'); 2603 2604 $template = $templateorid; 2605 if (!is_object($template)) { 2606 $template = new template($template); 2607 } 2608 2609 // The user must be able to view the template to use it as a base for a plan. 2610 if (!$template->can_read()) { 2611 throw new required_capability_exception($template->get_context(), 'moodle/competency:templateview', 2612 'nopermissions', ''); 2613 } 2614 2615 // Can not create plan from a hidden template. 2616 if ($template->get('visible') == false) { 2617 throw new coding_exception('A plan can not be created from a hidden template'); 2618 } 2619 2620 // Replicate logic in cohort_can_view_cohort() because we can't use it directly as we don't have a course context. 2621 $cohort = $DB->get_record('cohort', array('id' => $cohortid), '*', MUST_EXIST); 2622 $cohortcontext = context::instance_by_id($cohort->contextid); 2623 if (!$cohort->visible && !has_capability('moodle/cohort:view', $cohortcontext)) { 2624 throw new required_capability_exception($cohortcontext, 'moodle/cohort:view', 'nopermissions', ''); 2625 } 2626 2627 // Convert the template to a plan. 2628 $recordbase = $template->to_record(); 2629 $recordbase->templateid = $recordbase->id; 2630 $recordbase->name = $recordbase->shortname; 2631 $recordbase->status = plan::STATUS_ACTIVE; 2632 2633 unset($recordbase->id); 2634 unset($recordbase->timecreated); 2635 unset($recordbase->timemodified); 2636 unset($recordbase->usermodified); 2637 2638 // Remove extra keys. 2639 $properties = plan::properties_definition(); 2640 foreach ($recordbase as $key => $value) { 2641 if (!array_key_exists($key, $properties)) { 2642 unset($recordbase->$key); 2643 } 2644 } 2645 2646 // Create the plans. 2647 $created = 0; 2648 $userids = template_cohort::get_missing_plans($template->get('id'), $cohortid, $recreateunlinked); 2649 foreach ($userids as $userid) { 2650 $record = (object) (array) $recordbase; 2651 $record->userid = $userid; 2652 2653 $plan = new plan(0, $record); 2654 if (!$plan->can_manage()) { 2655 // Silently skip members where permissions are lacking. 2656 continue; 2657 } 2658 2659 $plan->create(); 2660 // Trigger created event. 2661 \core\event\competency_plan_created::create_from_plan($plan)->trigger(); 2662 $created++; 2663 } 2664 2665 return $created; 2666 } 2667 2668 /** 2669 * Unlink a plan from its template. 2670 * 2671 * @param \core_competency\plan|int $planorid The plan or its ID. 2672 * @return bool 2673 */ 2674 public static function unlink_plan_from_template($planorid) { 2675 global $DB; 2676 static::require_enabled(); 2677 2678 $plan = $planorid; 2679 if (!is_object($planorid)) { 2680 $plan = new plan($planorid); 2681 } 2682 2683 // The user must be allowed to manage the plans of the user, nothing about the template. 2684 if (!$plan->can_manage()) { 2685 throw new required_capability_exception($plan->get_context(), 'moodle/competency:planmanage', 'nopermissions', ''); 2686 } 2687 2688 // Only plan with status DRAFT or ACTIVE can be unliked.. 2689 if ($plan->get('status') == plan::STATUS_COMPLETE) { 2690 throw new coding_exception('Only draft or active plan can be unliked from a template'); 2691 } 2692 2693 // Early exit, it's already done... 2694 if (!$plan->is_based_on_template()) { 2695 return true; 2696 } 2697 2698 // Fetch the template. 2699 $template = new template($plan->get('templateid')); 2700 2701 // Now, proceed by copying all competencies to the plan, then update the plan. 2702 $transaction = $DB->start_delegated_transaction(); 2703 $competencies = template_competency::list_competencies($template->get('id'), false); 2704 $i = 0; 2705 foreach ($competencies as $competency) { 2706 $record = (object) array( 2707 'planid' => $plan->get('id'), 2708 'competencyid' => $competency->get('id'), 2709 'sortorder' => $i++ 2710 ); 2711 $pc = new plan_competency(null, $record); 2712 $pc->create(); 2713 } 2714 $plan->set('origtemplateid', $template->get('id')); 2715 $plan->set('templateid', null); 2716 $success = $plan->update(); 2717 $transaction->allow_commit(); 2718 2719 // Trigger unlinked event. 2720 \core\event\competency_plan_unlinked::create_from_plan($plan)->trigger(); 2721 2722 return $success; 2723 } 2724 2725 /** 2726 * Updates a plan. 2727 * 2728 * @param stdClass $record 2729 * @return \core_competency\plan 2730 */ 2731 public static function update_plan(stdClass $record) { 2732 static::require_enabled(); 2733 2734 $plan = new plan($record->id); 2735 2736 // Validate that the plan as it is can be managed. 2737 if (!$plan->can_manage()) { 2738 throw new required_capability_exception($plan->get_context(), 'moodle/competency:planmanage', 'nopermissions', ''); 2739 2740 } else if ($plan->get('status') == plan::STATUS_COMPLETE) { 2741 // A completed plan cannot be edited. 2742 throw new coding_exception('Completed plan cannot be edited.'); 2743 2744 } else if ($plan->is_based_on_template()) { 2745 // Prevent a plan based on a template to be edited. 2746 throw new coding_exception('Cannot update a plan that is based on a template.'); 2747 2748 } else if (isset($record->templateid) && $plan->get('templateid') != $record->templateid) { 2749 // Prevent a plan to be based on a template. 2750 throw new coding_exception('Cannot base a plan on a template.'); 2751 2752 } else if (isset($record->userid) && $plan->get('userid') != $record->userid) { 2753 // Prevent change of ownership as the capabilities are checked against that. 2754 throw new coding_exception('A plan cannot be transfered to another user'); 2755 2756 } else if (isset($record->status) && $plan->get('status') != $record->status) { 2757 // Prevent change of status. 2758 throw new coding_exception('To change the status of a plan use the appropriate methods.'); 2759 2760 } 2761 2762 $plan->from_record($record); 2763 $plan->update(); 2764 2765 // Trigger updated event. 2766 \core\event\competency_plan_updated::create_from_plan($plan)->trigger(); 2767 2768 return $plan; 2769 } 2770 2771 /** 2772 * Returns a plan data. 2773 * 2774 * @param int $id 2775 * @return \core_competency\plan 2776 */ 2777 public static function read_plan($id) { 2778 static::require_enabled(); 2779 $plan = new plan($id); 2780 2781 if (!$plan->can_read()) { 2782 $context = context_user::instance($plan->get('userid')); 2783 throw new required_capability_exception($context, 'moodle/competency:planview', 'nopermissions', ''); 2784 } 2785 2786 return $plan; 2787 } 2788 2789 /** 2790 * Plan event viewed. 2791 * 2792 * @param mixed $planorid The id or the plan. 2793 * @return boolean 2794 */ 2795 public static function plan_viewed($planorid) { 2796 static::require_enabled(); 2797 $plan = $planorid; 2798 if (!is_object($plan)) { 2799 $plan = new plan($plan); 2800 } 2801 2802 // First we do a permissions check. 2803 if (!$plan->can_read()) { 2804 $context = context_user::instance($plan->get('userid')); 2805 throw new required_capability_exception($context, 'moodle/competency:planview', 'nopermissions', ''); 2806 } 2807 2808 // Trigger a template viewed event. 2809 \core\event\competency_plan_viewed::create_from_plan($plan)->trigger(); 2810 2811 return true; 2812 } 2813 2814 /** 2815 * Deletes a plan. 2816 * 2817 * Plans based on a template can be removed just like any other one. 2818 * 2819 * @param int $id 2820 * @return bool Success? 2821 */ 2822 public static function delete_plan($id) { 2823 global $DB; 2824 static::require_enabled(); 2825 2826 $plan = new plan($id); 2827 2828 if (!$plan->can_manage()) { 2829 $context = context_user::instance($plan->get('userid')); 2830 throw new required_capability_exception($context, 'moodle/competency:planmanage', 'nopermissions', ''); 2831 } 2832 2833 // Wrap the suppression in a DB transaction. 2834 $transaction = $DB->start_delegated_transaction(); 2835 2836 // Delete plan competencies. 2837 $plancomps = plan_competency::get_records(array('planid' => $plan->get('id'))); 2838 foreach ($plancomps as $plancomp) { 2839 $plancomp->delete(); 2840 } 2841 2842 // Delete archive user competencies if the status of the plan is complete. 2843 if ($plan->get('status') == plan::STATUS_COMPLETE) { 2844 self::remove_archived_user_competencies_in_plan($plan); 2845 } 2846 $event = \core\event\competency_plan_deleted::create_from_plan($plan); 2847 $success = $plan->delete(); 2848 2849 $transaction->allow_commit(); 2850 2851 // Trigger deleted event. 2852 $event->trigger(); 2853 2854 return $success; 2855 } 2856 2857 /** 2858 * Cancel the review of a plan. 2859 * 2860 * @param int|plan $planorid The plan, or its ID. 2861 * @return bool 2862 */ 2863 public static function plan_cancel_review_request($planorid) { 2864 static::require_enabled(); 2865 $plan = $planorid; 2866 if (!is_object($plan)) { 2867 $plan = new plan($plan); 2868 } 2869 2870 // We need to be able to view the plan at least. 2871 if (!$plan->can_read()) { 2872 throw new required_capability_exception($plan->get_context(), 'moodle/competency:planview', 'nopermissions', ''); 2873 } 2874 2875 if ($plan->is_based_on_template()) { 2876 throw new coding_exception('Template plans cannot be reviewed.'); // This should never happen. 2877 } else if ($plan->get('status') != plan::STATUS_WAITING_FOR_REVIEW) { 2878 throw new coding_exception('The plan review cannot be cancelled at this stage.'); 2879 } else if (!$plan->can_request_review()) { 2880 throw new required_capability_exception($plan->get_context(), 'moodle/competency:planmanage', 'nopermissions', ''); 2881 } 2882 2883 $plan->set('status', plan::STATUS_DRAFT); 2884 $result = $plan->update(); 2885 2886 // Trigger review request cancelled event. 2887 \core\event\competency_plan_review_request_cancelled::create_from_plan($plan)->trigger(); 2888 2889 return $result; 2890 } 2891 2892 /** 2893 * Request the review of a plan. 2894 * 2895 * @param int|plan $planorid The plan, or its ID. 2896 * @return bool 2897 */ 2898 public static function plan_request_review($planorid) { 2899 static::require_enabled(); 2900 $plan = $planorid; 2901 if (!is_object($plan)) { 2902 $plan = new plan($plan); 2903 } 2904 2905 // We need to be able to view the plan at least. 2906 if (!$plan->can_read()) { 2907 throw new required_capability_exception($plan->get_context(), 'moodle/competency:planview', 'nopermissions', ''); 2908 } 2909 2910 if ($plan->is_based_on_template()) { 2911 throw new coding_exception('Template plans cannot be reviewed.'); // This should never happen. 2912 } else if ($plan->get('status') != plan::STATUS_DRAFT) { 2913 throw new coding_exception('The plan cannot be sent for review at this stage.'); 2914 } else if (!$plan->can_request_review()) { 2915 throw new required_capability_exception($plan->get_context(), 'moodle/competency:planmanage', 'nopermissions', ''); 2916 } 2917 2918 $plan->set('status', plan::STATUS_WAITING_FOR_REVIEW); 2919 $result = $plan->update(); 2920 2921 // Trigger review requested event. 2922 \core\event\competency_plan_review_requested::create_from_plan($plan)->trigger(); 2923 2924 return $result; 2925 } 2926 2927 /** 2928 * Start the review of a plan. 2929 * 2930 * @param int|plan $planorid The plan, or its ID. 2931 * @return bool 2932 */ 2933 public static function plan_start_review($planorid) { 2934 global $USER; 2935 static::require_enabled(); 2936 $plan = $planorid; 2937 if (!is_object($plan)) { 2938 $plan = new plan($plan); 2939 } 2940 2941 // We need to be able to view the plan at least. 2942 if (!$plan->can_read()) { 2943 throw new required_capability_exception($plan->get_context(), 'moodle/competency:planview', 'nopermissions', ''); 2944 } 2945 2946 if ($plan->is_based_on_template()) { 2947 throw new coding_exception('Template plans cannot be reviewed.'); // This should never happen. 2948 } else if ($plan->get('status') != plan::STATUS_WAITING_FOR_REVIEW) { 2949 throw new coding_exception('The plan review cannot be started at this stage.'); 2950 } else if (!$plan->can_review()) { 2951 throw new required_capability_exception($plan->get_context(), 'moodle/competency:planmanage', 'nopermissions', ''); 2952 } 2953 2954 $plan->set('status', plan::STATUS_IN_REVIEW); 2955 $plan->set('reviewerid', $USER->id); 2956 $result = $plan->update(); 2957 2958 // Trigger review started event. 2959 \core\event\competency_plan_review_started::create_from_plan($plan)->trigger(); 2960 2961 return $result; 2962 } 2963 2964 /** 2965 * Stop reviewing a plan. 2966 * 2967 * @param int|plan $planorid The plan, or its ID. 2968 * @return bool 2969 */ 2970 public static function plan_stop_review($planorid) { 2971 static::require_enabled(); 2972 $plan = $planorid; 2973 if (!is_object($plan)) { 2974 $plan = new plan($plan); 2975 } 2976 2977 // We need to be able to view the plan at least. 2978 if (!$plan->can_read()) { 2979 throw new required_capability_exception($plan->get_context(), 'moodle/competency:planview', 'nopermissions', ''); 2980 } 2981 2982 if ($plan->is_based_on_template()) { 2983 throw new coding_exception('Template plans cannot be reviewed.'); // This should never happen. 2984 } else if ($plan->get('status') != plan::STATUS_IN_REVIEW) { 2985 throw new coding_exception('The plan review cannot be stopped at this stage.'); 2986 } else if (!$plan->can_review()) { 2987 throw new required_capability_exception($plan->get_context(), 'moodle/competency:planmanage', 'nopermissions', ''); 2988 } 2989 2990 $plan->set('status', plan::STATUS_DRAFT); 2991 $plan->set('reviewerid', null); 2992 $result = $plan->update(); 2993 2994 // Trigger review stopped event. 2995 \core\event\competency_plan_review_stopped::create_from_plan($plan)->trigger(); 2996 2997 return $result; 2998 } 2999 3000 /** 3001 * Approve a plan. 3002 * 3003 * This means making the plan active. 3004 * 3005 * @param int|plan $planorid The plan, or its ID. 3006 * @return bool 3007 */ 3008 public static function approve_plan($planorid) { 3009 static::require_enabled(); 3010 $plan = $planorid; 3011 if (!is_object($plan)) { 3012 $plan = new plan($plan); 3013 } 3014 3015 // We need to be able to view the plan at least. 3016 if (!$plan->can_read()) { 3017 throw new required_capability_exception($plan->get_context(), 'moodle/competency:planview', 'nopermissions', ''); 3018 } 3019 3020 // We can approve a plan that is either a draft, in review, or waiting for review. 3021 if ($plan->is_based_on_template()) { 3022 throw new coding_exception('Template plans are already approved.'); // This should never happen. 3023 } else if (!$plan->is_draft()) { 3024 throw new coding_exception('The plan cannot be approved at this stage.'); 3025 } else if (!$plan->can_review()) { 3026 throw new required_capability_exception($plan->get_context(), 'moodle/competency:planmanage', 'nopermissions', ''); 3027 } 3028 3029 $plan->set('status', plan::STATUS_ACTIVE); 3030 $plan->set('reviewerid', null); 3031 $result = $plan->update(); 3032 3033 // Trigger approved event. 3034 \core\event\competency_plan_approved::create_from_plan($plan)->trigger(); 3035 3036 return $result; 3037 } 3038 3039 /** 3040 * Unapprove a plan. 3041 * 3042 * This means making the plan draft. 3043 * 3044 * @param int|plan $planorid The plan, or its ID. 3045 * @return bool 3046 */ 3047 public static function unapprove_plan($planorid) { 3048 static::require_enabled(); 3049 $plan = $planorid; 3050 if (!is_object($plan)) { 3051 $plan = new plan($plan); 3052 } 3053 3054 // We need to be able to view the plan at least. 3055 if (!$plan->can_read()) { 3056 throw new required_capability_exception($plan->get_context(), 'moodle/competency:planview', 'nopermissions', ''); 3057 } 3058 3059 if ($plan->is_based_on_template()) { 3060 throw new coding_exception('Template plans are always approved.'); // This should never happen. 3061 } else if ($plan->get('status') != plan::STATUS_ACTIVE) { 3062 throw new coding_exception('The plan cannot be sent back to draft at this stage.'); 3063 } else if (!$plan->can_review()) { 3064 throw new required_capability_exception($plan->get_context(), 'moodle/competency:planmanage', 'nopermissions', ''); 3065 } 3066 3067 $plan->set('status', plan::STATUS_DRAFT); 3068 $result = $plan->update(); 3069 3070 // Trigger unapproved event. 3071 \core\event\competency_plan_unapproved::create_from_plan($plan)->trigger(); 3072 3073 return $result; 3074 } 3075 3076 /** 3077 * Complete a plan. 3078 * 3079 * @param int|plan $planorid The plan, or its ID. 3080 * @return bool 3081 */ 3082 public static function complete_plan($planorid) { 3083 global $DB; 3084 static::require_enabled(); 3085 3086 $plan = $planorid; 3087 if (!is_object($planorid)) { 3088 $plan = new plan($planorid); 3089 } 3090 3091 // Validate that the plan can be managed. 3092 if (!$plan->can_manage()) { 3093 throw new required_capability_exception($plan->get_context(), 'moodle/competency:planmanage', 'nopermissions', ''); 3094 } 3095 3096 // Check if the plan was already completed. 3097 if ($plan->get('status') == plan::STATUS_COMPLETE) { 3098 throw new coding_exception('The plan is already completed.'); 3099 } 3100 3101 $originalstatus = $plan->get('status'); 3102 $plan->set('status', plan::STATUS_COMPLETE); 3103 3104 // The user should also be able to manage the plan when it's completed. 3105 if (!$plan->can_manage()) { 3106 throw new required_capability_exception($plan->get_context(), 'moodle/competency:planmanage', 'nopermissions', ''); 3107 } 3108 3109 // Put back original status because archive needs it to extract competencies from the right table. 3110 $plan->set('status', $originalstatus); 3111 3112 // Do the things. 3113 $transaction = $DB->start_delegated_transaction(); 3114 self::archive_user_competencies_in_plan($plan); 3115 $plan->set('status', plan::STATUS_COMPLETE); 3116 $success = $plan->update(); 3117 3118 if (!$success) { 3119 $transaction->rollback(new moodle_exception('The plan could not be updated.')); 3120 return $success; 3121 } 3122 3123 $transaction->allow_commit(); 3124 3125 // Trigger updated event. 3126 \core\event\competency_plan_completed::create_from_plan($plan)->trigger(); 3127 3128 return $success; 3129 } 3130 3131 /** 3132 * Reopen a plan. 3133 * 3134 * @param int|plan $planorid The plan, or its ID. 3135 * @return bool 3136 */ 3137 public static function reopen_plan($planorid) { 3138 global $DB; 3139 static::require_enabled(); 3140 3141 $plan = $planorid; 3142 if (!is_object($planorid)) { 3143 $plan = new plan($planorid); 3144 } 3145 3146 // Validate that the plan as it is can be managed. 3147 if (!$plan->can_manage()) { 3148 $context = context_user::instance($plan->get('userid')); 3149 throw new required_capability_exception($context, 'moodle/competency:planmanage', 'nopermissions', ''); 3150 } 3151 3152 $beforestatus = $plan->get('status'); 3153 $plan->set('status', plan::STATUS_ACTIVE); 3154 3155 // Validate if status can be changed. 3156 if (!$plan->can_manage()) { 3157 $context = context_user::instance($plan->get('userid')); 3158 throw new required_capability_exception($context, 'moodle/competency:planmanage', 'nopermissions', ''); 3159 } 3160 3161 // Wrap the updates in a DB transaction. 3162 $transaction = $DB->start_delegated_transaction(); 3163 3164 // Delete archived user competencies if the status of the plan is changed from complete to another status. 3165 $mustremovearchivedcompetencies = ($beforestatus == plan::STATUS_COMPLETE && $plan->get('status') != plan::STATUS_COMPLETE); 3166 if ($mustremovearchivedcompetencies) { 3167 self::remove_archived_user_competencies_in_plan($plan); 3168 } 3169 3170 // If duedate less than or equal to duedate_threshold unset it. 3171 if ($plan->get('duedate') <= time() + plan::DUEDATE_THRESHOLD) { 3172 $plan->set('duedate', 0); 3173 } 3174 3175 $success = $plan->update(); 3176 3177 if (!$success) { 3178 $transaction->rollback(new moodle_exception('The plan could not be updated.')); 3179 return $success; 3180 } 3181 3182 $transaction->allow_commit(); 3183 3184 // Trigger reopened event. 3185 \core\event\competency_plan_reopened::create_from_plan($plan)->trigger(); 3186 3187 return $success; 3188 } 3189 3190 /** 3191 * Get a single competency from the user plan. 3192 * 3193 * @param int $planorid The plan, or its ID. 3194 * @param int $competencyid The competency id. 3195 * @return (object) array( 3196 * 'competency' => \core_competency\competency, 3197 * 'usercompetency' => \core_competency\user_competency 3198 * 'usercompetencyplan' => \core_competency\user_competency_plan 3199 * ) 3200 * The values of of keys usercompetency and usercompetencyplan cannot be defined at the same time. 3201 */ 3202 public static function get_plan_competency($planorid, $competencyid) { 3203 static::require_enabled(); 3204 $plan = $planorid; 3205 if (!is_object($planorid)) { 3206 $plan = new plan($planorid); 3207 } 3208 3209 if (!user_competency::can_read_user($plan->get('userid'))) { 3210 throw new required_capability_exception($plan->get_context(), 'moodle/competency:usercompetencyview', 3211 'nopermissions', ''); 3212 } 3213 3214 $competency = $plan->get_competency($competencyid); 3215 3216 // Get user competencies from user_competency_plan if the plan status is set to complete. 3217 $iscompletedplan = $plan->get('status') == plan::STATUS_COMPLETE; 3218 if ($iscompletedplan) { 3219 $usercompetencies = user_competency_plan::get_multiple($plan->get('userid'), $plan->get('id'), array($competencyid)); 3220 $ucresultkey = 'usercompetencyplan'; 3221 } else { 3222 $usercompetencies = user_competency::get_multiple($plan->get('userid'), array($competencyid)); 3223 $ucresultkey = 'usercompetency'; 3224 } 3225 3226 $found = count($usercompetencies); 3227 3228 if ($found) { 3229 $uc = array_pop($usercompetencies); 3230 } else { 3231 if ($iscompletedplan) { 3232 throw new coding_exception('A user competency plan is missing'); 3233 } else { 3234 $uc = user_competency::create_relation($plan->get('userid'), $competency->get('id')); 3235 $uc->create(); 3236 } 3237 } 3238 3239 $plancompetency = (object) array( 3240 'competency' => $competency, 3241 'usercompetency' => null, 3242 'usercompetencyplan' => null 3243 ); 3244 $plancompetency->$ucresultkey = $uc; 3245 3246 return $plancompetency; 3247 } 3248 3249 /** 3250 * List the plans with a competency. 3251 * 3252 * @param int $userid The user id we want the plans for. 3253 * @param int $competencyorid The competency, or its ID. 3254 * @return array[plan] Array of learning plans. 3255 */ 3256 public static function list_plans_with_competency($userid, $competencyorid) { 3257 global $USER; 3258 3259 static::require_enabled(); 3260 $competencyid = $competencyorid; 3261 $competency = null; 3262 if (is_object($competencyid)) { 3263 $competency = $competencyid; 3264 $competencyid = $competency->get('id'); 3265 } 3266 3267 $plans = plan::get_by_user_and_competency($userid, $competencyid); 3268 foreach ($plans as $index => $plan) { 3269 // Filter plans we cannot read. 3270 if (!$plan->can_read()) { 3271 unset($plans[$index]); 3272 } 3273 } 3274 return $plans; 3275 } 3276 3277 /** 3278 * List the competencies in a user plan. 3279 * 3280 * @param int $planorid The plan, or its ID. 3281 * @return array((object) array( 3282 * 'competency' => \core_competency\competency, 3283 * 'usercompetency' => \core_competency\user_competency 3284 * 'usercompetencyplan' => \core_competency\user_competency_plan 3285 * )) 3286 * The values of of keys usercompetency and usercompetencyplan cannot be defined at the same time. 3287 */ 3288 public static function list_plan_competencies($planorid) { 3289 static::require_enabled(); 3290 $plan = $planorid; 3291 if (!is_object($planorid)) { 3292 $plan = new plan($planorid); 3293 } 3294 3295 if (!$plan->can_read()) { 3296 $context = context_user::instance($plan->get('userid')); 3297 throw new required_capability_exception($context, 'moodle/competency:planview', 'nopermissions', ''); 3298 } 3299 3300 $result = array(); 3301 $competencies = $plan->get_competencies(); 3302 3303 // Get user competencies from user_competency_plan if the plan status is set to complete. 3304 $iscompletedplan = $plan->get('status') == plan::STATUS_COMPLETE; 3305 if ($iscompletedplan) { 3306 $usercompetencies = user_competency_plan::get_multiple($plan->get('userid'), $plan->get('id'), $competencies); 3307 $ucresultkey = 'usercompetencyplan'; 3308 } else { 3309 $usercompetencies = user_competency::get_multiple($plan->get('userid'), $competencies); 3310 $ucresultkey = 'usercompetency'; 3311 } 3312 3313 // Build the return values. 3314 foreach ($competencies as $key => $competency) { 3315 $found = false; 3316 3317 foreach ($usercompetencies as $uckey => $uc) { 3318 if ($uc->get('competencyid') == $competency->get('id')) { 3319 $found = true; 3320 unset($usercompetencies[$uckey]); 3321 break; 3322 } 3323 } 3324 3325 if (!$found) { 3326 if ($iscompletedplan) { 3327 throw new coding_exception('A user competency plan is missing'); 3328 } else { 3329 $uc = user_competency::create_relation($plan->get('userid'), $competency->get('id')); 3330 } 3331 } 3332 3333 $plancompetency = (object) array( 3334 'competency' => $competency, 3335 'usercompetency' => null, 3336 'usercompetencyplan' => null 3337 ); 3338 $plancompetency->$ucresultkey = $uc; 3339 $result[] = $plancompetency; 3340 } 3341 3342 return $result; 3343 } 3344 3345 /** 3346 * Add a competency to a plan. 3347 * 3348 * @param int $planid The id of the plan 3349 * @param int $competencyid The id of the competency 3350 * @return bool 3351 */ 3352 public static function add_competency_to_plan($planid, $competencyid) { 3353 static::require_enabled(); 3354 $plan = new plan($planid); 3355 3356 // First we do a permissions check. 3357 if (!$plan->can_manage()) { 3358 throw new required_capability_exception($plan->get_context(), 'moodle/competency:planmanage', 'nopermissions', ''); 3359 3360 } else if ($plan->is_based_on_template()) { 3361 throw new coding_exception('A competency can not be added to a learning plan based on a template'); 3362 } 3363 3364 if (!$plan->can_be_edited()) { 3365 throw new coding_exception('A competency can not be added to a learning plan completed'); 3366 } 3367 3368 $competency = new competency($competencyid); 3369 3370 // Can not add a competency that belong to a hidden framework. 3371 if ($competency->get_framework()->get('visible') == false) { 3372 throw new coding_exception('A competency belonging to hidden framework can not be added'); 3373 } 3374 3375 $exists = plan_competency::get_record(array('planid' => $planid, 'competencyid' => $competencyid)); 3376 if (!$exists) { 3377 $record = new stdClass(); 3378 $record->planid = $planid; 3379 $record->competencyid = $competencyid; 3380 $plancompetency = new plan_competency(0, $record); 3381 $plancompetency->create(); 3382 } 3383 3384 return true; 3385 } 3386 3387 /** 3388 * Remove a competency from a plan. 3389 * 3390 * @param int $planid The plan id 3391 * @param int $competencyid The id of the competency 3392 * @return bool 3393 */ 3394 public static function remove_competency_from_plan($planid, $competencyid) { 3395 static::require_enabled(); 3396 $plan = new plan($planid); 3397 3398 // First we do a permissions check. 3399 if (!$plan->can_manage()) { 3400 $context = context_user::instance($plan->get('userid')); 3401 throw new required_capability_exception($context, 'moodle/competency:planmanage', 'nopermissions', ''); 3402 3403 } else if ($plan->is_based_on_template()) { 3404 throw new coding_exception('A competency can not be removed from a learning plan based on a template'); 3405 } 3406 3407 if (!$plan->can_be_edited()) { 3408 throw new coding_exception('A competency can not be removed from a learning plan completed'); 3409 } 3410 3411 $link = plan_competency::get_record(array('planid' => $planid, 'competencyid' => $competencyid)); 3412 if ($link) { 3413 return $link->delete(); 3414 } 3415 return false; 3416 } 3417 3418 /** 3419 * Move the plan competency up or down in the display list. 3420 * 3421 * Requires moodle/competency:planmanage capability at the system context. 3422 * 3423 * @param int $planid The plan id 3424 * @param int $competencyidfrom The id of the competency we are moving. 3425 * @param int $competencyidto The id of the competency we are moving to. 3426 * @return boolean 3427 */ 3428 public static function reorder_plan_competency($planid, $competencyidfrom, $competencyidto) { 3429 static::require_enabled(); 3430 $plan = new plan($planid); 3431 3432 // First we do a permissions check. 3433 if (!$plan->can_manage()) { 3434 $context = context_user::instance($plan->get('userid')); 3435 throw new required_capability_exception($context, 'moodle/competency:planmanage', 'nopermissions', ''); 3436 3437 } else if ($plan->is_based_on_template()) { 3438 throw new coding_exception('A competency can not be reordered in a learning plan based on a template'); 3439 } 3440 3441 if (!$plan->can_be_edited()) { 3442 throw new coding_exception('A competency can not be reordered in a learning plan completed'); 3443 } 3444 3445 $down = true; 3446 $matches = plan_competency::get_records(array('planid' => $planid, 'competencyid' => $competencyidfrom)); 3447 if (count($matches) == 0) { 3448 throw new coding_exception('The link does not exist'); 3449 } 3450 3451 $competencyfrom = array_pop($matches); 3452 $matches = plan_competency::get_records(array('planid' => $planid, 'competencyid' => $competencyidto)); 3453 if (count($matches) == 0) { 3454 throw new coding_exception('The link does not exist'); 3455 } 3456 3457 $competencyto = array_pop($matches); 3458 3459 $all = plan_competency::get_records(array('planid' => $planid), 'sortorder', 'ASC', 0, 0); 3460 3461 if ($competencyfrom->get('sortorder') > $competencyto->get('sortorder')) { 3462 // We are moving up, so put it before the "to" item. 3463 $down = false; 3464 } 3465 3466 foreach ($all as $id => $plancompetency) { 3467 $sort = $plancompetency->get('sortorder'); 3468 if ($down && $sort > $competencyfrom->get('sortorder') && $sort <= $competencyto->get('sortorder')) { 3469 $plancompetency->set('sortorder', $plancompetency->get('sortorder') - 1); 3470 $plancompetency->update(); 3471 } else if (!$down && $sort >= $competencyto->get('sortorder') && $sort < $competencyfrom->get('sortorder')) { 3472 $plancompetency->set('sortorder', $plancompetency->get('sortorder') + 1); 3473 $plancompetency->update(); 3474 } 3475 } 3476 $competencyfrom->set('sortorder', $competencyto->get('sortorder')); 3477 return $competencyfrom->update(); 3478 } 3479 3480 /** 3481 * Cancel a user competency review request. 3482 * 3483 * @param int $userid The user ID. 3484 * @param int $competencyid The competency ID. 3485 * @return bool 3486 */ 3487 public static function user_competency_cancel_review_request($userid, $competencyid) { 3488 static::require_enabled(); 3489 $context = context_user::instance($userid); 3490 $uc = user_competency::get_record(array('userid' => $userid, 'competencyid' => $competencyid)); 3491 if (!$uc || !$uc->can_read()) { 3492 throw new required_capability_exception($context, 'moodle/competency:usercompetencyview', 'nopermissions', ''); 3493 } else if ($uc->get('status') != user_competency::STATUS_WAITING_FOR_REVIEW) { 3494 throw new coding_exception('The competency can not be cancel review request at this stage.'); 3495 } else if (!$uc->can_request_review()) { 3496 throw new required_capability_exception($context, 'moodle/competency:usercompetencyrequestreview', 'nopermissions', ''); 3497 } 3498 3499 $uc->set('status', user_competency::STATUS_IDLE); 3500 $result = $uc->update(); 3501 if ($result) { 3502 \core\event\competency_user_competency_review_request_cancelled::create_from_user_competency($uc)->trigger(); 3503 } 3504 return $result; 3505 } 3506 3507 /** 3508 * Request a user competency review. 3509 * 3510 * @param int $userid The user ID. 3511 * @param int $competencyid The competency ID. 3512 * @return bool 3513 */ 3514 public static function user_competency_request_review($userid, $competencyid) { 3515 static::require_enabled(); 3516 $uc = user_competency::get_record(array('userid' => $userid, 'competencyid' => $competencyid)); 3517 if (!$uc) { 3518 $uc = user_competency::create_relation($userid, $competencyid); 3519 $uc->create(); 3520 } 3521 3522 if (!$uc->can_read()) { 3523 throw new required_capability_exception($uc->get_context(), 'moodle/competency:usercompetencyview', 3524 'nopermissions', ''); 3525 } else if ($uc->get('status') != user_competency::STATUS_IDLE) { 3526 throw new coding_exception('The competency can not be sent for review at this stage.'); 3527 } else if (!$uc->can_request_review()) { 3528 throw new required_capability_exception($uc->get_context(), 'moodle/competency:usercompetencyrequestreview', 3529 'nopermissions', ''); 3530 } 3531 3532 $uc->set('status', user_competency::STATUS_WAITING_FOR_REVIEW); 3533 $result = $uc->update(); 3534 if ($result) { 3535 \core\event\competency_user_competency_review_requested::create_from_user_competency($uc)->trigger(); 3536 } 3537 return $result; 3538 } 3539 3540 /** 3541 * Start a user competency review. 3542 * 3543 * @param int $userid The user ID. 3544 * @param int $competencyid The competency ID. 3545 * @return bool 3546 */ 3547 public static function user_competency_start_review($userid, $competencyid) { 3548 global $USER; 3549 static::require_enabled(); 3550 3551 $context = context_user::instance($userid); 3552 $uc = user_competency::get_record(array('userid' => $userid, 'competencyid' => $competencyid)); 3553 if (!$uc || !$uc->can_read()) { 3554 throw new required_capability_exception($context, 'moodle/competency:usercompetencyview', 'nopermissions', ''); 3555 } else if ($uc->get('status') != user_competency::STATUS_WAITING_FOR_REVIEW) { 3556 throw new coding_exception('The competency review can not be started at this stage.'); 3557 } else if (!$uc->can_review()) { 3558 throw new required_capability_exception($context, 'moodle/competency:usercompetencyreview', 'nopermissions', ''); 3559 } 3560 3561 $uc->set('status', user_competency::STATUS_IN_REVIEW); 3562 $uc->set('reviewerid', $USER->id); 3563 $result = $uc->update(); 3564 if ($result) { 3565 \core\event\competency_user_competency_review_started::create_from_user_competency($uc)->trigger(); 3566 } 3567 return $result; 3568 } 3569 3570 /** 3571 * Stop a user competency review. 3572 * 3573 * @param int $userid The user ID. 3574 * @param int $competencyid The competency ID. 3575 * @return bool 3576 */ 3577 public static function user_competency_stop_review($userid, $competencyid) { 3578 static::require_enabled(); 3579 $context = context_user::instance($userid); 3580 $uc = user_competency::get_record(array('userid' => $userid, 'competencyid' => $competencyid)); 3581 if (!$uc || !$uc->can_read()) { 3582 throw new required_capability_exception($context, 'moodle/competency:usercompetencyview', 'nopermissions', ''); 3583 } else if ($uc->get('status') != user_competency::STATUS_IN_REVIEW) { 3584 throw new coding_exception('The competency review can not be stopped at this stage.'); 3585 } else if (!$uc->can_review()) { 3586 throw new required_capability_exception($context, 'moodle/competency:usercompetencyreview', 'nopermissions', ''); 3587 } 3588 3589 $uc->set('status', user_competency::STATUS_IDLE); 3590 $result = $uc->update(); 3591 if ($result) { 3592 \core\event\competency_user_competency_review_stopped::create_from_user_competency($uc)->trigger(); 3593 } 3594 return $result; 3595 } 3596 3597 /** 3598 * Log user competency viewed event. 3599 * 3600 * @param user_competency|int $usercompetencyorid The user competency object or user competency id 3601 * @return bool 3602 */ 3603 public static function user_competency_viewed($usercompetencyorid) { 3604 static::require_enabled(); 3605 $uc = $usercompetencyorid; 3606 if (!is_object($uc)) { 3607 $uc = new user_competency($uc); 3608 } 3609 3610 if (!$uc || !$uc->can_read()) { 3611 throw new required_capability_exception($uc->get_context(), 'moodle/competency:usercompetencyview', 3612 'nopermissions', ''); 3613 } 3614 3615 \core\event\competency_user_competency_viewed::create_from_user_competency_viewed($uc)->trigger(); 3616 return true; 3617 } 3618 3619 /** 3620 * Log user competency viewed in plan event. 3621 * 3622 * @param user_competency|int $usercompetencyorid The user competency object or user competency id 3623 * @param int $planid The plan ID 3624 * @return bool 3625 */ 3626 public static function user_competency_viewed_in_plan($usercompetencyorid, $planid) { 3627 static::require_enabled(); 3628 $uc = $usercompetencyorid; 3629 if (!is_object($uc)) { 3630 $uc = new user_competency($uc); 3631 } 3632 3633 if (!$uc || !$uc->can_read()) { 3634 throw new required_capability_exception($uc->get_context(), 'moodle/competency:usercompetencyview', 3635 'nopermissions', ''); 3636 } 3637 $plan = new plan($planid); 3638 if ($plan->get('status') == plan::STATUS_COMPLETE) { 3639 throw new coding_exception('To log the user competency in completed plan use user_competency_plan_viewed method.'); 3640 } 3641 3642 \core\event\competency_user_competency_viewed_in_plan::create_from_user_competency_viewed_in_plan($uc, $planid)->trigger(); 3643 return true; 3644 } 3645 3646 /** 3647 * Log user competency viewed in course event. 3648 * 3649 * @param user_competency_course|int $usercoursecompetencyorid The user competency course object or its ID. 3650 * @param int $courseid The course ID 3651 * @return bool 3652 */ 3653 public static function user_competency_viewed_in_course($usercoursecompetencyorid) { 3654 static::require_enabled(); 3655 $ucc = $usercoursecompetencyorid; 3656 if (!is_object($ucc)) { 3657 $ucc = new user_competency_course($ucc); 3658 } 3659 3660 if (!$ucc || !user_competency::can_read_user_in_course($ucc->get('userid'), $ucc->get('courseid'))) { 3661 throw new required_capability_exception($ucc->get_context(), 'moodle/competency:usercompetencyview', 3662 'nopermissions', ''); 3663 } 3664 3665 // Validate the course, this will throw an exception if not valid. 3666 self::validate_course($ucc->get('courseid')); 3667 3668 \core\event\competency_user_competency_viewed_in_course::create_from_user_competency_viewed_in_course($ucc)->trigger(); 3669 return true; 3670 } 3671 3672 /** 3673 * Log user competency plan viewed event. 3674 * 3675 * @param user_competency_plan|int $usercompetencyplanorid The user competency plan object or user competency plan id 3676 * @return bool 3677 */ 3678 public static function user_competency_plan_viewed($usercompetencyplanorid) { 3679 static::require_enabled(); 3680 $ucp = $usercompetencyplanorid; 3681 if (!is_object($ucp)) { 3682 $ucp = new user_competency_plan($ucp); 3683 } 3684 3685 if (!$ucp || !user_competency::can_read_user($ucp->get('userid'))) { 3686 throw new required_capability_exception($ucp->get_context(), 'moodle/competency:usercompetencyview', 3687 'nopermissions', ''); 3688 } 3689 $plan = new plan($ucp->get('planid')); 3690 if ($plan->get('status') != plan::STATUS_COMPLETE) { 3691 throw new coding_exception('To log the user competency in non-completed plan use ' 3692 . 'user_competency_viewed_in_plan method.'); 3693 } 3694 3695 \core\event\competency_user_competency_plan_viewed::create_from_user_competency_plan($ucp)->trigger(); 3696 return true; 3697 } 3698 3699 /** 3700 * Check if template has related data. 3701 * 3702 * @param int $templateid The id of the template to check. 3703 * @return boolean 3704 */ 3705 public static function template_has_related_data($templateid) { 3706 static::require_enabled(); 3707 // First we do a permissions check. 3708 $template = new template($templateid); 3709 3710 if (!$template->can_read()) { 3711 throw new required_capability_exception($template->get_context(), 'moodle/competency:templateview', 3712 'nopermissions', ''); 3713 } 3714 3715 // OK - all set. 3716 return $template->has_plans(); 3717 } 3718 3719 /** 3720 * List all the related competencies. 3721 * 3722 * @param int $competencyid The id of the competency to check. 3723 * @return competency[] 3724 */ 3725 public static function list_related_competencies($competencyid) { 3726 static::require_enabled(); 3727 $competency = new competency($competencyid); 3728 3729 if (!has_any_capability(array('moodle/competency:competencyview', 'moodle/competency:competencymanage'), 3730 $competency->get_context())) { 3731 throw new required_capability_exception($competency->get_context(), 'moodle/competency:competencyview', 3732 'nopermissions', ''); 3733 } 3734 3735 return $competency->get_related_competencies(); 3736 } 3737 3738 /** 3739 * Add a related competency. 3740 * 3741 * @param int $competencyid The id of the competency 3742 * @param int $relatedcompetencyid The id of the related competency. 3743 * @return bool False when create failed, true on success, or if the relation already existed. 3744 */ 3745 public static function add_related_competency($competencyid, $relatedcompetencyid) { 3746 static::require_enabled(); 3747 $competency1 = new competency($competencyid); 3748 $competency2 = new competency($relatedcompetencyid); 3749 3750 require_capability('moodle/competency:competencymanage', $competency1->get_context()); 3751 3752 $relatedcompetency = related_competency::get_relation($competency1->get('id'), $competency2->get('id')); 3753 if (!$relatedcompetency->get('id')) { 3754 $relatedcompetency->create(); 3755 return true; 3756 } 3757 3758 return true; 3759 } 3760 3761 /** 3762 * Remove a related competency. 3763 * 3764 * @param int $competencyid The id of the competency. 3765 * @param int $relatedcompetencyid The id of the related competency. 3766 * @return bool True when it was deleted, false when it wasn't or the relation doesn't exist. 3767 */ 3768 public static function remove_related_competency($competencyid, $relatedcompetencyid) { 3769 static::require_enabled(); 3770 $competency = new competency($competencyid); 3771 3772 // This only check if we have the permission in either competency because both competencies 3773 // should belong to the same framework. 3774 require_capability('moodle/competency:competencymanage', $competency->get_context()); 3775 3776 $relatedcompetency = related_competency::get_relation($competencyid, $relatedcompetencyid); 3777 if ($relatedcompetency->get('id')) { 3778 return $relatedcompetency->delete(); 3779 } 3780 3781 return false; 3782 } 3783 3784 /** 3785 * Read a user evidence. 3786 * 3787 * @param int $id 3788 * @return user_evidence 3789 */ 3790 public static function read_user_evidence($id) { 3791 static::require_enabled(); 3792 $userevidence = new user_evidence($id); 3793 3794 if (!$userevidence->can_read()) { 3795 $context = $userevidence->get_context(); 3796 throw new required_capability_exception($context, 'moodle/competency:userevidenceview', 'nopermissions', ''); 3797 } 3798 3799 return $userevidence; 3800 } 3801 3802 /** 3803 * Create a new user evidence. 3804 * 3805 * @param object $data The data. 3806 * @param int $draftitemid The draft ID in which files have been saved. 3807 * @return user_evidence 3808 */ 3809 public static function create_user_evidence($data, $draftitemid = null) { 3810 static::require_enabled(); 3811 $userevidence = new user_evidence(null, $data); 3812 $context = $userevidence->get_context(); 3813 3814 if (!$userevidence->can_manage()) { 3815 throw new required_capability_exception($context, 'moodle/competency:userevidencemanage', 'nopermissions', ''); 3816 } 3817 3818 $userevidence->create(); 3819 if (!empty($draftitemid)) { 3820 $fileareaoptions = array('subdirs' => true); 3821 $itemid = $userevidence->get('id'); 3822 file_save_draft_area_files($draftitemid, $context->id, 'core_competency', 'userevidence', $itemid, $fileareaoptions); 3823 } 3824 3825 // Trigger an evidence of prior learning created event. 3826 \core\event\competency_user_evidence_created::create_from_user_evidence($userevidence)->trigger(); 3827 3828 return $userevidence; 3829 } 3830 3831 /** 3832 * Create a new user evidence. 3833 * 3834 * @param object $data The data. 3835 * @param int $draftitemid The draft ID in which files have been saved. 3836 * @return user_evidence 3837 */ 3838 public static function update_user_evidence($data, $draftitemid = null) { 3839 static::require_enabled(); 3840 $userevidence = new user_evidence($data->id); 3841 $context = $userevidence->get_context(); 3842 3843 if (!$userevidence->can_manage()) { 3844 throw new required_capability_exception($context, 'moodle/competency:userevidencemanage', 'nopermissions', ''); 3845 3846 } else if (property_exists($data, 'userid') && $data->userid != $userevidence->get('userid')) { 3847 throw new coding_exception('Can not change the userid of a user evidence.'); 3848 } 3849 3850 $userevidence->from_record($data); 3851 $userevidence->update(); 3852 3853 if (!empty($draftitemid)) { 3854 $fileareaoptions = array('subdirs' => true); 3855 $itemid = $userevidence->get('id'); 3856 file_save_draft_area_files($draftitemid, $context->id, 'core_competency', 'userevidence', $itemid, $fileareaoptions); 3857 } 3858 3859 // Trigger an evidence of prior learning updated event. 3860 \core\event\competency_user_evidence_updated::create_from_user_evidence($userevidence)->trigger(); 3861 3862 return $userevidence; 3863 } 3864 3865 /** 3866 * Delete a user evidence. 3867 * 3868 * @param int $id The user evidence ID. 3869 * @return bool 3870 */ 3871 public static function delete_user_evidence($id) { 3872 static::require_enabled(); 3873 $userevidence = new user_evidence($id); 3874 $context = $userevidence->get_context(); 3875 3876 if (!$userevidence->can_manage()) { 3877 throw new required_capability_exception($context, 'moodle/competency:userevidencemanage', 'nopermissions', ''); 3878 } 3879 3880 // Delete the user evidence. 3881 $userevidence->delete(); 3882 3883 // Delete associated files. 3884 $fs = get_file_storage(); 3885 $fs->delete_area_files($context->id, 'core_competency', 'userevidence', $id); 3886 3887 // Delete relation between evidence and competencies. 3888 $userevidence->set('id', $id); // Restore the ID to fully mock the object. 3889 $competencies = user_evidence_competency::get_competencies_by_userevidenceid($id); 3890 foreach ($competencies as $competency) { 3891 static::delete_user_evidence_competency($userevidence, $competency->get('id')); 3892 } 3893 3894 // Trigger an evidence of prior learning deleted event. 3895 \core\event\competency_user_evidence_deleted::create_from_user_evidence($userevidence)->trigger(); 3896 3897 $userevidence->set('id', 0); // Restore the object. 3898 3899 return true; 3900 } 3901 3902 /** 3903 * List the user evidence of a user. 3904 * 3905 * @param int $userid The user ID. 3906 * @return user_evidence[] 3907 */ 3908 public static function list_user_evidence($userid) { 3909 static::require_enabled(); 3910 if (!user_evidence::can_read_user($userid)) { 3911 $context = context_user::instance($userid); 3912 throw new required_capability_exception($context, 'moodle/competency:userevidenceview', 'nopermissions', ''); 3913 } 3914 3915 $evidence = user_evidence::get_records(array('userid' => $userid), 'name'); 3916 return $evidence; 3917 } 3918 3919 /** 3920 * Link a user evidence with a competency. 3921 * 3922 * @param user_evidence|int $userevidenceorid User evidence or its ID. 3923 * @param int $competencyid Competency ID. 3924 * @return user_evidence_competency 3925 */ 3926 public static function create_user_evidence_competency($userevidenceorid, $competencyid) { 3927 global $USER; 3928 static::require_enabled(); 3929 3930 $userevidence = $userevidenceorid; 3931 if (!is_object($userevidence)) { 3932 $userevidence = self::read_user_evidence($userevidence); 3933 } 3934 3935 // Perform user evidence capability checks. 3936 if (!$userevidence->can_manage()) { 3937 $context = $userevidence->get_context(); 3938 throw new required_capability_exception($context, 'moodle/competency:userevidencemanage', 'nopermissions', ''); 3939 } 3940 3941 // Perform competency capability checks. 3942 $competency = self::read_competency($competencyid); 3943 3944 // Get (and create) the relation. 3945 $relation = user_evidence_competency::get_relation($userevidence->get('id'), $competency->get('id')); 3946 if (!$relation->get('id')) { 3947 $relation->create(); 3948 3949 $link = url::user_evidence($userevidence->get('id')); 3950 self::add_evidence( 3951 $userevidence->get('userid'), 3952 $competency, 3953 $userevidence->get_context(), 3954 evidence::ACTION_LOG, 3955 'evidence_evidenceofpriorlearninglinked', 3956 'core_competency', 3957 $userevidence->get('name'), 3958 false, 3959 $link->out(false), 3960 null, 3961 $USER->id 3962 ); 3963 } 3964 3965 return $relation; 3966 } 3967 3968 /** 3969 * Delete a relationship between a user evidence and a competency. 3970 * 3971 * @param user_evidence|int $userevidenceorid User evidence or its ID. 3972 * @param int $competencyid Competency ID. 3973 * @return bool 3974 */ 3975 public static function delete_user_evidence_competency($userevidenceorid, $competencyid) { 3976 global $USER; 3977 static::require_enabled(); 3978 3979 $userevidence = $userevidenceorid; 3980 if (!is_object($userevidence)) { 3981 $userevidence = self::read_user_evidence($userevidence); 3982 } 3983 3984 // Perform user evidence capability checks. 3985 if (!$userevidence->can_manage()) { 3986 $context = $userevidence->get_context(); 3987 throw new required_capability_exception($context, 'moodle/competency:userevidencemanage', 'nopermissions', ''); 3988 } 3989 3990 // Get (and delete) the relation. 3991 $relation = user_evidence_competency::get_relation($userevidence->get('id'), $competencyid); 3992 if (!$relation->get('id')) { 3993 return true; 3994 } 3995 3996 $success = $relation->delete(); 3997 if ($success) { 3998 self::add_evidence( 3999 $userevidence->get('userid'), 4000 $competencyid, 4001 $userevidence->get_context(), 4002 evidence::ACTION_LOG, 4003 'evidence_evidenceofpriorlearningunlinked', 4004 'core_competency', 4005 $userevidence->get('name'), 4006 false, 4007 null, 4008 null, 4009 $USER->id 4010 ); 4011 } 4012 4013 return $success; 4014 } 4015 4016 /** 4017 * Send request review for user evidence competencies. 4018 * 4019 * @param int $id The user evidence ID. 4020 * @return bool 4021 */ 4022 public static function request_review_of_user_evidence_linked_competencies($id) { 4023 $userevidence = new user_evidence($id); 4024 $context = $userevidence->get_context(); 4025 $userid = $userevidence->get('userid'); 4026 4027 if (!$userevidence->can_manage()) { 4028 throw new required_capability_exception($context, 'moodle/competency:userevidencemanage', 'nopermissions', ''); 4029 } 4030 4031 $usercompetencies = user_evidence_competency::get_user_competencies_by_userevidenceid($id); 4032 foreach ($usercompetencies as $usercompetency) { 4033 if ($usercompetency->get('status') == user_competency::STATUS_IDLE) { 4034 static::user_competency_request_review($userid, $usercompetency->get('competencyid')); 4035 } 4036 } 4037 4038 return true; 4039 } 4040 4041 /** 4042 * Recursively duplicate competencies from a tree, we start duplicating from parents to children to have a correct path. 4043 * This method does not copy the related competencies. 4044 * 4045 * @param int $frameworkid - framework id 4046 * @param stdClass[] $tree - list of framework competency nodes 4047 * @param int $oldparent - old parent id 4048 * @param int $newparent - new parent id 4049 * @return competency[] $matchids - List of old competencies ids matched with new competencies object. 4050 */ 4051 protected static function duplicate_competency_tree($frameworkid, $tree, $oldparent = 0, $newparent = 0) { 4052 $matchids = array(); 4053 foreach ($tree as $node) { 4054 if ($node->competency->get('parentid') == $oldparent) { 4055 $parentid = $node->competency->get('id'); 4056 4057 // Create the competency. 4058 $competency = new competency(0, $node->competency->to_record()); 4059 $competency->set('competencyframeworkid', $frameworkid); 4060 $competency->set('parentid', $newparent); 4061 $competency->set('path', ''); 4062 $competency->set('id', 0); 4063 $competency->reset_rule(); 4064 $competency->create(); 4065 4066 // Trigger the created event competency. 4067 \core\event\competency_created::create_from_competency($competency)->trigger(); 4068 4069 // Match the old id with the new one. 4070 $matchids[$parentid] = $competency; 4071 4072 if (!empty($node->children)) { 4073 // Duplicate children competency. 4074 $childrenids = self::duplicate_competency_tree($frameworkid, $node->children, $parentid, $competency->get('id')); 4075 // Array_merge does not keep keys when merging so we use the + operator. 4076 $matchids = $matchids + $childrenids; 4077 } 4078 } 4079 } 4080 return $matchids; 4081 } 4082 4083 /** 4084 * Recursively migrate competency rules. 4085 * 4086 * @param array $tree - array of competencies object 4087 * @param competency[] $matchids - List of old competencies ids matched with new competencies object 4088 */ 4089 protected static function migrate_competency_tree_rules($tree, $matchids) { 4090 4091 foreach ($tree as $node) { 4092 $oldcompid = $node->competency->get('id'); 4093 if ($node->competency->get('ruletype') && array_key_exists($oldcompid, $matchids)) { 4094 try { 4095 // Get the new competency. 4096 $competency = $matchids[$oldcompid]; 4097 $class = $node->competency->get('ruletype'); 4098 $newruleconfig = $class::migrate_config($node->competency->get('ruleconfig'), $matchids); 4099 $competency->set('ruleconfig', $newruleconfig); 4100 $competency->set('ruletype', $class); 4101 $competency->set('ruleoutcome', $node->competency->get('ruleoutcome')); 4102 $competency->update(); 4103 } catch (\Exception $e) { 4104 debugging('Could not migrate competency rule from: ' . $oldcompid . ' to: ' . $competency->get('id') . '.' . 4105 ' Exception: ' . $e->getMessage(), DEBUG_DEVELOPER); 4106 $competency->reset_rule(); 4107 } 4108 } 4109 4110 if (!empty($node->children)) { 4111 self::migrate_competency_tree_rules($node->children, $matchids); 4112 } 4113 } 4114 } 4115 4116 /** 4117 * Archive user competencies in a plan. 4118 * 4119 * @param plan $plan The plan object. 4120 * @return void 4121 */ 4122 protected static function archive_user_competencies_in_plan($plan) { 4123 4124 // Check if the plan was already completed. 4125 if ($plan->get('status') == plan::STATUS_COMPLETE) { 4126 throw new coding_exception('The plan is already completed.'); 4127 } 4128 4129 $competencies = $plan->get_competencies(); 4130 $usercompetencies = user_competency::get_multiple($plan->get('userid'), $competencies); 4131 4132 $i = 0; 4133 foreach ($competencies as $competency) { 4134 $found = false; 4135 4136 foreach ($usercompetencies as $uckey => $uc) { 4137 if ($uc->get('competencyid') == $competency->get('id')) { 4138 $found = true; 4139 4140 $ucprecord = $uc->to_record(); 4141 $ucprecord->planid = $plan->get('id'); 4142 $ucprecord->sortorder = $i; 4143 unset($ucprecord->id); 4144 unset($ucprecord->status); 4145 unset($ucprecord->reviewerid); 4146 4147 $usercompetencyplan = new user_competency_plan(0, $ucprecord); 4148 $usercompetencyplan->create(); 4149 4150 unset($usercompetencies[$uckey]); 4151 break; 4152 } 4153 } 4154 4155 // If the user competency doesn't exist, we create a new relation in user_competency_plan. 4156 if (!$found) { 4157 $usercompetencyplan = user_competency_plan::create_relation($plan->get('userid'), $competency->get('id'), 4158 $plan->get('id')); 4159 $usercompetencyplan->set('sortorder', $i); 4160 $usercompetencyplan->create(); 4161 } 4162 $i++; 4163 } 4164 } 4165 4166 /** 4167 * Delete archived user competencies in a plan. 4168 * 4169 * @param plan $plan The plan object. 4170 * @return void 4171 */ 4172 protected static function remove_archived_user_competencies_in_plan($plan) { 4173 $competencies = $plan->get_competencies(); 4174 $usercompetenciesplan = user_competency_plan::get_multiple($plan->get('userid'), $plan->get('id'), $competencies); 4175 4176 foreach ($usercompetenciesplan as $ucpkey => $ucp) { 4177 $ucp->delete(); 4178 } 4179 } 4180 4181 /** 4182 * List all the evidence for a user competency. 4183 * 4184 * @param int $userid The user id - only used if usercompetencyid is 0. 4185 * @param int $competencyid The competency id - only used it usercompetencyid is 0. 4186 * @param int $planid The plan id - not used yet - but can be used to only list archived evidence if a plan is completed. 4187 * @param string $sort The field to sort the evidence by. 4188 * @param string $order The ordering of the sorting. 4189 * @param int $skip Number of records to skip. 4190 * @param int $limit Number of records to return. 4191 * @return \core_competency\evidence[] 4192 * @return array of \core_competency\evidence 4193 */ 4194 public static function list_evidence($userid = 0, $competencyid = 0, $planid = 0, $sort = 'timecreated', 4195 $order = 'DESC', $skip = 0, $limit = 0) { 4196 static::require_enabled(); 4197 4198 if (!user_competency::can_read_user($userid)) { 4199 $context = context_user::instance($userid); 4200 throw new required_capability_exception($context, 'moodle/competency:usercompetencyview', 'nopermissions', ''); 4201 } 4202 4203 $usercompetency = user_competency::get_record(array('userid' => $userid, 'competencyid' => $competencyid)); 4204 if (!$usercompetency) { 4205 return array(); 4206 } 4207 4208 $plancompleted = false; 4209 if ($planid != 0) { 4210 $plan = new plan($planid); 4211 if ($plan->get('status') == plan::STATUS_COMPLETE) { 4212 $plancompleted = true; 4213 } 4214 } 4215 4216 $select = 'usercompetencyid = :usercompetencyid'; 4217 $params = array('usercompetencyid' => $usercompetency->get('id')); 4218 if ($plancompleted) { 4219 $select .= ' AND timecreated <= :timecompleted'; 4220 $params['timecompleted'] = $plan->get('timemodified'); 4221 } 4222 4223 $orderby = $sort . ' ' . $order; 4224 $orderby .= !empty($orderby) ? ', id DESC' : 'id DESC'; // Prevent random ordering. 4225 4226 $evidence = evidence::get_records_select($select, $params, $orderby, '*', $skip, $limit); 4227 return $evidence; 4228 } 4229 4230 /** 4231 * List all the evidence for a user competency in a course. 4232 * 4233 * @param int $userid The user ID. 4234 * @param int $courseid The course ID. 4235 * @param int $competencyid The competency ID. 4236 * @param string $sort The field to sort the evidence by. 4237 * @param string $order The ordering of the sorting. 4238 * @param int $skip Number of records to skip. 4239 * @param int $limit Number of records to return. 4240 * @return \core_competency\evidence[] 4241 */ 4242 public static function list_evidence_in_course($userid = 0, $courseid = 0, $competencyid = 0, $sort = 'timecreated', 4243 $order = 'DESC', $skip = 0, $limit = 0) { 4244 static::require_enabled(); 4245 4246 if (!user_competency::can_read_user_in_course($userid, $courseid)) { 4247 $context = context_user::instance($userid); 4248 throw new required_capability_exception($context, 'moodle/competency:usercompetencyview', 'nopermissions', ''); 4249 } 4250 4251 $usercompetency = user_competency::get_record(array('userid' => $userid, 'competencyid' => $competencyid)); 4252 if (!$usercompetency) { 4253 return array(); 4254 } 4255 4256 $context = context_course::instance($courseid); 4257 return evidence::get_records_for_usercompetency($usercompetency->get('id'), $context, $sort, $order, $skip, $limit); 4258 } 4259 4260 /** 4261 * Create an evidence from a list of parameters. 4262 * 4263 * Requires no capability because evidence can be added in many situations under any user. 4264 * 4265 * @param int $userid The user id for which evidence is added. 4266 * @param competency|int $competencyorid The competency, or its id for which evidence is added. 4267 * @param context|int $contextorid The context in which the evidence took place. 4268 * @param int $action The type of action to take on the competency. \core_competency\evidence::ACTION_*. 4269 * @param string $descidentifier The strings identifier. 4270 * @param string $desccomponent The strings component. 4271 * @param mixed $desca Any arguments the string requires. 4272 * @param bool $recommend When true, the user competency will be sent for review. 4273 * @param string $url The url the evidence may link to. 4274 * @param int $grade The grade, or scale ID item. 4275 * @param int $actionuserid The ID of the user who took the action of adding the evidence. Null when system. 4276 * This should be used when the action was taken by a real person, this will allow 4277 * to keep track of all the evidence given by a certain person. 4278 * @param string $note A note to attach to the evidence. 4279 * @return evidence 4280 * @throws coding_exception 4281 * @throws invalid_persistent_exception 4282 * @throws moodle_exception 4283 */ 4284 public static function add_evidence($userid, $competencyorid, $contextorid, $action, $descidentifier, $desccomponent, 4285 $desca = null, $recommend = false, $url = null, $grade = null, $actionuserid = null, 4286 $note = null, $overridegrade = false) { 4287 global $DB; 4288 static::require_enabled(); 4289 4290 // Some clearly important variable assignments right there. 4291 $competencyid = $competencyorid; 4292 $competency = null; 4293 if (is_object($competencyid)) { 4294 $competency = $competencyid; 4295 $competencyid = $competency->get('id'); 4296 } 4297 $contextid = $contextorid; 4298 $context = $contextorid; 4299 if (is_object($contextorid)) { 4300 $contextid = $contextorid->id; 4301 } else { 4302 $context = context::instance_by_id($contextorid); 4303 } 4304 $setucgrade = false; 4305 $ucgrade = null; 4306 $ucproficiency = null; 4307 $usercompetencycourse = null; 4308 4309 // Fetch or create the user competency. 4310 $usercompetency = user_competency::get_record(array('userid' => $userid, 'competencyid' => $competencyid)); 4311 if (!$usercompetency) { 4312 $usercompetency = user_competency::create_relation($userid, $competencyid); 4313 $usercompetency->create(); 4314 } 4315 4316 // What should we be doing? 4317 switch ($action) { 4318 4319 // Completing a competency. 4320 case evidence::ACTION_COMPLETE: 4321 // The logic here goes like this: 4322 // 4323 // if rating outside a course 4324 // - set the default grade and proficiency ONLY if there is no current grade 4325 // else we are in a course 4326 // - set the defautl grade and proficiency in the course ONLY if there is no current grade in the course 4327 // - then check the course settings to see if we should push the rating outside the course 4328 // - if we should push it 4329 // --- push it only if the user_competency (outside the course) has no grade 4330 // Done. 4331 4332 if ($grade !== null) { 4333 throw new coding_exception("The grade MUST NOT be set with a 'completing' evidence."); 4334 } 4335 4336 // Fetch the default grade to attach to the evidence. 4337 if (empty($competency)) { 4338 $competency = new competency($competencyid); 4339 } 4340 list($grade, $proficiency) = $competency->get_default_grade(); 4341 4342 // Add user_competency_course record when in a course or module. 4343 if (in_array($context->contextlevel, array(CONTEXT_COURSE, CONTEXT_MODULE))) { 4344 $coursecontext = $context->get_course_context(); 4345 $courseid = $coursecontext->instanceid; 4346 $filterparams = array( 4347 'userid' => $userid, 4348 'competencyid' => $competencyid, 4349 'courseid' => $courseid 4350 ); 4351 // Fetch or create user competency course. 4352 $usercompetencycourse = user_competency_course::get_record($filterparams); 4353 if (!$usercompetencycourse) { 4354 $usercompetencycourse = user_competency_course::create_relation($userid, $competencyid, $courseid); 4355 $usercompetencycourse->create(); 4356 } 4357 // Only update the grade and proficiency if there is not already a grade or the override option is enabled. 4358 if ($usercompetencycourse->get('grade') === null || $overridegrade) { 4359 // Set grade. 4360 $usercompetencycourse->set('grade', $grade); 4361 // Set proficiency. 4362 $usercompetencycourse->set('proficiency', $proficiency); 4363 } 4364 4365 // Check the course settings to see if we should push to user plans. 4366 $coursesettings = course_competency_settings::get_by_courseid($courseid); 4367 $setucgrade = $coursesettings->get('pushratingstouserplans'); 4368 4369 if ($setucgrade) { 4370 // Only push to user plans if there is not already a grade or the override option is enabled. 4371 if ($usercompetency->get('grade') !== null && !$overridegrade) { 4372 $setucgrade = false; 4373 } else { 4374 $ucgrade = $grade; 4375 $ucproficiency = $proficiency; 4376 } 4377 } 4378 } else { 4379 4380 // When completing the competency we fetch the default grade from the competency. But we only mark 4381 // the user competency when a grade has not been set yet or if override option is enabled. 4382 // Complete is an action to use with automated systems. 4383 if ($usercompetency->get('grade') === null || $overridegrade) { 4384 $setucgrade = true; 4385 $ucgrade = $grade; 4386 $ucproficiency = $proficiency; 4387 } 4388 } 4389 4390 break; 4391 4392 // We override the grade, even overriding back to not set. 4393 case evidence::ACTION_OVERRIDE: 4394 $setucgrade = true; 4395 $ucgrade = $grade; 4396 if (empty($competency)) { 4397 $competency = new competency($competencyid); 4398 } 4399 if ($ucgrade !== null) { 4400 $ucproficiency = $competency->get_proficiency_of_grade($ucgrade); 4401 } 4402 4403 // Add user_competency_course record when in a course or module. 4404 if (in_array($context->contextlevel, array(CONTEXT_COURSE, CONTEXT_MODULE))) { 4405 $coursecontext = $context->get_course_context(); 4406 $courseid = $coursecontext->instanceid; 4407 $filterparams = array( 4408 'userid' => $userid, 4409 'competencyid' => $competencyid, 4410 'courseid' => $courseid 4411 ); 4412 // Fetch or create user competency course. 4413 $usercompetencycourse = user_competency_course::get_record($filterparams); 4414 if (!$usercompetencycourse) { 4415 $usercompetencycourse = user_competency_course::create_relation($userid, $competencyid, $courseid); 4416 $usercompetencycourse->create(); 4417 } 4418 // Get proficiency. 4419 $proficiency = $ucproficiency; 4420 if ($proficiency === null) { 4421 if (empty($competency)) { 4422 $competency = new competency($competencyid); 4423 } 4424 $proficiency = $competency->get_proficiency_of_grade($grade); 4425 } 4426 // Set grade. 4427 $usercompetencycourse->set('grade', $grade); 4428 // Set proficiency. 4429 $usercompetencycourse->set('proficiency', $proficiency); 4430 4431 $coursesettings = course_competency_settings::get_by_courseid($courseid); 4432 if (!$coursesettings->get('pushratingstouserplans')) { 4433 $setucgrade = false; 4434 } 4435 } 4436 4437 break; 4438 4439 // Simply logging an evidence. 4440 case evidence::ACTION_LOG: 4441 if ($grade !== null) { 4442 throw new coding_exception("The grade MUST NOT be set when 'logging' an evidence."); 4443 } 4444 break; 4445 4446 // Whoops, this is not expected. 4447 default: 4448 throw new coding_exception('Unexpected action parameter when registering an evidence.'); 4449 break; 4450 } 4451 4452 // Should we recommend? 4453 if ($recommend && $usercompetency->get('status') == user_competency::STATUS_IDLE) { 4454 $usercompetency->set('status', user_competency::STATUS_WAITING_FOR_REVIEW); 4455 } 4456 4457 // Setting the grade and proficiency for the user competency. 4458 $wascompleted = false; 4459 if ($setucgrade == true) { 4460 if (!$usercompetency->get('proficiency') && $ucproficiency) { 4461 $wascompleted = true; 4462 } 4463 $usercompetency->set('grade', $ucgrade); 4464 $usercompetency->set('proficiency', $ucproficiency); 4465 } 4466 4467 // Prepare the evidence. 4468 $record = new stdClass(); 4469 $record->usercompetencyid = $usercompetency->get('id'); 4470 $record->contextid = $contextid; 4471 $record->action = $action; 4472 $record->descidentifier = $descidentifier; 4473 $record->desccomponent = $desccomponent; 4474 $record->grade = $grade; 4475 $record->actionuserid = $actionuserid; 4476 $record->note = $note; 4477 $evidence = new evidence(0, $record); 4478 $evidence->set('desca', $desca); 4479 $evidence->set('url', $url); 4480 4481 // Validate both models, we should not operate on one if the other will not save. 4482 if (!$usercompetency->is_valid()) { 4483 throw new invalid_persistent_exception($usercompetency->get_errors()); 4484 } else if (!$evidence->is_valid()) { 4485 throw new invalid_persistent_exception($evidence->get_errors()); 4486 } 4487 4488 // Save the user_competency_course record. 4489 if ($usercompetencycourse !== null) { 4490 // Validate and update. 4491 if (!$usercompetencycourse->is_valid()) { 4492 throw new invalid_persistent_exception($usercompetencycourse->get_errors()); 4493 } 4494 $usercompetencycourse->update(); 4495 } 4496 4497 // Finally save. Pheww! 4498 $usercompetency->update(); 4499 $evidence->create(); 4500 4501 // Trigger the evidence_created event. 4502 \core\event\competency_evidence_created::create_from_evidence($evidence, $usercompetency, $recommend)->trigger(); 4503 4504 // The competency was marked as completed, apply the rules. 4505 if ($wascompleted) { 4506 self::apply_competency_rules_from_usercompetency($usercompetency, $competency, $overridegrade); 4507 } 4508 4509 return $evidence; 4510 } 4511 4512 /** 4513 * Read an evidence. 4514 * @param int $evidenceid The evidence ID. 4515 * @return evidence 4516 */ 4517 public static function read_evidence($evidenceid) { 4518 static::require_enabled(); 4519 4520 $evidence = new evidence($evidenceid); 4521 $uc = new user_competency($evidence->get('usercompetencyid')); 4522 if (!$uc->can_read()) { 4523 throw new required_capability_exception($uc->get_context(), 'moodle/competency:usercompetencyview', 4524 'nopermissions', ''); 4525 } 4526 4527 return $evidence; 4528 } 4529 4530 /** 4531 * Delete an evidence. 4532 * 4533 * @param evidence|int $evidenceorid The evidence, or its ID. 4534 * @return bool 4535 */ 4536 public static function delete_evidence($evidenceorid) { 4537 $evidence = $evidenceorid; 4538 if (!is_object($evidence)) { 4539 $evidence = new evidence($evidenceorid); 4540 } 4541 4542 $uc = new user_competency($evidence->get('usercompetencyid')); 4543 if (!evidence::can_delete_user($uc->get('userid'))) { 4544 throw new required_capability_exception($uc->get_context(), 'moodle/competency:evidencedelete', 'nopermissions', ''); 4545 } 4546 4547 return $evidence->delete(); 4548 } 4549 4550 /** 4551 * Apply the competency rules from a user competency. 4552 * 4553 * The user competency passed should be one that was recently marked as complete. 4554 * A user competency is considered 'complete' when it's proficiency value is true. 4555 * 4556 * This method will check if the parent of this usercompetency's competency has any 4557 * rules and if so will see if they match. When matched it will take the required 4558 * step to add evidence and trigger completion, etc... 4559 * 4560 * @param user_competency $usercompetency The user competency recently completed. 4561 * @param competency|null $competency The competency of the user competency, useful to avoid unnecessary read. 4562 * @return void 4563 */ 4564 protected static function apply_competency_rules_from_usercompetency(user_competency $usercompetency, 4565 competency $competency = null, $overridegrade = false) { 4566 4567 // Perform some basic checks. 4568 if (!$usercompetency->get('proficiency')) { 4569 throw new coding_exception('The user competency passed is not completed.'); 4570 } 4571 if ($competency === null) { 4572 $competency = $usercompetency->get_competency(); 4573 } 4574 if ($competency->get('id') != $usercompetency->get('competencyid')) { 4575 throw new coding_exception('Mismatch between user competency and competency.'); 4576 } 4577 4578 // Fetch the parent. 4579 $parent = $competency->get_parent(); 4580 if ($parent === null) { 4581 return; 4582 } 4583 4584 // The parent should have a rule, and a meaningful outcome. 4585 $ruleoutcome = $parent->get('ruleoutcome'); 4586 if ($ruleoutcome == competency::OUTCOME_NONE) { 4587 return; 4588 } 4589 $rule = $parent->get_rule_object(); 4590 if ($rule === null) { 4591 return; 4592 } 4593 4594 // Fetch or create the user competency for the parent. 4595 $userid = $usercompetency->get('userid'); 4596 $parentuc = user_competency::get_record(array('userid' => $userid, 'competencyid' => $parent->get('id'))); 4597 if (!$parentuc) { 4598 $parentuc = user_competency::create_relation($userid, $parent->get('id')); 4599 $parentuc->create(); 4600 } 4601 4602 // Does the rule match? 4603 if (!$rule->matches($parentuc)) { 4604 return; 4605 } 4606 4607 // Figuring out what to do. 4608 $recommend = false; 4609 if ($ruleoutcome == competency::OUTCOME_EVIDENCE) { 4610 $action = evidence::ACTION_LOG; 4611 4612 } else if ($ruleoutcome == competency::OUTCOME_RECOMMEND) { 4613 $action = evidence::ACTION_LOG; 4614 $recommend = true; 4615 4616 } else if ($ruleoutcome == competency::OUTCOME_COMPLETE) { 4617 $action = evidence::ACTION_COMPLETE; 4618 4619 } else { 4620 throw new moodle_exception('Unexpected rule outcome: ' + $ruleoutcome); 4621 } 4622 4623 // Finally add an evidence. 4624 static::add_evidence( 4625 $userid, 4626 $parent, 4627 $parent->get_context()->id, 4628 $action, 4629 'evidence_competencyrule', 4630 'core_competency', 4631 null, 4632 $recommend, 4633 null, 4634 null, 4635 null, 4636 null, 4637 $overridegrade 4638 ); 4639 } 4640 4641 /** 4642 * Observe when a course module is marked as completed. 4643 * 4644 * Note that the user being logged in while this happens may be anyone. 4645 * Do not rely on capability checks here! 4646 * 4647 * @param \core\event\course_module_completion_updated $event 4648 * @return void 4649 */ 4650 public static function observe_course_module_completion_updated(\core\event\course_module_completion_updated $event) { 4651 if (!static::is_enabled()) { 4652 return; 4653 } 4654 4655 $eventdata = $event->get_record_snapshot('course_modules_completion', $event->objectid); 4656 4657 if ($eventdata->completionstate == COMPLETION_COMPLETE 4658 || $eventdata->completionstate == COMPLETION_COMPLETE_PASS) { 4659 $coursemodulecompetencies = course_module_competency::list_course_module_competencies($eventdata->coursemoduleid); 4660 4661 $cm = get_coursemodule_from_id(null, $eventdata->coursemoduleid); 4662 $fastmodinfo = get_fast_modinfo($cm->course)->cms[$cm->id]; 4663 4664 $cmname = $fastmodinfo->name; 4665 $url = $fastmodinfo->url; 4666 4667 foreach ($coursemodulecompetencies as $coursemodulecompetency) { 4668 $outcome = $coursemodulecompetency->get('ruleoutcome'); 4669 $action = null; 4670 $recommend = false; 4671 $strdesc = 'evidence_coursemodulecompleted'; 4672 $overridegrade = $coursemodulecompetency->get('overridegrade'); 4673 4674 if ($outcome == course_module_competency::OUTCOME_NONE) { 4675 continue; 4676 } 4677 if ($outcome == course_module_competency::OUTCOME_EVIDENCE) { 4678 $action = evidence::ACTION_LOG; 4679 4680 } else if ($outcome == course_module_competency::OUTCOME_RECOMMEND) { 4681 $action = evidence::ACTION_LOG; 4682 $recommend = true; 4683 4684 } else if ($outcome == course_module_competency::OUTCOME_COMPLETE) { 4685 $action = evidence::ACTION_COMPLETE; 4686 4687 } else { 4688 throw new moodle_exception('Unexpected rule outcome: ' + $outcome); 4689 } 4690 4691 static::add_evidence( 4692 $event->relateduserid, 4693 $coursemodulecompetency->get('competencyid'), 4694 $event->contextid, 4695 $action, 4696 $strdesc, 4697 'core_competency', 4698 $cmname, 4699 $recommend, 4700 $url, 4701 null, 4702 null, 4703 null, 4704 $overridegrade 4705 ); 4706 } 4707 } 4708 } 4709 4710 /** 4711 * Observe when a course is marked as completed. 4712 * 4713 * Note that the user being logged in while this happens may be anyone. 4714 * Do not rely on capability checks here! 4715 * 4716 * @param \core\event\course_completed $event 4717 * @return void 4718 */ 4719 public static function observe_course_completed(\core\event\course_completed $event) { 4720 if (!static::is_enabled()) { 4721 return; 4722 } 4723 4724 $sql = 'courseid = :courseid AND ruleoutcome != :nooutcome'; 4725 $params = array( 4726 'courseid' => $event->courseid, 4727 'nooutcome' => course_competency::OUTCOME_NONE 4728 ); 4729 $coursecompetencies = course_competency::get_records_select($sql, $params); 4730 4731 $course = get_course($event->courseid); 4732 $courseshortname = format_string($course->shortname, null, array('context' => $event->contextid)); 4733 4734 foreach ($coursecompetencies as $coursecompetency) { 4735 4736 $outcome = $coursecompetency->get('ruleoutcome'); 4737 $action = null; 4738 $recommend = false; 4739 $strdesc = 'evidence_coursecompleted'; 4740 4741 if ($outcome == course_module_competency::OUTCOME_NONE) { 4742 continue; 4743 } 4744 if ($outcome == course_competency::OUTCOME_EVIDENCE) { 4745 $action = evidence::ACTION_LOG; 4746 4747 } else if ($outcome == course_competency::OUTCOME_RECOMMEND) { 4748 $action = evidence::ACTION_LOG; 4749 $recommend = true; 4750 4751 } else if ($outcome == course_competency::OUTCOME_COMPLETE) { 4752 $action = evidence::ACTION_COMPLETE; 4753 4754 } else { 4755 throw new moodle_exception('Unexpected rule outcome: ' + $outcome); 4756 } 4757 4758 static::add_evidence( 4759 $event->relateduserid, 4760 $coursecompetency->get('competencyid'), 4761 $event->contextid, 4762 $action, 4763 $strdesc, 4764 'core_competency', 4765 $courseshortname, 4766 $recommend, 4767 $event->get_url() 4768 ); 4769 } 4770 } 4771 4772 /** 4773 * Action to perform when a course module is deleted. 4774 * 4775 * Do not call this directly, this is reserved for core use. 4776 * 4777 * @param stdClass $cm The CM object. 4778 * @return void 4779 */ 4780 public static function hook_course_module_deleted(stdClass $cm) { 4781 global $DB; 4782 $DB->delete_records(course_module_competency::TABLE, array('cmid' => $cm->id)); 4783 } 4784 4785 /** 4786 * Action to perform when a course is deleted. 4787 * 4788 * Do not call this directly, this is reserved for core use. 4789 * 4790 * @param stdClass $course The course object. 4791 * @return void 4792 */ 4793 public static function hook_course_deleted(stdClass $course) { 4794 global $DB; 4795 $DB->delete_records(course_competency::TABLE, array('courseid' => $course->id)); 4796 $DB->delete_records(course_competency_settings::TABLE, array('courseid' => $course->id)); 4797 $DB->delete_records(user_competency_course::TABLE, array('courseid' => $course->id)); 4798 } 4799 4800 /** 4801 * Action to perform when a course is being reset. 4802 * 4803 * Do not call this directly, this is reserved for core use. 4804 * 4805 * @param int $courseid The course ID. 4806 * @return void 4807 */ 4808 public static function hook_course_reset_competency_ratings($courseid) { 4809 global $DB; 4810 $DB->delete_records(user_competency_course::TABLE, array('courseid' => $courseid)); 4811 } 4812 4813 /** 4814 * Action to perform when a cohort is deleted. 4815 * 4816 * Do not call this directly, this is reserved for core use. 4817 * 4818 * @param \stdClass $cohort The cohort object. 4819 * @return void 4820 */ 4821 public static function hook_cohort_deleted(\stdClass $cohort) { 4822 global $DB; 4823 $DB->delete_records(template_cohort::TABLE, array('cohortid' => $cohort->id)); 4824 } 4825 4826 /** 4827 * Action to perform when a user is deleted. 4828 * 4829 * @param int $userid The user id. 4830 */ 4831 public static function hook_user_deleted($userid) { 4832 global $DB; 4833 4834 $usercompetencies = $DB->get_records(user_competency::TABLE, ['userid' => $userid], '', 'id'); 4835 foreach ($usercompetencies as $usercomp) { 4836 $DB->delete_records(evidence::TABLE, ['usercompetencyid' => $usercomp->id]); 4837 } 4838 4839 $DB->delete_records(user_competency::TABLE, ['userid' => $userid]); 4840 $DB->delete_records(user_competency_course::TABLE, ['userid' => $userid]); 4841 $DB->delete_records(user_competency_plan::TABLE, ['userid' => $userid]); 4842 4843 // Delete any associated files. 4844 $fs = get_file_storage(); 4845 $context = context_user::instance($userid); 4846 $userevidences = $DB->get_records(user_evidence::TABLE, ['userid' => $userid], '', 'id'); 4847 foreach ($userevidences as $userevidence) { 4848 $DB->delete_records(user_evidence_competency::TABLE, ['userevidenceid' => $userevidence->id]); 4849 $DB->delete_records(user_evidence::TABLE, ['id' => $userevidence->id]); 4850 $fs->delete_area_files($context->id, 'core_competency', 'userevidence', $userevidence->id); 4851 } 4852 4853 $userplans = $DB->get_records(plan::TABLE, ['userid' => $userid], '', 'id'); 4854 foreach ($userplans as $userplan) { 4855 $DB->delete_records(plan_competency::TABLE, ['planid' => $userplan->id]); 4856 $DB->delete_records(plan::TABLE, ['id' => $userplan->id]); 4857 } 4858 } 4859 4860 /** 4861 * Manually grade a user competency. 4862 * 4863 * @param int $userid 4864 * @param int $competencyid 4865 * @param int $grade 4866 * @param string $note A note to attach to the evidence 4867 * @return array of \core_competency\user_competency 4868 */ 4869 public static function grade_competency($userid, $competencyid, $grade, $note = null) { 4870 global $USER; 4871 static::require_enabled(); 4872 4873 $uc = static::get_user_competency($userid, $competencyid); 4874 $context = $uc->get_context(); 4875 if (!user_competency::can_grade_user($uc->get('userid'))) { 4876 throw new required_capability_exception($context, 'moodle/competency:competencygrade', 'nopermissions', ''); 4877 } 4878 4879 // Throws exception if competency not in plan. 4880 $competency = $uc->get_competency(); 4881 $competencycontext = $competency->get_context(); 4882 if (!has_any_capability(array('moodle/competency:competencyview', 'moodle/competency:competencymanage'), 4883 $competencycontext)) { 4884 throw new required_capability_exception($competencycontext, 'moodle/competency:competencyview', 'nopermissions', ''); 4885 } 4886 4887 $action = evidence::ACTION_OVERRIDE; 4888 $desckey = 'evidence_manualoverride'; 4889 4890 $result = self::add_evidence($uc->get('userid'), 4891 $competency, 4892 $context->id, 4893 $action, 4894 $desckey, 4895 'core_competency', 4896 null, 4897 false, 4898 null, 4899 $grade, 4900 $USER->id, 4901 $note); 4902 if ($result) { 4903 $uc->read(); 4904 $event = \core\event\competency_user_competency_rated::create_from_user_competency($uc); 4905 $event->trigger(); 4906 } 4907 return $result; 4908 } 4909 4910 /** 4911 * Manually grade a user competency from the plans page. 4912 * 4913 * @param mixed $planorid 4914 * @param int $competencyid 4915 * @param int $grade 4916 * @param string $note A note to attach to the evidence 4917 * @return array of \core_competency\user_competency 4918 */ 4919 public static function grade_competency_in_plan($planorid, $competencyid, $grade, $note = null) { 4920 global $USER; 4921 static::require_enabled(); 4922 4923 $plan = $planorid; 4924 if (!is_object($planorid)) { 4925 $plan = new plan($planorid); 4926 } 4927 4928 $context = $plan->get_context(); 4929 if (!user_competency::can_grade_user($plan->get('userid'))) { 4930 throw new required_capability_exception($context, 'moodle/competency:competencygrade', 'nopermissions', ''); 4931 } 4932 4933 // Throws exception if competency not in plan. 4934 $competency = $plan->get_competency($competencyid); 4935 $competencycontext = $competency->get_context(); 4936 if (!has_any_capability(array('moodle/competency:competencyview', 'moodle/competency:competencymanage'), 4937 $competencycontext)) { 4938 throw new required_capability_exception($competencycontext, 'moodle/competency:competencyview', 'nopermissions', ''); 4939 } 4940 4941 $action = evidence::ACTION_OVERRIDE; 4942 $desckey = 'evidence_manualoverrideinplan'; 4943 4944 $result = self::add_evidence($plan->get('userid'), 4945 $competency, 4946 $context->id, 4947 $action, 4948 $desckey, 4949 'core_competency', 4950 $plan->get('name'), 4951 false, 4952 null, 4953 $grade, 4954 $USER->id, 4955 $note); 4956 if ($result) { 4957 $uc = static::get_user_competency($plan->get('userid'), $competency->get('id')); 4958 $event = \core\event\competency_user_competency_rated_in_plan::create_from_user_competency($uc, $plan->get('id')); 4959 $event->trigger(); 4960 } 4961 return $result; 4962 } 4963 4964 /** 4965 * Manually grade a user course competency from the course page. 4966 * 4967 * This may push the rating to the user competency 4968 * if the course is configured this way. 4969 * 4970 * @param mixed $courseorid 4971 * @param int $userid 4972 * @param int $competencyid 4973 * @param int $grade 4974 * @param string $note A note to attach to the evidence 4975 * @return array of \core_competency\user_competency 4976 */ 4977 public static function grade_competency_in_course($courseorid, $userid, $competencyid, $grade, $note = null) { 4978 global $USER, $DB; 4979 static::require_enabled(); 4980 4981 $course = $courseorid; 4982 if (!is_object($courseorid)) { 4983 $course = $DB->get_record('course', array('id' => $courseorid)); 4984 } 4985 $context = context_course::instance($course->id); 4986 4987 // Check that we can view the user competency details in the course. 4988 if (!user_competency::can_read_user_in_course($userid, $course->id)) { 4989 throw new required_capability_exception($context, 'moodle/competency:usercompetencyview', 'nopermissions', ''); 4990 } 4991 4992 // Validate the permission to grade. 4993 if (!user_competency::can_grade_user_in_course($userid, $course->id)) { 4994 throw new required_capability_exception($context, 'moodle/competency:competencygrade', 'nopermissions', ''); 4995 } 4996 4997 // Check that competency is in course and visible to the current user. 4998 $competency = course_competency::get_competency($course->id, $competencyid); 4999 $competencycontext = $competency->get_context(); 5000 if (!has_any_capability(array('moodle/competency:competencyview', 'moodle/competency:competencymanage'), 5001 $competencycontext)) { 5002 throw new required_capability_exception($competencycontext, 'moodle/competency:competencyview', 'nopermissions', ''); 5003 } 5004 5005 // Check that the user is enrolled in the course, and is "gradable". 5006 if (!is_enrolled($context, $userid, 'moodle/competency:coursecompetencygradable')) { 5007 throw new coding_exception('The competency may not be rated at this time.'); 5008 } 5009 5010 $action = evidence::ACTION_OVERRIDE; 5011 $desckey = 'evidence_manualoverrideincourse'; 5012 5013 $result = self::add_evidence($userid, 5014 $competency, 5015 $context->id, 5016 $action, 5017 $desckey, 5018 'core_competency', 5019 $context->get_context_name(), 5020 false, 5021 null, 5022 $grade, 5023 $USER->id, 5024 $note); 5025 if ($result) { 5026 $all = user_competency_course::get_multiple($userid, $course->id, array($competency->get('id'))); 5027 $uc = reset($all); 5028 $event = \core\event\competency_user_competency_rated_in_course::create_from_user_competency_course($uc); 5029 $event->trigger(); 5030 } 5031 return $result; 5032 } 5033 5034 /** 5035 * Count the plans in the template, filtered by status. 5036 * 5037 * Requires moodle/competency:templateview capability at the system context. 5038 * 5039 * @param mixed $templateorid The id or the template. 5040 * @param int $status One of the plan status constants (or 0 for all plans). 5041 * @return int 5042 */ 5043 public static function count_plans_for_template($templateorid, $status = 0) { 5044 static::require_enabled(); 5045 $template = $templateorid; 5046 if (!is_object($template)) { 5047 $template = new template($template); 5048 } 5049 5050 // First we do a permissions check. 5051 if (!$template->can_read()) { 5052 throw new required_capability_exception($template->get_context(), 'moodle/competency:templateview', 5053 'nopermissions', ''); 5054 } 5055 5056 return plan::count_records_for_template($template->get('id'), $status); 5057 } 5058 5059 /** 5060 * Count the user-completency-plans in the template, optionally filtered by proficiency. 5061 * 5062 * Requires moodle/competency:templateview capability at the system context. 5063 * 5064 * @param mixed $templateorid The id or the template. 5065 * @param mixed $proficiency If true, filter by proficiency, if false filter by not proficient, if null - no filter. 5066 * @return int 5067 */ 5068 public static function count_user_competency_plans_for_template($templateorid, $proficiency = null) { 5069 static::require_enabled(); 5070 $template = $templateorid; 5071 if (!is_object($template)) { 5072 $template = new template($template); 5073 } 5074 5075 // First we do a permissions check. 5076 if (!$template->can_read()) { 5077 throw new required_capability_exception($template->get_context(), 'moodle/competency:templateview', 5078 'nopermissions', ''); 5079 } 5080 5081 return user_competency_plan::count_records_for_template($template->get('id'), $proficiency); 5082 } 5083 5084 /** 5085 * List the plans in the template, filtered by status. 5086 * 5087 * Requires moodle/competency:templateview capability at the system context. 5088 * 5089 * @param mixed $templateorid The id or the template. 5090 * @param int $status One of the plan status constants (or 0 for all plans). 5091 * @param int $skip The number of records to skip 5092 * @param int $limit The max number of records to return 5093 * @return plan[] 5094 */ 5095 public static function list_plans_for_template($templateorid, $status = 0, $skip = 0, $limit = 100) { 5096 $template = $templateorid; 5097 if (!is_object($template)) { 5098 $template = new template($template); 5099 } 5100 5101 // First we do a permissions check. 5102 if (!$template->can_read()) { 5103 throw new required_capability_exception($template->get_context(), 'moodle/competency:templateview', 5104 'nopermissions', ''); 5105 } 5106 5107 return plan::get_records_for_template($template->get('id'), $status, $skip, $limit); 5108 } 5109 5110 /** 5111 * Get the most often not completed competency for this course. 5112 * 5113 * Requires moodle/competency:coursecompetencyview capability at the course context. 5114 * 5115 * @param int $courseid The course id 5116 * @param int $skip The number of records to skip 5117 * @param int $limit The max number of records to return 5118 * @return competency[] 5119 */ 5120 public static function get_least_proficient_competencies_for_course($courseid, $skip = 0, $limit = 100) { 5121 static::require_enabled(); 5122 $coursecontext = context_course::instance($courseid); 5123 5124 if (!has_any_capability(array('moodle/competency:coursecompetencyview', 'moodle/competency:coursecompetencymanage'), 5125 $coursecontext)) { 5126 throw new required_capability_exception($coursecontext, 'moodle/competency:coursecompetencyview', 'nopermissions', ''); 5127 } 5128 5129 return user_competency_course::get_least_proficient_competencies_for_course($courseid, $skip, $limit); 5130 } 5131 5132 /** 5133 * Get the most often not completed competency for this template. 5134 * 5135 * Requires moodle/competency:templateview capability at the system context. 5136 * 5137 * @param mixed $templateorid The id or the template. 5138 * @param int $skip The number of records to skip 5139 * @param int $limit The max number of records to return 5140 * @return competency[] 5141 */ 5142 public static function get_least_proficient_competencies_for_template($templateorid, $skip = 0, $limit = 100) { 5143 static::require_enabled(); 5144 $template = $templateorid; 5145 if (!is_object($template)) { 5146 $template = new template($template); 5147 } 5148 5149 // First we do a permissions check. 5150 if (!$template->can_read()) { 5151 throw new required_capability_exception($template->get_context(), 'moodle/competency:templateview', 5152 'nopermissions', ''); 5153 } 5154 5155 return user_competency_plan::get_least_proficient_competencies_for_template($template->get('id'), $skip, $limit); 5156 } 5157 5158 /** 5159 * Template event viewed. 5160 * 5161 * Requires moodle/competency:templateview capability at the system context. 5162 * 5163 * @param mixed $templateorid The id or the template. 5164 * @return boolean 5165 */ 5166 public static function template_viewed($templateorid) { 5167 static::require_enabled(); 5168 $template = $templateorid; 5169 if (!is_object($template)) { 5170 $template = new template($template); 5171 } 5172 5173 // First we do a permissions check. 5174 if (!$template->can_read()) { 5175 throw new required_capability_exception($template->get_context(), 'moodle/competency:templateview', 5176 'nopermissions', ''); 5177 } 5178 5179 // Trigger a template viewed event. 5180 \core\event\competency_template_viewed::create_from_template($template)->trigger(); 5181 5182 return true; 5183 } 5184 5185 /** 5186 * Get the competency settings for a course. 5187 * 5188 * Requires moodle/competency:coursecompetencyview capability at the course context. 5189 * 5190 * @param int $courseid The course id 5191 * @return course_competency_settings 5192 */ 5193 public static function read_course_competency_settings($courseid) { 5194 static::require_enabled(); 5195 5196 // First we do a permissions check. 5197 if (!course_competency_settings::can_read($courseid)) { 5198 $context = context_course::instance($courseid); 5199 throw new required_capability_exception($context, 'moodle/competency:coursecompetencyview', 'nopermissions', ''); 5200 } 5201 5202 return course_competency_settings::get_by_courseid($courseid); 5203 } 5204 5205 /** 5206 * Update the competency settings for a course. 5207 * 5208 * Requires moodle/competency:coursecompetencyconfigure capability at the course context. 5209 * 5210 * @param int $courseid The course id 5211 * @param stdClass $settings List of settings. The only valid setting ATM is pushratginstouserplans (boolean). 5212 * @return bool 5213 */ 5214 public static function update_course_competency_settings($courseid, $settings) { 5215 static::require_enabled(); 5216 5217 $settings = (object) $settings; 5218 5219 // Get all the valid settings. 5220 $pushratingstouserplans = isset($settings->pushratingstouserplans) ? $settings->pushratingstouserplans : false; 5221 5222 // First we do a permissions check. 5223 if (!course_competency_settings::can_manage_course($courseid)) { 5224 $context = context_course::instance($courseid); 5225 throw new required_capability_exception($context, 'moodle/competency:coursecompetencyconfigure', 'nopermissions', ''); 5226 } 5227 5228 $exists = course_competency_settings::get_record(array('courseid' => $courseid)); 5229 5230 // Now update or insert. 5231 if ($exists) { 5232 $settings = $exists; 5233 $settings->set('pushratingstouserplans', $pushratingstouserplans); 5234 return $settings->update(); 5235 } else { 5236 $data = (object) array('courseid' => $courseid, 'pushratingstouserplans' => $pushratingstouserplans); 5237 $settings = new course_competency_settings(0, $data); 5238 $result = $settings->create(); 5239 return !empty($result); 5240 } 5241 } 5242 5243 5244 /** 5245 * Function used to return a list of users where the given user has a particular capability. 5246 * 5247 * This is used e.g. to find all the users where someone is able to manage their learning plans, 5248 * it also would be useful for mentees etc. 5249 * 5250 * @param string $capability - The capability string we are filtering for. If '' is passed, 5251 * an always matching filter is returned. 5252 * @param int $userid - The user id we are using for the access checks. Defaults to current user. 5253 * @param int $type - The type of named params to return (passed to $DB->get_in_or_equal). 5254 * @param string $prefix - The type prefix for the db table (passed to $DB->get_in_or_equal). 5255 * @return list($sql, $params) Same as $DB->get_in_or_equal(). 5256 * @todo MDL-52243 Move this function to lib/accesslib.php 5257 */ 5258 public static function filter_users_with_capability_on_user_context_sql($capability, $userid = 0, $type = SQL_PARAMS_QM, 5259 $prefix='param') { 5260 5261 global $USER, $DB; 5262 $allresultsfilter = array('> 0', array()); 5263 $noresultsfilter = array('= -1', array()); 5264 5265 if (empty($capability)) { 5266 return $allresultsfilter; 5267 } 5268 5269 if (!$capinfo = get_capability_info($capability)) { 5270 throw new coding_exception('Capability does not exist: ' . $capability); 5271 } 5272 5273 if (empty($userid)) { 5274 $userid = $USER->id; 5275 } 5276 5277 // Make sure the guest account and not-logged-in users never get any risky caps no matter what the actual settings are. 5278 if (($capinfo->captype === 'write') or ($capinfo->riskbitmask & (RISK_XSS | RISK_CONFIG | RISK_DATALOSS))) { 5279 if (isguestuser($userid) or $userid == 0) { 5280 return $noresultsfilter; 5281 } 5282 } 5283 5284 if (is_siteadmin($userid)) { 5285 // No filtering for site admins. 5286 return $allresultsfilter; 5287 } 5288 5289 // Check capability on system level. 5290 $syscontext = context_system::instance(); 5291 $hassystem = has_capability($capability, $syscontext, $userid); 5292 5293 $access = get_user_roles_sitewide_accessdata($userid); 5294 // Build up a list of level 2 contexts (candidates to be user context). 5295 $filtercontexts = array(); 5296 // Build list of roles to check overrides. 5297 $roles = array(); 5298 5299 foreach ($access['ra'] as $path => $role) { 5300 $parts = explode('/', $path); 5301 if (count($parts) == 3) { 5302 $filtercontexts[$parts[2]] = $parts[2]; 5303 } else if (count($parts) > 3) { 5304 // We know this is not a user context because there is another path with more than 2 levels. 5305 unset($filtercontexts[$parts[2]]); 5306 } 5307 $roles = array_merge($roles, $role); 5308 } 5309 5310 // Add all contexts in which a role may be overidden. 5311 $rdefs = get_role_definitions($roles); 5312 foreach ($rdefs as $roledef) { 5313 foreach ($roledef as $path => $caps) { 5314 if (!isset($caps[$capability])) { 5315 // The capability is not mentioned, we can ignore. 5316 continue; 5317 } 5318 $parts = explode('/', $path); 5319 if (count($parts) === 3) { 5320 // Only get potential user contexts, they only ever have 2 slashes /parentId/Id. 5321 $filtercontexts[$parts[2]] = $parts[2]; 5322 } 5323 } 5324 } 5325 5326 // No interesting contexts - return all or no results. 5327 if (empty($filtercontexts)) { 5328 if ($hassystem) { 5329 return $allresultsfilter; 5330 } else { 5331 return $noresultsfilter; 5332 } 5333 } 5334 // Fetch all interesting contexts for further examination. 5335 list($insql, $params) = $DB->get_in_or_equal($filtercontexts, SQL_PARAMS_NAMED); 5336 $params['level'] = CONTEXT_USER; 5337 $fields = context_helper::get_preload_record_columns_sql('ctx'); 5338 $interestingcontexts = $DB->get_recordset_sql('SELECT ' . $fields . ' 5339 FROM {context} ctx 5340 WHERE ctx.contextlevel = :level 5341 AND ctx.id ' . $insql . ' 5342 ORDER BY ctx.id', $params); 5343 if ($hassystem) { 5344 // If allowed at system, search for exceptions prohibiting the capability at user context. 5345 $excludeusers = array(); 5346 foreach ($interestingcontexts as $contextrecord) { 5347 $candidateuserid = $contextrecord->ctxinstance; 5348 context_helper::preload_from_record($contextrecord); 5349 $usercontext = context_user::instance($candidateuserid); 5350 // Has capability should use the data already preloaded. 5351 if (!has_capability($capability, $usercontext, $userid)) { 5352 $excludeusers[$candidateuserid] = $candidateuserid; 5353 } 5354 } 5355 5356 // Construct SQL excluding users with this role assigned for this user. 5357 if (empty($excludeusers)) { 5358 $interestingcontexts->close(); 5359 return $allresultsfilter; 5360 } 5361 list($sql, $params) = $DB->get_in_or_equal($excludeusers, $type, $prefix, false); 5362 } else { 5363 // If not allowed at system, search for exceptions allowing the capability at user context. 5364 $allowusers = array(); 5365 foreach ($interestingcontexts as $contextrecord) { 5366 $candidateuserid = $contextrecord->ctxinstance; 5367 context_helper::preload_from_record($contextrecord); 5368 $usercontext = context_user::instance($candidateuserid); 5369 // Has capability should use the data already preloaded. 5370 if (has_capability($capability, $usercontext, $userid)) { 5371 $allowusers[$candidateuserid] = $candidateuserid; 5372 } 5373 } 5374 5375 // Construct SQL excluding users with this role assigned for this user. 5376 if (empty($allowusers)) { 5377 $interestingcontexts->close(); 5378 return $noresultsfilter; 5379 } 5380 list($sql, $params) = $DB->get_in_or_equal($allowusers, $type, $prefix); 5381 } 5382 $interestingcontexts->close(); 5383 5384 // Return the goods!. 5385 return array($sql, $params); 5386 } 5387 5388 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
