Search moodle.org's
Developer Documentation
Developer Documentation
See Release Notes
Long Term Support Release
- Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
- Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
- PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.
/lib/classes/event/ -> base.php (source)
Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 400 and 401] [Versions 401 and 402] [Versions 401 and 403]
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: | 1004 lines (36 kb) |
| Included or required: | 1 time |
| Referenced: | 0 times |
| Includes or requires: | 0 files |
Defines 3 classes
base:: (1 method):
__construct()
name:: (34 methods):
create()
validate_data()
get_name()
get_name_with_info()
get_description()
can_view()
restore()
restore_unknown()
restore_legacy()
get_objectid_mapping()
get_objectid_mapping()
get_other_mapping()
get_other_mapping()
get_static_info()
get_explanation()
get_context()
get_url()
get_data()
get_logextra()
get_legacy_eventname()
get_legacy_eventdata()
get_legacy_logdata()
validate_before_trigger()
trigger()
is_triggered()
is_dispatched()
is_restored()
add_record_snapshot()
get_record_snapshot()
__get()
__set()
__isset()
getIterator()
is_deprecated()
name:: (34 methods):
create()
validate_data()
get_name()
get_name_with_info()
get_description()
can_view()
restore()
restore_unknown()
restore_legacy()
get_objectid_mapping()
get_objectid_mapping()
get_other_mapping()
get_other_mapping()
get_static_info()
get_explanation()
get_context()
get_url()
get_data()
get_logextra()
get_legacy_eventname()
get_legacy_eventdata()
get_legacy_logdata()
validate_before_trigger()
trigger()
is_triggered()
is_dispatched()
is_restored()
add_record_snapshot()
get_record_snapshot()
__get()
__set()
__isset()
getIterator()
is_deprecated()
All other event classes must extend this class.
| __construct() X-Ref |
| Private constructor, use create() or restore() methods instead. |
| 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 |
| 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 |
