MDL-55188 events: Final deprecation of part of events 1 API.
[moodle.git] / lib / classes / event / base.php
CommitLineData
d8a1f426
PS
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
17namespace core\event;
18
5999e40f
MN
19defined('MOODLE_INTERNAL') || die();
20
d8a1f426
PS
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
d8a1f426
PS
29/**
30 * All other event classes must extend this class.
31 *
32 * @package core
9638600b 33 * @since Moodle 2.6
d8a1f426
PS
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
660f049f 40 * @property-read string $target what/who was target of the action
a85258ca 41 * @property-read string $objecttable name of database table where is object record stored
d8a1f426
PS
42 * @property-read int $objectid optional id of the object
43 * @property-read string $crud letter indicating event type
3345e24f 44 * @property-read int $edulevel log level (one of the constants LEVEL_)
d8a1f426
PS
45 * @property-read int $contextid
46 * @property-read int $contextlevel
47 * @property-read int $contextinstanceid
48 * @property-read int $userid who did this?
b64af72c 49 * @property-read int $courseid the courseid of the event context, 0 for contexts above course
d8a1f426 50 * @property-read int $relateduserid
bc293202
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.
c4297815 53 * @property-read mixed $other array or scalar, can not contain objects
d8a1f426
PS
54 * @property-read int $timecreated
55 */
ed17808d 56abstract class base implements \IteratorAggregate {
38d6fbfa
FM
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
6920d390
MN
78 /**
79 * The value used when an id can not be mapped during a restore.
80 */
81 const NOT_MAPPED = -31337;
82
f74fe5ba
MN
83 /**
84 * The value used when an id can not be found during a restore.
85 */
86 const NOT_FOUND = -31338;
87
0edba58d
AA
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
d8a1f426
PS
98 /** @var array event data */
99 protected $data;
100
4b734e74 101 /** @var array the format is standardised by logging API */
b0cdc969 102 protected $logextra;
4b734e74 103
d8a1f426
PS
104 /** @var \context of this event */
105 protected $context;
106
22626564
PS
107 /**
108 * @var bool indicates if event was already triggered,
109 * this prevents second attempt to trigger event.
110 */
d8a1f426
PS
111 private $triggered;
112
22626564
PS
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 */
d8a1f426
PS
123 private $restored;
124
125 /** @var array list of event properties */
126 private static $fields = array(
3345e24f 127 'eventname', 'component', 'action', 'target', 'objecttable', 'objectid', 'crud', 'edulevel', 'contextid',
bc293202 128 'contextlevel', 'contextinstanceid', 'userid', 'courseid', 'relateduserid', 'anonymous', 'other',
4b734e74 129 'timecreated');
d8a1f426
PS
130
131 /** @var array simple record cache */
fd4f3e9e 132 private $recordsnapshots = array();
d8a1f426
PS
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);
b6c7ab22
AA
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);
d8a1f426
PS
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
c4297815 165 * 3/ other - the other data describing the event, can not contain objects
d8a1f426
PS
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) {
3345e24f 174 global $USER, $CFG;
d8a1f426
PS
175
176 $data = (array)$data;
177
178 /** @var \core\event\base $event */
179 $event = new static();
180 $event->triggered = false;
181 $event->restored = false;
22626564 182 $event->dispatched = false;
d8a1f426 183
bc293202
184 // By default all events are visible in logs.
185 $event->data['anonymous'] = 0;
186
fb23739e
PS
187 // Set static event data specific for child class.
188 $event->init();
189
3345e24f
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
4b734e74
PS
198 // Set automatic data.
199 $event->data['timecreated'] = time();
200
4b734e74 201 // Set optional data or use defaults.
d8a1f426
PS
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;
c4297815 205 $event->data['other'] = isset($data['other']) ? $data['other'] : null;
d8a1f426 206 $event->data['relateduserid'] = isset($data['relateduserid']) ? $data['relateduserid'] : null;
bc293202
207 if (isset($data['anonymous'])) {
208 $event->data['anonymous'] = $data['anonymous'];
209 }
210 $event->data['anonymous'] = (int)(bool)$event->data['anonymous'];
d8a1f426 211
fddd1018 212 if (isset($event->context)) {
097011c4
PS
213 if (isset($data['context'])) {
214 debugging('Context was already set in init() method, ignoring context parameter', DEBUG_DEVELOPER);
fddd1018 215 }
fddd1018
PS
216
217 } else if (!empty($data['context'])) {
d8a1f426 218 $event->context = $data['context'];
27af3e62
PS
219
220 } else if (!empty($data['contextid'])) {
097011c4
PS
221 $event->context = \context::instance_by_id($data['contextid'], MUST_EXIST);
222
27af3e62 223 } else {
fddd1018 224 throw new \coding_exception('context (or contextid) is a required event property, system context may be hardcoded in init() method.');
d8a1f426 225 }
d8a1f426 226
097011c4
PS
227 $event->data['contextid'] = $event->context->id;
228 $event->data['contextlevel'] = $event->context->contextlevel;
229 $event->data['contextinstanceid'] = $event->context->instanceid;
230
d8a1f426 231 if (!isset($event->data['courseid'])) {
097011c4 232 if ($coursecontext = $event->context->get_course_context(false)) {
513d8793 233 $event->data['courseid'] = $coursecontext->instanceid;
d8a1f426
PS
234 } else {
235 $event->data['courseid'] = 0;
236 }
237 }
238
097011c4 239 if (!array_key_exists('relateduserid', $data) and $event->context->contextlevel == CONTEXT_USER) {
d8a1f426
PS
240 $event->data['relateduserid'] = $event->context->instanceid;
241 }
242
4b734e74 243 // Warn developers if they do something wrong.
96f81ea3 244 if ($CFG->debugdeveloper) {
660f049f 245 static $automatickeys = array('eventname', 'component', 'action', 'target', 'contextlevel', 'contextinstanceid', 'timecreated');
3345e24f 246 static $initkeys = array('crud', 'level', 'objecttable', 'edulevel');
4b734e74
PS
247
248 foreach ($data as $key => $ignored) {
249 if ($key === 'context') {
250 continue;
251
252 } else if (in_array($key, $automatickeys)) {
96f81ea3 253 debugging("Data key '$key' is not allowed in \\core\\event\\base::create() method, it is set automatically", DEBUG_DEVELOPER);
4b734e74
PS
254
255 } else if (in_array($key, $initkeys)) {
96f81ea3 256 debugging("Data key '$key' is not allowed in \\core\\event\\base::create() method, you need to set it in init() method", DEBUG_DEVELOPER);
4b734e74
PS
257
258 } else if (!in_array($key, self::$fields)) {
259 debugging("Data key '$key' does not exist in \\core\\event\\base");
d8a1f426
PS
260 }
261 }
9ede00db
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 }
d8a1f426
PS
269 }
270
c61a3a5c 271 // Let developers validate their custom data (such as $this->data['other'], contextlevel, etc.).
fddd1018
PS
272 $event->validate_data();
273
d8a1f426
PS
274 return $event;
275 }
276
277 /**
278 * Override in subclass.
279 *
280 * Set all required data properties:
38d6fbfa 281 * 1/ crud - letter [crud]
3345e24f 282 * 2/ edulevel - using a constant self::LEVEL_*.
a85258ca 283 * 3/ objecttable - name of database table if objectid specified
4b734e74 284 *
fddd1018
PS
285 * Optionally it can set:
286 * a/ fixed system context
d8a1f426
PS
287 *
288 * @return void
289 */
290 protected abstract function init();
291
fddd1018 292 /**
c61a3a5c 293 * Let developers validate their custom data (such as $this->data['other'], contextlevel, etc.).
fddd1018
PS
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
4b734e74
PS
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 *
fc9fc9fb 307 * @return string
4b734e74
PS
308 */
309 public static function get_name() {
310 // Override in subclass with real lang string.
1ccc1268 311 $parts = explode('\\', get_called_class());
4b734e74 312 if (count($parts) !== 3) {
fc9fc9fb 313 return get_string('unknownevent', 'error');
4b734e74
PS
314 }
315 return $parts[0].': '.str_replace('_', ' ', $parts[2]);
316 }
317
51d85c7c
AN
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
4b734e74 338 /**
fc9fc9fb 339 * Returns non-localised event description with id's for admin use only.
05a970d3 340 *
fc9fc9fb 341 * @return string
4b734e74
PS
342 */
343 public function get_description() {
344 return null;
345 }
346
347 /**
bc22fa93
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
4b734e74
PS
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) {
15f009e1 359 debugging('can_view() method is deprecated, use anonymous flag instead if necessary.', DEBUG_DEVELOPER);
4b734e74
PS
360 return is_siteadmin($user_or_id);
361 }
362
d8a1f426
PS
363 /**
364 * Restore event from existing historic data.
365 *
366 * @param array $data
b0cdc969 367 * @param array $logextra the format is standardised by logging API
d8a1f426
PS
368 * @return bool|\core\event\base
369 */
b0cdc969 370 public static final function restore(array $data, array $logextra) {
d8a1f426
PS
371 $classname = $data['eventname'];
372 $component = $data['component'];
373 $action = $data['action'];
132eff90 374 $target = $data['target'];
d8a1f426
PS
375
376 // Security: make 100% sure this really is an event class.
132eff90 377 if ($classname !== "\\{$component}\\event\\{$target}_{$action}") {
d8a1f426
PS
378 return false;
379 }
380
381 if (!class_exists($classname)) {
d409944a 382 return self::restore_unknown($data, $logextra);
d8a1f426
PS
383 }
384 $event = new $classname();
385 if (!($event instanceof \core\event\base)) {
386 return false;
387 }
388
85a4b8a3 389 $event->init(); // Init method of events could be setting custom properties.
d8a1f426 390 $event->restored = true;
22626564
PS
391 $event->triggered = true;
392 $event->dispatched = true;
b0cdc969 393 $event->logextra = $logextra;
d8a1f426
PS
394
395 foreach (self::$fields as $key) {
4b734e74 396 if (!array_key_exists($key, $data)) {
d8a1f426 397 debugging("Event restore data must contain key $key");
4b734e74 398 $data[$key] = null;
d8a1f426
PS
399 }
400 }
4b734e74
PS
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;
d8a1f426
PS
410
411 return $event;
412 }
413
d409944a
PS
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
7eaca5a8
435 /**
436 * Create fake event from legacy log data.
437 *
81fbecc0 438 * @param \stdClass $legacy
7eaca5a8
439 * @return base
440 */
441 public static final function restore_legacy($legacy) {
442 $classname = get_called_class();
81fbecc0 443 /** @var base $event */
7eaca5a8
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
81fbecc0
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;
7eaca5a8
515
516 $event->data['other'] = (array)$legacy;
517
518 return $event;
519 }
520
6920d390
MN
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() {
63b5a5fa 549 debugging('In order to restore course logs accurately the event "' . get_called_class() . '" must define the
6920d390
MN
550 function get_objectid_mapping().', DEBUG_DEVELOPER);
551
552 return false;
553 }
554
901a7ff7
MN
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() {
63b5a5fa 590 debugging('In order to restore course logs accurately the event "' . get_called_class() . '" must define the
901a7ff7
MN
591 function get_other_mapping().', DEBUG_DEVELOPER);
592 }
593
cc662b06
AG
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
d8a1f426
PS
657 /**
658 * Returns event context.
659 * @return \context
660 */
661 public function get_context() {
662 if (isset($this->context)) {
663 return $this->context;
664 }
fdc729ea 665 $this->context = \context::instance_by_id($this->data['contextid'], IGNORE_MISSING);
d8a1f426
PS
666 return $this->context;
667 }
668
669 /**
670 * Returns relevant URL, override in subclasses.
4b734e74 671 * @return \moodle_url
d8a1f426
PS
672 */
673 public function get_url() {
674 return null;
675 }
676
677 /**
678 * Return standardised event data as array.
679 *
3345e24f 680 * @return array All elements are scalars except the 'other' field which is array.
d8a1f426
PS
681 */
682 public function get_data() {
683 return $this->data;
684 }
685
4b734e74
PS
686 /**
687 * Return auxiliary data that was stored in logs.
688 *
3345e24f
689 * List of standard properties:
690 * - origin: IP number, cli,cron
691 * - realuserid: id of the user when logged-in-as
05a970d3 692 *
4b734e74
PS
693 * @return array the format is standardised by logging API
694 */
b0cdc969
PS
695 public function get_logextra() {
696 return $this->logextra;
4b734e74
PS
697 }
698
d8a1f426
PS
699 /**
700 * Does this event replace legacy event?
701 *
82b1fb51
PS
702 * Note: do not use directly!
703 *
d8a1f426
PS
704 * @return null|string legacy event name
705 */
22446003 706 public static function get_legacy_eventname() {
d8a1f426
PS
707 return null;
708 }
709
710 /**
711 * Legacy event data if get_legacy_eventname() is not empty.
712 *
82b1fb51
PS
713 * Note: do not use directly!
714 *
d8a1f426
PS
715 * @return mixed
716 */
82b1fb51 717 protected function get_legacy_eventdata() {
d8a1f426
PS
718 return null;
719 }
720
721 /**
722 * Doest this event replace add_to_log() statement?
723 *
82b1fb51
PS
724 * Note: do not use directly!
725 *
d8a1f426
PS
726 * @return null|array of parameters to be passed to legacy add_to_log() function.
727 */
82b1fb51 728 protected function get_legacy_logdata() {
d8a1f426
PS
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() {
96f81ea3 740 global $DB, $CFG;
a85258ca 741
d8a1f426
PS
742 if (empty($this->data['crud'])) {
743 throw new \coding_exception('crud must be specified in init() method of each method');
744 }
3345e24f
745 if (!isset($this->data['edulevel'])) {
746 throw new \coding_exception('edulevel must be specified in init() method of each method');
d8a1f426 747 }
a85258ca
PS
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 }
d8a1f426 751
96f81ea3 752 if ($CFG->debugdeveloper) {
d8a1f426
PS
753 // Ideally these should be coding exceptions, but we need to skip these for performance reasons
754 // on production servers.
4b734e74
PS
755
756 if (!in_array($this->data['crud'], array('c', 'r', 'u', 'd'), true)) {
96f81ea3 757 debugging("Invalid event crud value specified.", DEBUG_DEVELOPER);
4b734e74 758 }
3345e24f 759 if (!in_array($this->data['edulevel'], array(self::LEVEL_OTHER, self::LEVEL_TEACHING, self::LEVEL_PARTICIPATING))) {
38d6fbfa 760 // Bitwise combination of levels is not allowed at this stage.
3345e24f 761 debugging('Event property edulevel must a constant value, see event_base::LEVEL_*', DEBUG_DEVELOPER);
4b734e74 762 }
d8a1f426 763 if (self::$fields !== array_keys($this->data)) {
96f81ea3 764 debugging('Number of event data fields must not be changed in event classes', DEBUG_DEVELOPER);
d8a1f426 765 }
c4297815 766 $encoded = json_encode($this->data['other']);
49ff1342
AG
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)) {
96f81ea3 770 debugging('other event data must be compatible with json encoding', DEBUG_DEVELOPER);
4b734e74
PS
771 }
772 if ($this->data['userid'] and !is_number($this->data['userid'])) {
96f81ea3 773 debugging('Event property userid must be a number', DEBUG_DEVELOPER);
4b734e74
PS
774 }
775 if ($this->data['courseid'] and !is_number($this->data['courseid'])) {
96f81ea3 776 debugging('Event property courseid must be a number', DEBUG_DEVELOPER);
4b734e74
PS
777 }
778 if ($this->data['objectid'] and !is_number($this->data['objectid'])) {
96f81ea3 779 debugging('Event property objectid must be a number', DEBUG_DEVELOPER);
4b734e74
PS
780 }
781 if ($this->data['relateduserid'] and !is_number($this->data['relateduserid'])) {
96f81ea3 782 debugging('Event property relateduserid must be a number', DEBUG_DEVELOPER);
d8a1f426 783 }
a85258ca
PS
784 if ($this->data['objecttable']) {
785 if (!$DB->get_manager()->table_exists($this->data['objecttable'])) {
96f81ea3 786 debugging('Unknown table specified in objecttable field', DEBUG_DEVELOPER);
a85258ca 787 }
31e571cd
FM
788 if (!isset($this->data['objectid'])) {
789 debugging('Event property objectid must be set when objecttable is defined', DEBUG_DEVELOPER);
790 }
a85258ca 791 }
d8a1f426
PS
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 }
22626564 804 if ($this->triggered or $this->dispatched) {
d8a1f426
PS
805 throw new \coding_exception('Can not trigger event twice');
806 }
807
d8a1f426
PS
808 $this->validate_before_trigger();
809
22626564
PS
810 $this->triggered = true;
811
ef1987dc 812 if (isset($CFG->loglifetime) and $CFG->loglifetime != -1) {
d8a1f426 813 if ($data = $this->get_legacy_logdata()) {
7eaca5a8
814 $manager = get_log_manager();
815 if (method_exists($manager, 'legacy_add_to_log')) {
c3ba899a
MG
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 }
7eaca5a8 824 }
d8a1f426
PS
825 }
826 }
827
62401e8f
PS
828 if (PHPUNIT_TEST and \phpunit_util::is_redirecting_events()) {
829 $this->dispatched = true;
830 \phpunit_util::event_triggered($this);
831 return;
832 }
833
d8a1f426
PS
834 \core\event\manager::dispatch($this);
835
22626564 836 $this->dispatched = true;
d8a1f426
PS
837 }
838
839 /**
22626564 840 * Was this event already triggered?
d8a1f426
PS
841 *
842 * @return bool
843 */
22626564 844 public final function is_triggered() {
d8a1f426
PS
845 return $this->triggered;
846 }
847
22626564
PS
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
d8a1f426 857 /**
4b734e74 858 * Was this event restored?
d8a1f426
PS
859 *
860 * @return bool
861 */
22626564 862 public final function is_restored() {
d8a1f426
PS
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
4b734e74 870 * that was just deleted.
d8a1f426
PS
871 *
872 * @param string $tablename
873 * @param \stdClass $record
300dbc66
PS
874 *
875 * @throws \coding_exception if used after ::trigger()
d8a1f426 876 */
fd4f3e9e 877 public final function add_record_snapshot($tablename, $record) {
96f81ea3 878 global $DB, $CFG;
d8a1f426 879
300dbc66
PS
880 if ($this->triggered) {
881 throw new \coding_exception('It is not possible to add snapshots after triggering of events');
882 }
883
92e2e855
MG
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 }
fc755767 888
d8a1f426
PS
889 // NOTE: this might use some kind of MUC cache,
890 // hopefully we will not run out of memory here...
96f81ea3 891 if ($CFG->debugdeveloper) {
92e2e855
MG
892 if (!($record instanceof \stdClass)) {
893 debugging('Argument $record must be an instance of stdClass.', DEBUG_DEVELOPER);
894 }
d8a1f426 895 if (!$DB->get_manager()->table_exists($tablename)) {
96f81ea3 896 debugging("Invalid table name '$tablename' specified, database table does not exist.", DEBUG_DEVELOPER);
5e70ea26
MG
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 }
d8a1f426
PS
904 }
905 }
b396d40e 906 $this->recordsnapshots[$tablename][$record->id] = $record;
d8a1f426
PS
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
4ad6d5c5
PS
915 *
916 * @throws \coding_exception if used after ::restore()
d8a1f426 917 */
fd4f3e9e 918 public final function get_record_snapshot($tablename, $id) {
d8a1f426
PS
919 global $DB;
920
4ad6d5c5
PS
921 if ($this->restored) {
922 throw new \coding_exception('It is not possible to get snapshots from restored events');
923 }
924
b396d40e 925 if (isset($this->recordsnapshots[$tablename][$id])) {
5e70ea26 926 return clone($this->recordsnapshots[$tablename][$id]);
d8a1f426
PS
927 }
928
929 $record = $DB->get_record($tablename, array('id'=>$id));
b396d40e 930 $this->recordsnapshots[$tablename][$id] = $record;
d8a1f426
PS
931
932 return $record;
933 }
934
935 /**
936 * Magic getter for read only access.
937 *
d8a1f426
PS
938 * @param string $name
939 * @return mixed
d8a1f426
PS
940 */
941 public function __get($name) {
3345e24f
942 if ($name === 'level') {
943 debugging('level property is deprecated, use edulevel property instead', DEBUG_DEVELOPER);
944 return $this->data['edulevel'];
945 }
d8a1f426
PS
946 if (array_key_exists($name, $this->data)) {
947 return $this->data[$name];
948 }
949
4b734e74 950 debugging("Accessing non-existent event property '$name'");
d8a1f426 951 }
605a8c33
PS
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) {
3345e24f
975 if ($name === 'level') {
976 debugging('level property is deprecated, use edulevel property instead', DEBUG_DEVELOPER);
977 return isset($this->data['edulevel']);
978 }
605a8c33
PS
979 return isset($this->data[$name]);
980 }
ed17808d
PS
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 }
51d85c7c
AN
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 }
d8a1f426 1003}