phpBB

Development Wiki

Difference between revisions of "Add Events"

From phpBB Development Wiki

(Triggering an event in PHP code)
(Triggering an event in PHP code)
Line 8: Line 8:
 
extract($phpbb_dispatcher->trigger_event('identifier', compact($vars)));
 
extract($phpbb_dispatcher->trigger_event('identifier', compact($vars)));
 
</php>
 
</php>
This piece of code wraps the two local variables `$var1` and `$var2` in an event object which is passed to all listeners registered for the `identifier` event. The listeners may then return an array of variables which will be extracted into local variables of the scope the event was triggered from. This allows listeners to overwrite or modify local variables in the scope of the event triggerer.
+
This piece of code wraps the two local variables <code>$var1</code> and <code>$var2</code> in an event object which is passed to all listeners registered for the <code>identifier</code> event. The listeners may then return an array of variables which will be extracted into local variables of the scope the event was triggered from. This allows listeners to overwrite or modify local variables in the scope of the event triggerer.
  
You will need to replace `identifier` with the name of your event. This should be prefixed by `core.` if it is an event in the core and not in your extension . You may have events in your extensions for other extensions to use. The identifier should be unique and only use underscores and lowercase letters for the prefix and name. Further you should replace `var1` and `var2` with the list of variables that are to be passed to listeners. Each of these variables should exist in the local scope where the event is triggered. You can pass any number of variables.
+
You will need to replace <code>identifier</code> with the name of your event. This should be prefixed by <code>core.</code> if it is an event in the core and not in your extension . You may have events in your extensions for other extensions to use. The identifier should be unique and use only underscores and lowercase letters for the prefix and name which have to be separated with a dot. Further you should replace <code>var1</code> and <code>var2</code> with the list of variables that are to be passed to listeners. Each of these variables should exist in the local scope where the event is triggered. You can pass any number of variables.
  
 
After creating an event please document it as described in the last section of this article.
 
After creating an event please document it as described in the last section of this article.
  
'''Note''' The `$phpbb_dispatcher` object is available from phpBB's dependency injection container or as a global variable, so if you do not pass it as a parameter to your method, use `global $phpbb_dispatcher` to make it available.
+
'''Note''' The <code>$phpbb_dispatcher</code> object is available from phpBB's dependency injection container or as a global variable, so if you do not pass it as a parameter to your method, use <code>global $phpbb_dispatcher</code> to make it available.
  
 
If an event does not need any arguments, you can use this short version:
 
If an event does not need any arguments, you can use this short version:

Revision as of 01:15, 18 October 2013

What are events?

When an extension wishes to hook its functionality into the phpBB core at a certain point, it can do so only where respective events are triggered. For more information, see the wiki article for listeners. Events are also known as hook location and previously ledges.

Triggering an event in PHP code

Adapt the following snippet of code to trigger an event in any PHP code.

$vars = array('var1''var2');
extract($phpbb_dispatcher->trigger_event('identifier'compact($vars)));

This piece of code wraps the two local variables $var1 and $var2 in an event object which is passed to all listeners registered for the identifier event. The listeners may then return an array of variables which will be extracted into local variables of the scope the event was triggered from. This allows listeners to overwrite or modify local variables in the scope of the event triggerer.

You will need to replace identifier with the name of your event. This should be prefixed by core. if it is an event in the core and not in your extension . You may have events in your extensions for other extensions to use. The identifier should be unique and use only underscores and lowercase letters for the prefix and name which have to be separated with a dot. Further you should replace var1 and var2 with the list of variables that are to be passed to listeners. Each of these variables should exist in the local scope where the event is triggered. You can pass any number of variables.

After creating an event please document it as described in the last section of this article.

Note The $phpbb_dispatcher object is available from phpBB's dependency injection container or as a global variable, so if you do not pass it as a parameter to your method, use global $phpbb_dispatcher to make it available.

If an event does not need any arguments, you can use this short version:

extract($phpbb_dispatcher->dispatch('identifer'));

Triggering an event in a template

Add the following code to a template:

<!-- EVENT identifier -->

Replace the identifier with the name of the listener. Make sure to only use underscores, numbers and lowercase letters.

That's it! You've created an event and should document it as described below.

Core events List

If you add an event to phpBB rather than one of your own templates, it must be added to the events list.

You can view and edit the events list here

Examples of events being added