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]

Base event class.

Copyright: 2013 Petr Skoda {@link http://skodak.org}
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 1003 lines (36 kb)
Included or required: 1 time
Referenced: 0 times
Includes or requires: 0 files

Defines 3 classes


Class: base  - X-Ref

All other event classes must extend this class.

__construct()   X-Ref
Private constructor, use create() or restore() methods instead.


Class: name  - X-Ref

create(array $data = null)   X-Ref
Create new event.

The optional data keys as:
1/ objectid - the id of the object specified in class name
2/ context - the context of this event
3/ other - the other data describing the event, can not contain objects
4/ relateduserid - the id of user which is somehow related to this event

param: array $data
return: \core\event\base returns instance of new event

validate_data()   X-Ref
Let developers validate their custom data (such as $this->data['other'], contextlevel, etc.).

Throw \coding_exception or debugging() notice in case of any problems.

get_name()   X-Ref
Returns localised general event name.

Override in subclass, we can not make it static and abstract at the same time.

return: string

get_name_with_info()   X-Ref
Returns the event name complete with metadata information.

This includes information about whether the event has been deprecated so should not be used in all situations -
for example within reports themselves.

If overriding this function, please ensure that you call the parent version too.

return: string

get_description()   X-Ref
Returns non-localised event description with id's for admin use only.

return: string

can_view($user_or_id = null)   X-Ref
This method was originally intended for granular
access control on the event level, unfortunately
the proper implementation would be too expensive
in many cases.

param: int|\stdClass $user_or_id ID of the user.
return: bool True if the user can view the event, false otherwise.

restore(array $data, array $logextra)   X-Ref
Restore event from existing historic data.

param: array $data
param: array $logextra the format is standardised by logging API
return: bool|\core\event\base

restore_unknown(array $data, array $logextra)   X-Ref
Restore unknown event.

param: array $data
param: array $logextra
return: unknown_logged

restore_legacy($legacy)   X-Ref
Create fake event from legacy log data.

param: \stdClass $legacy
return: base

get_objectid_mapping()   X-Ref
This is used when restoring course logs where it is required that we
map the objectid to it's new value in the new course.

Does nothing in the base class except display a debugging message warning
the user that the event does not contain the required functionality to
map this information. For events that do not store an objectid this won't
be called, so no debugging message will be displayed.

Example of usage:

return array('db' => 'assign_submissions', 'restore' => 'submission');

If the objectid can not be mapped during restore set the value to \core\event\base::NOT_MAPPED, example -

return array('db' => 'some_table', 'restore' => \core\event\base::NOT_MAPPED);

Note - it isn't necessary to specify the 'db' and 'restore' values in this case, so you can also use -

return \core\event\base::NOT_MAPPED;

The 'db' key refers to the database table and the 'restore' key refers to
the name of the restore element the objectid is associated with. In many
cases these will be the same.

return: string the name of the restore mapping the objectid links to

get_objectid_mapping()   X-Ref
No description

get_other_mapping()   X-Ref
This is used when restoring course logs where it is required that we
map the information in 'other' to it's new value in the new course.

Does nothing in the base class except display a debugging message warning
the user that the event does not contain the required functionality to
map this information. For events that do not store any other information this
won't be called, so no debugging message will be displayed.

Example of usage:

$othermapped = array();
$othermapped['discussionid'] = array('db' => 'forum_discussions', 'restore' => 'forum_discussion');
$othermapped['forumid'] = array('db' => 'forum', 'restore' => 'forum');
return $othermapped;

If an id can not be mapped during restore we set it to \core\event\base::NOT_MAPPED, example -

$othermapped = array();
$othermapped['someid'] = array('db' => 'some_table', 'restore' => \core\event\base::NOT_MAPPED);
return $othermapped;

Note - it isn't necessary to specify the 'db' and 'restore' values in this case, so you can also use -

$othermapped = array();
$othermapped['someid'] = \core\event\base::NOT_MAPPED;
return $othermapped;

The 'db' key refers to the database table and the 'restore' key refers to
the name of the restore element the other value is associated with. In many
cases these will be the same.

return: array an array of other values and their corresponding mapping

get_other_mapping()   X-Ref
No description

get_static_info()   X-Ref
Get static information about an event.
This is used in reports and is not for general use.

return: array Static information about the event.

get_explanation()   X-Ref
Get an explanation of what the class does.
By default returns the phpdocs from the child event class. Ideally this should
be overridden to return a translatable get_string style markdown.
e.g. return new lang_string('eventyourspecialevent', 'plugin_type');

return: string An explanation of the event formatted in markdown style.

get_context()   X-Ref
Returns event context.

return: \context

get_url()   X-Ref
Returns relevant URL, override in subclasses.

return: \moodle_url

get_data()   X-Ref
Return standardised event data as array.

return: array All elements are scalars except the 'other' field which is array.

get_logextra()   X-Ref
Return auxiliary data that was stored in logs.

List of standard properties:
- origin: IP number, cli,cron
- realuserid: id of the user when logged-in-as

return: array the format is standardised by logging API

get_legacy_eventname()   X-Ref
Does this event replace legacy event?

Note: do not use directly!

return: null|string legacy event name

get_legacy_eventdata()   X-Ref
Legacy event data if get_legacy_eventname() is not empty.

Note: do not use directly!

return: mixed

get_legacy_logdata()   X-Ref
Doest this event replace add_to_log() statement?

Note: do not use directly!

return: null|array of parameters to be passed to legacy add_to_log() function.

validate_before_trigger()   X-Ref
Validate all properties right before triggering the event.

This throws coding exceptions for fatal problems and debugging for minor problems.


trigger()   X-Ref
Trigger event.


is_triggered()   X-Ref
Was this event already triggered?

return: bool

is_dispatched()   X-Ref
Used from event manager to prevent direct access.

return: bool

is_restored()   X-Ref
Was this event restored?

return: bool

add_record_snapshot($tablename, $record)   X-Ref
Add cached data that will be most probably used in event observers.

This is used to improve performance, but it is required for data
that was just deleted.

param: string $tablename
param: \stdClass $record

get_record_snapshot($tablename, $id)   X-Ref
Returns cached record or fetches data from database if not cached.

param: string $tablename
param: int $id
return: \stdClass

__get($name)   X-Ref
Magic getter for read only access.

param: string $name
return: mixed

__set($name, $value)   X-Ref
Magic setter.

Note: we must not allow modification of data from outside,
after trigger() the data MUST NOT CHANGE!!!

param: string $name
param: mixed $value

__isset($name)   X-Ref
Is data property set?

param: string $name
return: bool

getIterator()   X-Ref
Create an iterator because magic vars can't be seen by 'foreach'.

return: \ArrayIterator

is_deprecated()   X-Ref
Whether this event has been marked as deprecated.

Events cannot be deprecated in the normal fashion as they must remain to support historical data.
Once they are deprecated, there is no way to trigger the event, so it does not make sense to list it in some
parts of the UI (e.g. Event Monitor).

return: boolean

Class: name  - X-Ref

create(array $data = null)   X-Ref
Create new event.

The optional data keys as:
1/ objectid - the id of the object specified in class name
2/ context - the context of this event
3/ other - the other data describing the event, can not contain objects
4/ relateduserid - the id of user which is somehow related to this event

param: array $data
return: \core\event\base returns instance of new event

validate_data()   X-Ref
Let developers validate their custom data (such as $this->data['other'], contextlevel, etc.).

Throw \coding_exception or debugging() notice in case of any problems.

get_name()   X-Ref
Returns localised general event name.

Override in subclass, we can not make it static and abstract at the same time.

return: string

get_name_with_info()   X-Ref
Returns the event name complete with metadata information.

This includes information about whether the event has been deprecated so should not be used in all situations -
for example within reports themselves.

If overriding this function, please ensure that you call the parent version too.

return: string

get_description()   X-Ref
Returns non-localised event description with id's for admin use only.

return: string

can_view($user_or_id = null)   X-Ref
This method was originally intended for granular
access control on the event level, unfortunately
the proper implementation would be too expensive
in many cases.

param: int|\stdClass $user_or_id ID of the user.
return: bool True if the user can view the event, false otherwise.

restore(array $data, array $logextra)   X-Ref
Restore event from existing historic data.

param: array $data
param: array $logextra the format is standardised by logging API
return: bool|\core\event\base

restore_unknown(array $data, array $logextra)   X-Ref
Restore unknown event.

param: array $data
param: array $logextra
return: unknown_logged

restore_legacy($legacy)   X-Ref
Create fake event from legacy log data.

param: \stdClass $legacy
return: base

get_objectid_mapping()   X-Ref
This is used when restoring course logs where it is required that we
map the objectid to it's new value in the new course.

Does nothing in the base class except display a debugging message warning
the user that the event does not contain the required functionality to
map this information. For events that do not store an objectid this won't
be called, so no debugging message will be displayed.

Example of usage:

return array('db' => 'assign_submissions', 'restore' => 'submission');

If the objectid can not be mapped during restore set the value to \core\event\base::NOT_MAPPED, example -

return array('db' => 'some_table', 'restore' => \core\event\base::NOT_MAPPED);

Note - it isn't necessary to specify the 'db' and 'restore' values in this case, so you can also use -

return \core\event\base::NOT_MAPPED;

The 'db' key refers to the database table and the 'restore' key refers to
the name of the restore element the objectid is associated with. In many
cases these will be the same.

return: string the name of the restore mapping the objectid links to

get_objectid_mapping()   X-Ref
No description

get_other_mapping()   X-Ref
This is used when restoring course logs where it is required that we
map the information in 'other' to it's new value in the new course.

Does nothing in the base class except display a debugging message warning
the user that the event does not contain the required functionality to
map this information. For events that do not store any other information this
won't be called, so no debugging message will be displayed.

Example of usage:

$othermapped = array();
$othermapped['discussionid'] = array('db' => 'forum_discussions', 'restore' => 'forum_discussion');
$othermapped['forumid'] = array('db' => 'forum', 'restore' => 'forum');
return $othermapped;

If an id can not be mapped during restore we set it to \core\event\base::NOT_MAPPED, example -

$othermapped = array();
$othermapped['someid'] = array('db' => 'some_table', 'restore' => \core\event\base::NOT_MAPPED);
return $othermapped;

Note - it isn't necessary to specify the 'db' and 'restore' values in this case, so you can also use -

$othermapped = array();
$othermapped['someid'] = \core\event\base::NOT_MAPPED;
return $othermapped;

The 'db' key refers to the database table and the 'restore' key refers to
the name of the restore element the other value is associated with. In many
cases these will be the same.

return: array an array of other values and their corresponding mapping

get_other_mapping()   X-Ref
No description

get_static_info()   X-Ref
Get static information about an event.
This is used in reports and is not for general use.

return: array Static information about the event.

get_explanation()   X-Ref
Get an explanation of what the class does.
By default returns the phpdocs from the child event class. Ideally this should
be overridden to return a translatable get_string style markdown.
e.g. return new lang_string('eventyourspecialevent', 'plugin_type');

return: string An explanation of the event formatted in markdown style.

get_context()   X-Ref
Returns event context.

return: \context

get_url()   X-Ref
Returns relevant URL, override in subclasses.

return: \moodle_url

get_data()   X-Ref
Return standardised event data as array.

return: array All elements are scalars except the 'other' field which is array.

get_logextra()   X-Ref
Return auxiliary data that was stored in logs.

List of standard properties:
- origin: IP number, cli,cron
- realuserid: id of the user when logged-in-as

return: array the format is standardised by logging API

get_legacy_eventname()   X-Ref
Does this event replace legacy event?

Note: do not use directly!

return: null|string legacy event name

get_legacy_eventdata()   X-Ref
Legacy event data if get_legacy_eventname() is not empty.

Note: do not use directly!

return: mixed

get_legacy_logdata()   X-Ref
Doest this event replace add_to_log() statement?

Note: do not use directly!

return: null|array of parameters to be passed to legacy add_to_log() function.

validate_before_trigger()   X-Ref
Validate all properties right before triggering the event.

This throws coding exceptions for fatal problems and debugging for minor problems.


trigger()   X-Ref
Trigger event.


is_triggered()   X-Ref
Was this event already triggered?

return: bool

is_dispatched()   X-Ref
Used from event manager to prevent direct access.

return: bool

is_restored()   X-Ref
Was this event restored?

return: bool

add_record_snapshot($tablename, $record)   X-Ref
Add cached data that will be most probably used in event observers.

This is used to improve performance, but it is required for data
that was just deleted.

param: string $tablename
param: \stdClass $record

get_record_snapshot($tablename, $id)   X-Ref
Returns cached record or fetches data from database if not cached.

param: string $tablename
param: int $id
return: \stdClass

__get($name)   X-Ref
Magic getter for read only access.

param: string $name
return: mixed

__set($name, $value)   X-Ref
Magic setter.

Note: we must not allow modification of data from outside,
after trigger() the data MUST NOT CHANGE!!!

param: string $name
param: mixed $value

__isset($name)   X-Ref
Is data property set?

param: string $name
return: bool

getIterator()   X-Ref
Create an iterator because magic vars can't be seen by 'foreach'.

return: \ArrayIterator

is_deprecated()   X-Ref
Whether this event has been marked as deprecated.

Events cannot be deprecated in the normal fashion as they must remain to support historical data.
Once they are deprecated, there is no way to trigger the event, so it does not make sense to list it in some
parts of the UI (e.g. Event Monitor).

return: boolean