[GitHub/WoltLab/woltlab.github.io.git] / docs / package / pip / event-listener.md

# Event Listener Package Installation Plugin

Registers event listeners.
An explanation of events and event listeners can be found [here](../../php/api/events.md).

## Components

Each event listener is described as an `<eventlistener>` element with a `name` attribute.
As the `name` attribute has only be introduced with WSC 3.0, it is not yet mandatory to allow backwards compatibility.
If `name` is not given, the system automatically sets the name based on the id of the event listener in the database.

### `<eventclassname>`

The event class name is the name of the class in which the event is fired.

### `<eventname>`

The event name is the name given when the event is fired to identify different events within the same class.
You can either give a single event name or a comma-separated list of event names in which case the event listener listens to all of the listed events.

### `<listenerclassname>`

The listener class name is the name of the class which is triggered if the relevant event is fired.
The PHP class has to implement the `wcf\system\event\listener\IParameterizedEventListener` interface.

!!! warning "Legacy event listeners are only required to implement the deprecated `wcf\system\event\IEventListener` interface. When writing new code or update existing code, you should always implement the `wcf\system\event\listener\IParameterizedEventListener` interface!"

### `<inherit>`

The inherit value can either be `0` (default value if the element is omitted) or `1` and determines if the event listener is also triggered for child classes of the given event class name.
This is the case if `1` is used as the value.

### `<environment>`

The value of the environment element must be one of `user`, `admin` or `all` and defaults to `user` if no value is given.
The value determines if the event listener will be executed in the frontend (`user`), the backend (`admin`) or both (`all`).

### `<nice>`

The nice value element can contain an integer value out of the interval `[-128,127]` with `0` being the default value if the element is omitted.
The nice value determines the execution order of event listeners.
Event listeners with smaller nice values are executed first.
If the nice value of two event listeners is equal, they are sorted by the listener class name.

!!! info "If you pass a value out of the mentioned interval, the value will be adjusted to the closest value in the interval."

### `<options>`

The options element can contain a comma-separated list of options of which at least one needs to be enabled for the event listener to be executed.

### `<permissions>`

The permissions element can contain a comma-separated list of permissions of which the active user needs to have at least one for the event listener to be executed.


## Example

{jinja{ codebox(
  title="eventListener.xml",
  language="xml",
  filepath="package/pip/eventListener.xml"
) }}
Commit	Line	Data
8659eb86	1	# Event Listener Package Installation Plugin
a58ecf9e MS	2
a58ecf9e MS	3	Registers event listeners.
21609ed2	4	An explanation of events and event listeners can be found [here](../../php/api/events.md).
a58ecf9e MS	5
	6	## Components
	7
	8	Each event listener is described as an `<eventlistener>` element with a `name` attribute.
	9	As the `name` attribute has only be introduced with WSC 3.0, it is not yet mandatory to allow backwards compatibility.
	10	If `name` is not given, the system automatically sets the name based on the id of the event listener in the database.
	11
	12	### `<eventclassname>`
	13
	14	The event class name is the name of the class in which the event is fired.
	15
	16	### `<eventname>`
	17
	18	The event name is the name given when the event is fired to identify different events within the same class.
	19	You can either give a single event name or a comma-separated list of event names in which case the event listener listens to all of the listed events.
	20
	21	### `<listenerclassname>`
	22
	23	The listener class name is the name of the class which is triggered if the relevant event is fired.
	24	The PHP class has to implement the `wcf\system\event\listener\IParameterizedEventListener` interface.
	25
9003992d	26	!!! warning "Legacy event listeners are only required to implement the deprecated `wcf\system\event\IEventListener` interface. When writing new code or update existing code, you should always implement the `wcf\system\event\listener\IParameterizedEventListener` interface!"
a58ecf9e MS	27
	28	### `<inherit>`
	29
	30	The inherit value can either be `0` (default value if the element is omitted) or `1` and determines if the event listener is also triggered for child classes of the given event class name.
	31	This is the case if `1` is used as the value.
	32
	33	### `<environment>`
	34
ae06654c TD	35	The value of the environment element must be one of `user`, `admin` or `all` and defaults to `user` if no value is given.
ae06654c TD	36	The value determines if the event listener will be executed in the frontend (`user`), the backend (`admin`) or both (`all`).
a58ecf9e	37
ef7ce04c	38	### `<nice>`
a58ecf9e MS	39
	40	The nice value element can contain an integer value out of the interval `[-128,127]` with `0` being the default value if the element is omitted.
	41	The nice value determines the execution order of event listeners.
	42	Event listeners with smaller nice values are executed first.
	43	If the nice value of two event listeners is equal, they are sorted by the listener class name.
	44
9003992d	45	!!! info "If you pass a value out of the mentioned interval, the value will be adjusted to the closest value in the interval."
a58ecf9e MS	46
	47	### `<options>`
	48
	49	The options element can contain a comma-separated list of options of which at least one needs to be enabled for the event listener to be executed.
	50
	51	### `<permissions>`
	52
	53	The permissions element can contain a comma-separated list of permissions of which the active user needs to have at least one for the event listener to be executed.
	54
	55
	56	## Example
	57
9a3f5fa3	58	{jinja{ codebox(
f778fce2 MS	59	title="eventListener.xml",
	60	language="xml",
	61	filepath="package/pip/eventListener.xml"
9a3f5fa3	62	) }}