Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 3.11.x will end 14 Nov 2022 (12 months plus 6 months extension).
  • Bug fixes for security issues in 3.11.x will end 13 Nov 2023 (18 months plus 12 months extension).
  • PHP version: minimum PHP 7.3.0 Note: minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is supported too.

Differences Between: [Versions 310 and 311] [Versions 311 and 400] [Versions 311 and 401] [Versions 311 and 402] [Versions 311 and 403] [Versions 39 and 311]

   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      final private 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  }