27f74c0a20d9ef33fff743136d75579adcfe5947
[moodle.git] / lib / classes / event / base.php
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/>.
17 namespace core\event;
19 defined('MOODLE_INTERNAL') || die();
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  */
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 {
58     /**
59      * Other level.
60      */
61     const LEVEL_OTHER = 0;
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;
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;
78     /**
79      * The value used when an id can not be mapped during a restore.
80      */
81     const NOT_MAPPED = -31337;
83     /**
84      * The value used when an id can not be found during a restore.
85      */
86     const NOT_FOUND = -31338;
88     /**
89      * User id to use when the user is not logged in.
90      */
91     const USER_NOTLOGGEDIN = 0;
93     /**
94      * User id to use when actor is not an actual user but system, cli or cron.
95      */
96     const USER_OTHER = -1;
98     /** @var array event data */
99     protected $data;
101     /** @var array the format is standardised by logging API */
102     protected $logextra;
104     /** @var \context of this event */
105     protected $context;
107     /**
108      * @var bool indicates if event was already triggered,
109      *           this prevents second attempt to trigger event.
110      */
111     private $triggered;
113     /**
114      * @var bool indicates if event was already dispatched,
115      *           this prevents direct calling of manager::dispatch($event).
116      */
117     private $dispatched;
119     /**
120      * @var bool indicates if event was restored from storage,
121      *           this prevents triggering of restored events.
122      */
123     private $restored;
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');
131     /** @var array simple record cache */
132     private $recordsnapshots = array();
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);
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];
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     }
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;
176         $data = (array)$data;
178         /** @var \core\event\base $event */
179         $event = new static();
180         $event->triggered = false;
181         $event->restored = false;
182         $event->dispatched = false;
184         // By default all events are visible in logs.
185         $event->data['anonymous'] = 0;
187         // Set static event data specific for child class.
188         $event->init();
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         }
198         // Set automatic data.
199         $event->data['timecreated'] = time();
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'];
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             }
217         } else if (!empty($data['context'])) {
218             $event->context = $data['context'];
220         } else if (!empty($data['contextid'])) {
221             $event->context = \context::instance_by_id($data['contextid'], MUST_EXIST);
223         } else {
224             throw new \coding_exception('context (or contextid) is a required event property, system context may be hardcoded in init() method.');
225         }
227         $event->data['contextid'] = $event->context->id;
228         $event->data['contextlevel'] = $event->context->contextlevel;
229         $event->data['contextinstanceid'] = $event->context->instanceid;
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         }
239         if (!array_key_exists('relateduserid', $data) and $event->context->contextlevel == CONTEXT_USER) {
240             $event->data['relateduserid'] = $event->context->instanceid;
241         }
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');
248             foreach ($data as $key => $ignored) {
249                 if ($key === 'context') {
250                     continue;
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);
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);
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         }
271         // Let developers validate their custom data (such as $this->data['other'], contextlevel, etc.).
272         $event->validate_data();
274         return $event;
275     }
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();
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     }
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     }
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();
331         if (static::is_deprecated()) {
332             $return = get_string('deprecatedeventname', 'core', $return);
333         }
335         return $return;
336     }
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     }
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     }
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'];
376         // Security: make 100% sure this really is an event class.
377         if ($classname !== "\\{$component}\\event\\{$target}_{$action}") {
378             return false;
379         }
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         }
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;
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;
411         return $event;
412     }
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';
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;
432         return $event;
433     }
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;
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         }
461         $event->data = array();
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;
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;
516         $event->data['other'] = (array)$legacy;
518         return $event;
519     }
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);
552         return false;
553     }
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     }
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     }
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();
628         // Check that there is something to work on.
629         if (empty($docblock)) {
630             return null;
631         }
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);
654         return $explanation;
655     }
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     }
669     /**
670      * Returns relevant URL, override in subclasses.
671      * @return \moodle_url
672      */
673     public function get_url() {
674         return null;
675     }
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     }
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     }
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     }
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     }
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     }
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;
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         }
752         if ($CFG->debugdeveloper) {
753             // Ideally these should be coding exceptions, but we need to skip these for performance reasons
754             // on production servers.
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     }
795     /**
796      * Trigger event.
797      */
798     public final function trigger() {
799         global $CFG;
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         }
808         $this->validate_before_trigger();
810         $this->triggered = true;
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         }
828         if (PHPUNIT_TEST and \phpunit_util::is_redirecting_events()) {
829             $this->dispatched = true;
830             \phpunit_util::event_triggered($this);
831             return;
832         }
834         \core\event\manager::dispatch($this);
836         $this->dispatched = true;
838         if ($legacyeventname = static::get_legacy_eventname()) {
839             events_trigger_legacy($legacyeventname, $this->get_legacy_eventdata());
840         }
841     }
843     /**
844      * Was this event already triggered?
845      *
846      * @return bool
847      */
848     public final function is_triggered() {
849         return $this->triggered;
850     }
852     /**
853      * Used from event manager to prevent direct access.
854      *
855      * @return bool
856      */
857     public final function is_dispatched() {
858         return $this->dispatched;
859     }
861     /**
862      * Was this event restored?
863      *
864      * @return bool
865      */
866     public final function is_restored() {
867         return $this->restored;
868     }
870     /**
871      * Add cached data that will be most probably used in event observers.
872      *
873      * This is used to improve performance, but it is required for data
874      * that was just deleted.
875      *
876      * @param string $tablename
877      * @param \stdClass $record
878      *
879      * @throws \coding_exception if used after ::trigger()
880      */
881     public final function add_record_snapshot($tablename, $record) {
882         global $DB, $CFG;
884         if ($this->triggered) {
885             throw new \coding_exception('It is not possible to add snapshots after triggering of events');
886         }
888         // Special case for course module, allow instance of cm_info to be passed instead of stdClass.
889         if ($tablename === 'course_modules' && $record instanceof \cm_info) {
890             $record = $record->get_course_module_record();
891         }
893         // NOTE: this might use some kind of MUC cache,
894         //       hopefully we will not run out of memory here...
895         if ($CFG->debugdeveloper) {
896             if (!($record instanceof \stdClass)) {
897                 debugging('Argument $record must be an instance of stdClass.', DEBUG_DEVELOPER);
898             }
899             if (!$DB->get_manager()->table_exists($tablename)) {
900                 debugging("Invalid table name '$tablename' specified, database table does not exist.", DEBUG_DEVELOPER);
901             } else {
902                 $columns = $DB->get_columns($tablename);
903                 $missingfields = array_diff(array_keys($columns), array_keys((array)$record));
904                 if (!empty($missingfields)) {
905                     debugging("Fields list in snapshot record does not match fields list in '$tablename'. Record is missing fields: ".
906                             join(', ', $missingfields), DEBUG_DEVELOPER);
907                 }
908             }
909         }
910         $this->recordsnapshots[$tablename][$record->id] = $record;
911     }
913     /**
914      * Returns cached record or fetches data from database if not cached.
915      *
916      * @param string $tablename
917      * @param int $id
918      * @return \stdClass
919      *
920      * @throws \coding_exception if used after ::restore()
921      */
922     public final function get_record_snapshot($tablename, $id) {
923         global $DB;
925         if ($this->restored) {
926             throw new \coding_exception('It is not possible to get snapshots from restored events');
927         }
929         if (isset($this->recordsnapshots[$tablename][$id])) {
930             return clone($this->recordsnapshots[$tablename][$id]);
931         }
933         $record = $DB->get_record($tablename, array('id'=>$id));
934         $this->recordsnapshots[$tablename][$id] = $record;
936         return $record;
937     }
939     /**
940      * Magic getter for read only access.
941      *
942      * @param string $name
943      * @return mixed
944      */
945     public function __get($name) {
946         if ($name === 'level') {
947             debugging('level property is deprecated, use edulevel property instead', DEBUG_DEVELOPER);
948             return $this->data['edulevel'];
949         }
950         if (array_key_exists($name, $this->data)) {
951             return $this->data[$name];
952         }
954         debugging("Accessing non-existent event property '$name'");
955     }
957     /**
958      * Magic setter.
959      *
960      * Note: we must not allow modification of data from outside,
961      *       after trigger() the data MUST NOT CHANGE!!!
962      *
963      * @param string $name
964      * @param mixed $value
965      *
966      * @throws \coding_exception
967      */
968     public function __set($name, $value) {
969         throw new \coding_exception('Event properties must not be modified.');
970     }
972     /**
973      * Is data property set?
974      *
975      * @param string $name
976      * @return bool
977      */
978     public function __isset($name) {
979         if ($name === 'level') {
980             debugging('level property is deprecated, use edulevel property instead', DEBUG_DEVELOPER);
981             return isset($this->data['edulevel']);
982         }
983         return isset($this->data[$name]);
984     }
986     /**
987      * Create an iterator because magic vars can't be seen by 'foreach'.
988      *
989      * @return \ArrayIterator
990      */
991     public function getIterator() {
992         return new \ArrayIterator($this->data);
993     }
995     /**
996      * Whether this event has been marked as deprecated.
997      *
998      * Events cannot be deprecated in the normal fashion as they must remain to support historical data.
999      * Once they are deprecated, there is no way to trigger the event, so it does not make sense to list it in some
1000      * parts of the UI (e.g. Event Monitor).
1001      *
1002      * @return boolean
1003      */
1004     public static function is_deprecated() {
1005         return false;
1006     }