Search moodle.org's
Developer Documentation
Developer Documentation
- Bug fixes for general core bugs in 3.10.x will end 8 November 2021 (12 months).
- Bug fixes for security issues in 3.10.x will end 9 May 2022 (18 months).
- PHP version: minimum PHP 7.2.0 Note: minimum PHP version has increased since Moodle 3.8. PHP 7.3.x and 7.4.x are supported too.
/lib/classes/event/ -> base.php (source)
Differences Between: [Versions 310 and 311] [Versions 310 and 400] [Versions 310 and 401] [Versions 310 and 402] [Versions 310 and 403]
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 namespace core\event; 18 19 defined('MOODLE_INTERNAL') || die(); 20 21 /** 22 * Base event class. 23 * 24 * @package core 25 * @copyright 2013 Petr Skoda {@link http://skodak.org} 26 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 27 */ 28 29 /** 30 * All other event classes must extend this class. 31 * 32 * @package core 33 * @since Moodle 2.6 34 * @copyright 2013 Petr Skoda {@link http://skodak.org} 35 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 36 * 37 * @property-read string $eventname Name of the event (=== class name with leading \) 38 * @property-read string $component Full frankenstyle component name 39 * @property-read string $action what happened 40 * @property-read string $target what/who was target of the action 41 * @property-read string $objecttable name of database table where is object record stored 42 * @property-read int $objectid optional id of the object 43 * @property-read string $crud letter indicating event type 44 * @property-read int $edulevel log level (one of the constants LEVEL_) 45 * @property-read int $contextid 46 * @property-read int $contextlevel 47 * @property-read int $contextinstanceid 48 * @property-read int $userid who did this? 49 * @property-read int $courseid the courseid of the event context, 0 for contexts above course 50 * @property-read int $relateduserid 51 * @property-read int $anonymous 1 means event should not be visible in reports, 0 means normal event, 52 * create() argument may be also true/false. 53 * @property-read mixed $other array or scalar, can not contain objects 54 * @property-read int $timecreated 55 */ 56 abstract class base implements \IteratorAggregate { 57 58 /** 59 * Other level. 60 */ 61 const LEVEL_OTHER = 0; 62 63 /** 64 * Teaching level. 65 * 66 * Any event that is performed by someone (typically a teacher) and has a teaching value, 67 * anything that is affecting the learning experience/environment of the students. 68 */ 69 const LEVEL_TEACHING = 1; 70 71 /** 72 * Participating level. 73 * 74 * Any event that is performed by a user, and is related (or could be related) to his learning experience. 75 */ 76 const LEVEL_PARTICIPATING = 2; 77 78 /** 79 * The value used when an id can not be mapped during a restore. 80 */ 81 const NOT_MAPPED = -31337; 82 83 /** 84 * The value used when an id can not be found during a restore. 85 */ 86 const NOT_FOUND = -31338; 87 88 /** 89 * User id to use when the user is not logged in. 90 */ 91 const USER_NOTLOGGEDIN = 0; 92 93 /** 94 * User id to use when actor is not an actual user but system, cli or cron. 95 */ 96 const USER_OTHER = -1; 97 98 /** @var array event data */ 99 protected $data; 100 101 /** @var array the format is standardised by logging API */ 102 protected $logextra; 103 104 /** @var \context of this event */ 105 protected $context; 106 107 /** 108 * @var bool indicates if event was already triggered, 109 * this prevents second attempt to trigger event. 110 */ 111 private $triggered; 112 113 /** 114 * @var bool indicates if event was already dispatched, 115 * this prevents direct calling of manager::dispatch($event). 116 */ 117 private $dispatched; 118 119 /** 120 * @var bool indicates if event was restored from storage, 121 * this prevents triggering of restored events. 122 */ 123 private $restored; 124 125 /** @var array list of event properties */ 126 private static $fields = array( 127 'eventname', 'component', 'action', 'target', 'objecttable', 'objectid', 'crud', 'edulevel', 'contextid', 128 'contextlevel', 'contextinstanceid', 'userid', 'courseid', 'relateduserid', 'anonymous', 'other', 129 'timecreated'); 130 131 /** @var array simple record cache */ 132 private $recordsnapshots = array(); 133 134 /** 135 * Private constructor, use create() or restore() methods instead. 136 */ 137 private final function __construct() { 138 $this->data = array_fill_keys(self::$fields, null); 139 140 // Define some basic details. 141 $classname = get_called_class(); 142 $parts = explode('\\', $classname); 143 if (count($parts) !== 3 or $parts[1] !== 'event') { 144 throw new \coding_exception("Invalid event class name '$classname', it must be defined in component\\event\\ 145 namespace"); 146 } 147 $this->data['eventname'] = '\\'.$classname; 148 $this->data['component'] = $parts[0]; 149 150 $pos = strrpos($parts[2], '_'); 151 if ($pos === false) { 152 throw new \coding_exception("Invalid event class name '$classname', there must be at least one underscore separating 153 object and action words"); 154 } 155 $this->data['target'] = substr($parts[2], 0, $pos); 156 $this->data['action'] = substr($parts[2], $pos + 1); 157 } 158 159 /** 160 * Create new event. 161 * 162 * The optional data keys as: 163 * 1/ objectid - the id of the object specified in class name 164 * 2/ context - the context of this event 165 * 3/ other - the other data describing the event, can not contain objects 166 * 4/ relateduserid - the id of user which is somehow related to this event 167 * 168 * @param array $data 169 * @return \core\event\base returns instance of new event 170 * 171 * @throws \coding_exception 172 */ 173 public static final function create(array $data = null) { 174 global $USER, $CFG; 175 176 $data = (array)$data; 177 178 /** @var \core\event\base $event */ 179 $event = new static(); 180 $event->triggered = false; 181 $event->restored = false; 182 $event->dispatched = false; 183 184 // By default all events are visible in logs. 185 $event->data['anonymous'] = 0; 186 187 // Set static event data specific for child class. 188 $event->init(); 189 190 if (isset($event->data['level'])) { 191 if (!isset($event->data['edulevel'])) { 192 debugging('level property is deprecated, use edulevel property instead', DEBUG_DEVELOPER); 193 $event->data['edulevel'] = $event->data['level']; 194 } 195 unset($event->data['level']); 196 } 197 198 // Set automatic data. 199 $event->data['timecreated'] = time(); 200 201 // Set optional data or use defaults. 202 $event->data['objectid'] = isset($data['objectid']) ? $data['objectid'] : null; 203 $event->data['courseid'] = isset($data['courseid']) ? $data['courseid'] : null; 204 $event->data['userid'] = isset($data['userid']) ? $data['userid'] : $USER->id; 205 $event->data['other'] = isset($data['other']) ? $data['other'] : null; 206 $event->data['relateduserid'] = isset($data['relateduserid']) ? $data['relateduserid'] : null; 207 if (isset($data['anonymous'])) { 208 $event->data['anonymous'] = $data['anonymous']; 209 } 210 $event->data['anonymous'] = (int)(bool)$event->data['anonymous']; 211 212 if (isset($event->context)) { 213 if (isset($data['context'])) { 214 debugging('Context was already set in init() method, ignoring context parameter', DEBUG_DEVELOPER); 215 } 216 217 } else if (!empty($data['context'])) { 218 $event->context = $data['context']; 219 220 } else if (!empty($data['contextid'])) { 221 $event->context = \context::instance_by_id($data['contextid'], MUST_EXIST); 222 223 } else { 224 throw new \coding_exception('context (or contextid) is a required event property, system context may be hardcoded in init() method.'); 225 } 226 227 $event->data['contextid'] = $event->context->id; 228 $event->data['contextlevel'] = $event->context->contextlevel; 229 $event->data['contextinstanceid'] = $event->context->instanceid; 230 231 if (!isset($event->data['courseid'])) { 232 if ($coursecontext = $event->context->get_course_context(false)) { 233 $event->data['courseid'] = $coursecontext->instanceid; 234 } else { 235 $event->data['courseid'] = 0; 236 } 237 } 238 239 if (!array_key_exists('relateduserid', $data) and $event->context->contextlevel == CONTEXT_USER) { 240 $event->data['relateduserid'] = $event->context->instanceid; 241 } 242 243 // Warn developers if they do something wrong. 244 if ($CFG->debugdeveloper) { 245 static $automatickeys = array('eventname', 'component', 'action', 'target', 'contextlevel', 'contextinstanceid', 'timecreated'); 246 static $initkeys = array('crud', 'level', 'objecttable', 'edulevel'); 247 248 foreach ($data as $key => $ignored) { 249 if ($key === 'context') { 250 continue; 251 252 } else if (in_array($key, $automatickeys)) { 253 debugging("Data key '$key' is not allowed in \\core\\event\\base::create() method, it is set automatically", DEBUG_DEVELOPER); 254 255 } else if (in_array($key, $initkeys)) { 256 debugging("Data key '$key' is not allowed in \\core\\event\\base::create() method, you need to set it in init() method", DEBUG_DEVELOPER); 257 258 } else if (!in_array($key, self::$fields)) { 259 debugging("Data key '$key' does not exist in \\core\\event\\base"); 260 } 261 } 262 $expectedcourseid = 0; 263 if ($coursecontext = $event->context->get_course_context(false)) { 264 $expectedcourseid = $coursecontext->instanceid; 265 } 266 if ($expectedcourseid != $event->data['courseid']) { 267 debugging("Inconsistent courseid - context combination detected.", DEBUG_DEVELOPER); 268 } 269 } 270 271 // Let developers validate their custom data (such as $this->data['other'], contextlevel, etc.). 272 $event->validate_data(); 273 274 return $event; 275 } 276 277 /** 278 * Override in subclass. 279 * 280 * Set all required data properties: 281 * 1/ crud - letter [crud] 282 * 2/ edulevel - using a constant self::LEVEL_*. 283 * 3/ objecttable - name of database table if objectid specified 284 * 285 * Optionally it can set: 286 * a/ fixed system context 287 * 288 * @return void 289 */ 290 protected abstract function init(); 291 292 /** 293 * Let developers validate their custom data (such as $this->data['other'], contextlevel, etc.). 294 * 295 * Throw \coding_exception or debugging() notice in case of any problems. 296 */ 297 protected function validate_data() { 298 // Override if you want to validate event properties when 299 // creating new events. 300 } 301 302 /** 303 * Returns localised general event name. 304 * 305 * Override in subclass, we can not make it static and abstract at the same time. 306 * 307 * @return string 308 */ 309 public static function get_name() { 310 // Override in subclass with real lang string. 311 $parts = explode('\\', get_called_class()); 312 if (count($parts) !== 3) { 313 return get_string('unknownevent', 'error'); 314 } 315 return $parts[0].': '.str_replace('_', ' ', $parts[2]); 316 } 317 318 /** 319 * Returns the event name complete with metadata information. 320 * 321 * This includes information about whether the event has been deprecated so should not be used in all situations - 322 * for example within reports themselves. 323 * 324 * If overriding this function, please ensure that you call the parent version too. 325 * 326 * @return string 327 */ 328 public static function get_name_with_info() { 329 $return = static::get_name(); 330 331 if (static::is_deprecated()) { 332 $return = get_string('deprecatedeventname', 'core', $return); 333 } 334 335 return $return; 336 } 337 338 /** 339 * Returns non-localised event description with id's for admin use only. 340 * 341 * @return string 342 */ 343 public function get_description() { 344 return null; 345 } 346 347 /** 348 * This method was originally intended for granular 349 * access control on the event level, unfortunately 350 * the proper implementation would be too expensive 351 * in many cases. 352 * 353 * @deprecated since 2.7 354 * 355 * @param int|\stdClass $user_or_id ID of the user. 356 * @return bool True if the user can view the event, false otherwise. 357 */ 358 public function can_view($user_or_id = null) { 359 debugging('can_view() method is deprecated, use anonymous flag instead if necessary.', DEBUG_DEVELOPER); 360 return is_siteadmin($user_or_id); 361 } 362 363 /** 364 * Restore event from existing historic data. 365 * 366 * @param array $data 367 * @param array $logextra the format is standardised by logging API 368 * @return bool|\core\event\base 369 */ 370 public static final function restore(array $data, array $logextra) { 371 $classname = $data['eventname']; 372 $component = $data['component']; 373 $action = $data['action']; 374 $target = $data['target']; 375 376 // Security: make 100% sure this really is an event class. 377 if ($classname !== "\\{$component}\\event\\{$target}_{$action}") { 378 return false; 379 } 380 381 if (!class_exists($classname)) { 382 return self::restore_unknown($data, $logextra); 383 } 384 $event = new $classname(); 385 if (!($event instanceof \core\event\base)) { 386 return false; 387 } 388 389 $event->init(); // Init method of events could be setting custom properties. 390 $event->restored = true; 391 $event->triggered = true; 392 $event->dispatched = true; 393 $event->logextra = $logextra; 394 395 foreach (self::$fields as $key) { 396 if (!array_key_exists($key, $data)) { 397 debugging("Event restore data must contain key $key"); 398 $data[$key] = null; 399 } 400 } 401 if (count($data) != count(self::$fields)) { 402 foreach ($data as $key => $value) { 403 if (!in_array($key, self::$fields)) { 404 debugging("Event restore data cannot contain key $key"); 405 unset($data[$key]); 406 } 407 } 408 } 409 $event->data = $data; 410 411 return $event; 412 } 413 414 /** 415 * Restore unknown event. 416 * 417 * @param array $data 418 * @param array $logextra 419 * @return unknown_logged 420 */ 421 protected static final function restore_unknown(array $data, array $logextra) { 422 $classname = '\core\event\unknown_logged'; 423 424 /** @var unknown_logged $event */ 425 $event = new $classname(); 426 $event->restored = true; 427 $event->triggered = true; 428 $event->dispatched = true; 429 $event->data = $data; 430 $event->logextra = $logextra; 431 432 return $event; 433 } 434 435 /** 436 * Create fake event from legacy log data. 437 * 438 * @param \stdClass $legacy 439 * @return base 440 */ 441 public static final function restore_legacy($legacy) { 442 $classname = get_called_class(); 443 /** @var base $event */ 444 $event = new $classname(); 445 $event->restored = true; 446 $event->triggered = true; 447 $event->dispatched = true; 448 449 $context = false; 450 $component = 'legacy'; 451 if ($legacy->cmid) { 452 $context = \context_module::instance($legacy->cmid, IGNORE_MISSING); 453 $component = 'mod_'.$legacy->module; 454 } else if ($legacy->course) { 455 $context = \context_course::instance($legacy->course, IGNORE_MISSING); 456 } 457 if (!$context) { 458 $context = \context_system::instance(); 459 } 460 461 $event->data = array(); 462 463 $event->data['eventname'] = $legacy->module.'_'.$legacy->action; 464 $event->data['component'] = $component; 465 $event->data['action'] = $legacy->action; 466 $event->data['target'] = null; 467 $event->data['objecttable'] = null; 468 $event->data['objectid'] = null; 469 if (strpos($legacy->action, 'view') !== false) { 470 $event->data['crud'] = 'r'; 471 } else if (strpos($legacy->action, 'print') !== false) { 472 $event->data['crud'] = 'r'; 473 } else if (strpos($legacy->action, 'update') !== false) { 474 $event->data['crud'] = 'u'; 475 } else if (strpos($legacy->action, 'hide') !== false) { 476 $event->data['crud'] = 'u'; 477 } else if (strpos($legacy->action, 'move') !== false) { 478 $event->data['crud'] = 'u'; 479 } else if (strpos($legacy->action, 'write') !== false) { 480 $event->data['crud'] = 'u'; 481 } else if (strpos($legacy->action, 'tag') !== false) { 482 $event->data['crud'] = 'u'; 483 } else if (strpos($legacy->action, 'remove') !== false) { 484 $event->data['crud'] = 'u'; 485 } else if (strpos($legacy->action, 'delete') !== false) { 486 $event->data['crud'] = 'p'; 487 } else if (strpos($legacy->action, 'create') !== false) { 488 $event->data['crud'] = 'c'; 489 } else if (strpos($legacy->action, 'post') !== false) { 490 $event->data['crud'] = 'c'; 491 } else if (strpos($legacy->action, 'add') !== false) { 492 $event->data['crud'] = 'c'; 493 } else { 494 // End of guessing... 495 $event->data['crud'] = 'r'; 496 } 497 $event->data['edulevel'] = $event::LEVEL_OTHER; 498 $event->data['contextid'] = $context->id; 499 $event->data['contextlevel'] = $context->contextlevel; 500 $event->data['contextinstanceid'] = $context->instanceid; 501 $event->data['userid'] = ($legacy->userid ? $legacy->userid : null); 502 $event->data['courseid'] = ($legacy->course ? $legacy->course : null); 503 $event->data['relateduserid'] = ($legacy->userid ? $legacy->userid : null); 504 $event->data['timecreated'] = $legacy->time; 505 506 $event->logextra = array(); 507 if ($legacy->ip) { 508 $event->logextra['origin'] = 'web'; 509 $event->logextra['ip'] = $legacy->ip; 510 } else { 511 $event->logextra['origin'] = 'cli'; 512 $event->logextra['ip'] = null; 513 } 514 $event->logextra['realuserid'] = null; 515 516 $event->data['other'] = (array)$legacy; 517 518 return $event; 519 } 520 521 /** 522 * This is used when restoring course logs where it is required that we 523 * map the objectid to it's new value in the new course. 524 * 525 * Does nothing in the base class except display a debugging message warning 526 * the user that the event does not contain the required functionality to 527 * map this information. For events that do not store an objectid this won't 528 * be called, so no debugging message will be displayed. 529 * 530 * Example of usage: 531 * 532 * return array('db' => 'assign_submissions', 'restore' => 'submission'); 533 * 534 * If the objectid can not be mapped during restore set the value to \core\event\base::NOT_MAPPED, example - 535 * 536 * return array('db' => 'some_table', 'restore' => \core\event\base::NOT_MAPPED); 537 * 538 * Note - it isn't necessary to specify the 'db' and 'restore' values in this case, so you can also use - 539 * 540 * return \core\event\base::NOT_MAPPED; 541 * 542 * The 'db' key refers to the database table and the 'restore' key refers to 543 * the name of the restore element the objectid is associated with. In many 544 * cases these will be the same. 545 * 546 * @return string the name of the restore mapping the objectid links to 547 */ 548 public static function get_objectid_mapping() { 549 debugging('In order to restore course logs accurately the event "' . get_called_class() . '" must define the 550 function get_objectid_mapping().', DEBUG_DEVELOPER); 551 552 return false; 553 } 554 555 /** 556 * This is used when restoring course logs where it is required that we 557 * map the information in 'other' to it's new value in the new course. 558 * 559 * Does nothing in the base class except display a debugging message warning 560 * the user that the event does not contain the required functionality to 561 * map this information. For events that do not store any other information this 562 * won't be called, so no debugging message will be displayed. 563 * 564 * Example of usage: 565 * 566 * $othermapped = array(); 567 * $othermapped['discussionid'] = array('db' => 'forum_discussions', 'restore' => 'forum_discussion'); 568 * $othermapped['forumid'] = array('db' => 'forum', 'restore' => 'forum'); 569 * return $othermapped; 570 * 571 * If an id can not be mapped during restore we set it to \core\event\base::NOT_MAPPED, example - 572 * 573 * $othermapped = array(); 574 * $othermapped['someid'] = array('db' => 'some_table', 'restore' => \core\event\base::NOT_MAPPED); 575 * return $othermapped; 576 * 577 * Note - it isn't necessary to specify the 'db' and 'restore' values in this case, so you can also use - 578 * 579 * $othermapped = array(); 580 * $othermapped['someid'] = \core\event\base::NOT_MAPPED; 581 * return $othermapped; 582 * 583 * The 'db' key refers to the database table and the 'restore' key refers to 584 * the name of the restore element the other value is associated with. In many 585 * cases these will be the same. 586 * 587 * @return array an array of other values and their corresponding mapping 588 */ 589 public static function get_other_mapping() { 590 debugging('In order to restore course logs accurately the event "' . get_called_class() . '" must define the 591 function get_other_mapping().', DEBUG_DEVELOPER); 592 } 593 594 /** 595 * Get static information about an event. 596 * This is used in reports and is not for general use. 597 * 598 * @return array Static information about the event. 599 */ 600 public static final function get_static_info() { 601 /** Var \core\event\base $event. */ 602 $event = new static(); 603 // Set static event data specific for child class. 604 $event->init(); 605 return array( 606 'eventname' => $event->data['eventname'], 607 'component' => $event->data['component'], 608 'target' => $event->data['target'], 609 'action' => $event->data['action'], 610 'crud' => $event->data['crud'], 611 'edulevel' => $event->data['edulevel'], 612 'objecttable' => $event->data['objecttable'], 613 ); 614 } 615 616 /** 617 * Get an explanation of what the class does. 618 * By default returns the phpdocs from the child event class. Ideally this should 619 * be overridden to return a translatable get_string style markdown. 620 * e.g. return new lang_string('eventyourspecialevent', 'plugin_type'); 621 * 622 * @return string An explanation of the event formatted in markdown style. 623 */ 624 public static function get_explanation() { 625 $ref = new \ReflectionClass(get_called_class()); 626 $docblock = $ref->getDocComment(); 627 628 // Check that there is something to work on. 629 if (empty($docblock)) { 630 return null; 631 } 632 633 $docblocklines = explode("\n", $docblock); 634 // Remove the bulk of the comment characters. 635 $pattern = "/(^\s*\/\*\*|^\s+\*\s|^\s+\*)/"; 636 $cleanline = array(); 637 foreach ($docblocklines as $line) { 638 $templine = preg_replace($pattern, '', $line); 639 // If there is nothing on the line then don't add it to the array. 640 if (!empty($templine)) { 641 $cleanline[] = rtrim($templine); 642 } 643 // If we get to a line starting with an @ symbol then we don't want the rest. 644 if (preg_match("/^@|\//", $templine)) { 645 // Get rid of the last entry (it contains an @ symbol). 646 array_pop($cleanline); 647 // Break out of this foreach loop. 648 break; 649 } 650 } 651 // Add a line break to the sanitised lines. 652 $explanation = implode("\n", $cleanline); 653 654 return $explanation; 655 } 656 657 /** 658 * Returns event context. 659 * @return \context 660 */ 661 public function get_context() { 662 if (isset($this->context)) { 663 return $this->context; 664 } 665 $this->context = \context::instance_by_id($this->data['contextid'], IGNORE_MISSING); 666 return $this->context; 667 } 668 669 /** 670 * Returns relevant URL, override in subclasses. 671 * @return \moodle_url 672 */ 673 public function get_url() { 674 return null; 675 } 676 677 /** 678 * Return standardised event data as array. 679 * 680 * @return array All elements are scalars except the 'other' field which is array. 681 */ 682 public function get_data() { 683 return $this->data; 684 } 685 686 /** 687 * Return auxiliary data that was stored in logs. 688 * 689 * List of standard properties: 690 * - origin: IP number, cli,cron 691 * - realuserid: id of the user when logged-in-as 692 * 693 * @return array the format is standardised by logging API 694 */ 695 public function get_logextra() { 696 return $this->logextra; 697 } 698 699 /** 700 * Does this event replace legacy event? 701 * 702 * Note: do not use directly! 703 * 704 * @return null|string legacy event name 705 */ 706 public static function get_legacy_eventname() { 707 return null; 708 } 709 710 /** 711 * Legacy event data if get_legacy_eventname() is not empty. 712 * 713 * Note: do not use directly! 714 * 715 * @return mixed 716 */ 717 protected function get_legacy_eventdata() { 718 return null; 719 } 720 721 /** 722 * Doest this event replace add_to_log() statement? 723 * 724 * Note: do not use directly! 725 * 726 * @return null|array of parameters to be passed to legacy add_to_log() function. 727 */ 728 protected function get_legacy_logdata() { 729 return null; 730 } 731 732 /** 733 * Validate all properties right before triggering the event. 734 * 735 * This throws coding exceptions for fatal problems and debugging for minor problems. 736 * 737 * @throws \coding_exception 738 */ 739 protected final function validate_before_trigger() { 740 global $DB, $CFG; 741 742 if (empty($this->data['crud'])) { 743 throw new \coding_exception('crud must be specified in init() method of each method'); 744 } 745 if (!isset($this->data['edulevel'])) { 746 throw new \coding_exception('edulevel must be specified in init() method of each method'); 747 } 748 if (!empty($this->data['objectid']) and empty($this->data['objecttable'])) { 749 throw new \coding_exception('objecttable must be specified in init() method if objectid present'); 750 } 751 752 if ($CFG->debugdeveloper) { 753 // Ideally these should be coding exceptions, but we need to skip these for performance reasons 754 // on production servers. 755 756 if (!in_array($this->data['crud'], array('c', 'r', 'u', 'd'), true)) { 757 debugging("Invalid event crud value specified.", DEBUG_DEVELOPER); 758 } 759 if (!in_array($this->data['edulevel'], array(self::LEVEL_OTHER, self::LEVEL_TEACHING, self::LEVEL_PARTICIPATING))) { 760 // Bitwise combination of levels is not allowed at this stage. 761 debugging('Event property edulevel must a constant value, see event_base::LEVEL_*', DEBUG_DEVELOPER); 762 } 763 if (self::$fields !== array_keys($this->data)) { 764 debugging('Number of event data fields must not be changed in event classes', DEBUG_DEVELOPER); 765 } 766 $encoded = json_encode($this->data['other']); 767 // The comparison here is not set to strict as whole float numbers will be converted to integers through JSON encoding / 768 // decoding and send an unwanted debugging message. 769 if ($encoded === false or $this->data['other'] != json_decode($encoded, true)) { 770 debugging('other event data must be compatible with json encoding', DEBUG_DEVELOPER); 771 } 772 if ($this->data['userid'] and !is_number($this->data['userid'])) { 773 debugging('Event property userid must be a number', DEBUG_DEVELOPER); 774 } 775 if ($this->data['courseid'] and !is_number($this->data['courseid'])) { 776 debugging('Event property courseid must be a number', DEBUG_DEVELOPER); 777 } 778 if ($this->data['objectid'] and !is_number($this->data['objectid'])) { 779 debugging('Event property objectid must be a number', DEBUG_DEVELOPER); 780 } 781 if ($this->data['relateduserid'] and !is_number($this->data['relateduserid'])) { 782 debugging('Event property relateduserid must be a number', DEBUG_DEVELOPER); 783 } 784 if ($this->data['objecttable']) { 785 if (!$DB->get_manager()->table_exists($this->data['objecttable'])) { 786 debugging('Unknown table specified in objecttable field', DEBUG_DEVELOPER); 787 } 788 if (!isset($this->data['objectid'])) { 789 debugging('Event property objectid must be set when objecttable is defined', DEBUG_DEVELOPER); 790 } 791 } 792 } 793 } 794 795 /** 796 * Trigger event. 797 */ 798 public final function trigger() { 799 global $CFG; 800 801 if ($this->restored) { 802 throw new \coding_exception('Can not trigger restored event'); 803 } 804 if ($this->triggered or $this->dispatched) { 805 throw new \coding_exception('Can not trigger event twice'); 806 } 807 808 $this->validate_before_trigger(); 809 810 $this->triggered = true; 811 812 if (isset($CFG->loglifetime) and $CFG->loglifetime != -1) { 813 if ($data = $this->get_legacy_logdata()) { 814 $manager = get_log_manager(); 815 if (method_exists($manager, 'legacy_add_to_log')) { 816 if (is_array($data[0])) { 817 // Some events require several entries in 'log' table. 818 foreach ($data as $d) { 819 call_user_func_array(array($manager, 'legacy_add_to_log'), $d); 820 } 821 } else { 822 call_user_func_array(array($manager, 'legacy_add_to_log'), $data); 823 } 824 } 825 } 826 } 827 828 if (PHPUNIT_TEST and \phpunit_util::is_redirecting_events()) { 829 $this->dispatched = true; 830 \phpunit_util::event_triggered($this); 831 return; 832 } 833 834 \core\event\manager::dispatch($this); 835 836 $this->dispatched = true; 837 } 838 839 /** 840 * Was this event already triggered? 841 * 842 * @return bool 843 */ 844 public final function is_triggered() { 845 return $this->triggered; 846 } 847 848 /** 849 * Used from event manager to prevent direct access. 850 * 851 * @return bool 852 */ 853 public final function is_dispatched() { 854 return $this->dispatched; 855 } 856 857 /** 858 * Was this event restored? 859 * 860 * @return bool 861 */ 862 public final function is_restored() { 863 return $this->restored; 864 } 865 866 /** 867 * Add cached data that will be most probably used in event observers. 868 * 869 * This is used to improve performance, but it is required for data 870 * that was just deleted. 871 * 872 * @param string $tablename 873 * @param \stdClass $record 874 * 875 * @throws \coding_exception if used after ::trigger() 876 */ 877 public final function add_record_snapshot($tablename, $record) { 878 global $DB, $CFG; 879 880 if ($this->triggered) { 881 throw new \coding_exception('It is not possible to add snapshots after triggering of events'); 882 } 883 884 // Special case for course module, allow instance of cm_info to be passed instead of stdClass. 885 if ($tablename === 'course_modules' && $record instanceof \cm_info) { 886 $record = $record->get_course_module_record(); 887 } 888 889 // NOTE: this might use some kind of MUC cache, 890 // hopefully we will not run out of memory here... 891 if ($CFG->debugdeveloper) { 892 if (!($record instanceof \stdClass)) { 893 debugging('Argument $record must be an instance of stdClass.', DEBUG_DEVELOPER); 894 } 895 if (!$DB->get_manager()->table_exists($tablename)) { 896 debugging("Invalid table name '$tablename' specified, database table does not exist.", DEBUG_DEVELOPER); 897 } else { 898 $columns = $DB->get_columns($tablename); 899 $missingfields = array_diff(array_keys($columns), array_keys((array)$record)); 900 if (!empty($missingfields)) { 901 debugging("Fields list in snapshot record does not match fields list in '$tablename'. Record is missing fields: ". 902 join(', ', $missingfields), DEBUG_DEVELOPER); 903 } 904 } 905 } 906 $this->recordsnapshots[$tablename][$record->id] = $record; 907 } 908 909 /** 910 * Returns cached record or fetches data from database if not cached. 911 * 912 * @param string $tablename 913 * @param int $id 914 * @return \stdClass 915 * 916 * @throws \coding_exception if used after ::restore() 917 */ 918 public final function get_record_snapshot($tablename, $id) { 919 global $DB; 920 921 if ($this->restored) { 922 throw new \coding_exception('It is not possible to get snapshots from restored events'); 923 } 924 925 if (isset($this->recordsnapshots[$tablename][$id])) { 926 return clone($this->recordsnapshots[$tablename][$id]); 927 } 928 929 $record = $DB->get_record($tablename, array('id'=>$id)); 930 $this->recordsnapshots[$tablename][$id] = $record; 931 932 return $record; 933 } 934 935 /** 936 * Magic getter for read only access. 937 * 938 * @param string $name 939 * @return mixed 940 */ 941 public function __get($name) { 942 if ($name === 'level') { 943 debugging('level property is deprecated, use edulevel property instead', DEBUG_DEVELOPER); 944 return $this->data['edulevel']; 945 } 946 if (array_key_exists($name, $this->data)) { 947 return $this->data[$name]; 948 } 949 950 debugging("Accessing non-existent event property '$name'"); 951 } 952 953 /** 954 * Magic setter. 955 * 956 * Note: we must not allow modification of data from outside, 957 * after trigger() the data MUST NOT CHANGE!!! 958 * 959 * @param string $name 960 * @param mixed $value 961 * 962 * @throws \coding_exception 963 */ 964 public function __set($name, $value) { 965 throw new \coding_exception('Event properties must not be modified.'); 966 } 967 968 /** 969 * Is data property set? 970 * 971 * @param string $name 972 * @return bool 973 */ 974 public function __isset($name) { 975 if ($name === 'level') { 976 debugging('level property is deprecated, use edulevel property instead', DEBUG_DEVELOPER); 977 return isset($this->data['edulevel']); 978 } 979 return isset($this->data[$name]); 980 } 981 982 /** 983 * Create an iterator because magic vars can't be seen by 'foreach'. 984 * 985 * @return \ArrayIterator 986 */ 987 public function getIterator() { 988 return new \ArrayIterator($this->data); 989 } 990 991 /** 992 * Whether this event has been marked as deprecated. 993 * 994 * Events cannot be deprecated in the normal fashion as they must remain to support historical data. 995 * Once they are deprecated, there is no way to trigger the event, so it does not make sense to list it in some 996 * parts of the UI (e.g. Event Monitor). 997 * 998 * @return boolean 999 */ 1000 public static function is_deprecated() { 1001 return false; 1002 } 1003 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
