From ccc3f56743da4fe1656d4a9edf298de9cb49f968 Mon Sep 17 00:00:00 2001 From: rxu Date: Sat, 14 Jun 2025 23:24:37 +0700 Subject: [PATCH 1/3] Add template event listener prioritizing docs. Requires https://github.com/phpbb/phpbb/pull/6770 to get merged. --- development/extensions/tutorial_events.rst | 67 ++++++++++++++++++++-- 1 file changed, 61 insertions(+), 6 deletions(-) diff --git a/development/extensions/tutorial_events.rst b/development/extensions/tutorial_events.rst index 9ea6a471..641a9efa 100644 --- a/development/extensions/tutorial_events.rst +++ b/development/extensions/tutorial_events.rst @@ -82,13 +82,68 @@ text ``DEMO_PAGE``. We will fix the link text in the next section. ``config.php`` file, which will force the template engine to always look for template listeners when a page is being rendered. -It's important to understand that when phpBB compiles the templates, -there is no current system for determining the priority in which template -listeners from different extensions subscribed to the same event are -compiled. In rare cases some extensions could cause a conflict, in which case -the recommendation is for the extension authors to work together on a solution for their -conflicting template listeners. +Prioritising template event listeners (optional) +--------------------------------------- + +In rare cases, some extensions could cause a conflict when template listeners +from different extensions are subscribed to the same template event. In such cases +phpBB allows to assign the priority to template event listeners, which allows +to determine the order template event listeners will be compiled. +This can be accomplished using PHP core event listener subscribed to the +``core.twig_event_tokenparser_constructor`` core event, which should use +``template_event_priority_array`` array variable to assign the template event listener priority. +``template_event_priority_array`` array has the following format: + +:: + + '_' => [ + 'event/' => , + ], + +Example: + +.. code-block:: php + + 'set_template_event_priority', + ]; + } + /** + * Assign priority to template event listener + * + * @param \phpbb\event\data $event The event object + */ + public function set_template_event_priority($event) + { + $template_event_priority_array = $event['template_event_priority_array']; + $template_event_priority_array['acme_demo'] = [ + 'event/navbar_header_quick_links_after' => $priority, + ]; + $event['template_event_priority_array'] = $template_event_priority_array; + } + } + +In this example, ``$priority`` is an integer, the value of which defaults to 0. +Setting this integer to higher values equals more importance and therefore that +template event listener will be compiled earlier than others subscribed to the same template event. +In case of equal priority values, template event listeners will be compiled in the order +they have been read from their locations. PHP Core Events & Listeners =========================== From ca4d3b7ffc5ebef03cb00d4b5bfdd889db10f33a Mon Sep 17 00:00:00 2001 From: rxu Date: Sat, 14 Jun 2025 23:46:02 +0700 Subject: [PATCH 2/3] Adjust terms. --- development/extensions/tutorial_events.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/development/extensions/tutorial_events.rst b/development/extensions/tutorial_events.rst index 641a9efa..9ebac10c 100644 --- a/development/extensions/tutorial_events.rst +++ b/development/extensions/tutorial_events.rst @@ -96,7 +96,7 @@ This can be accomplished using PHP core event listener subscribed to the :: - '_' => [ + '_' => [ 'event/' => , ], From a30511f4707771549c0b13e17aca999bf04bc01b Mon Sep 17 00:00:00 2001 From: rxu Date: Sun, 15 Jun 2025 01:11:10 +0700 Subject: [PATCH 3/3] Address review issues. --- development/extensions/tutorial_events.rst | 47 ++++++++-------------- 1 file changed, 17 insertions(+), 30 deletions(-) diff --git a/development/extensions/tutorial_events.rst b/development/extensions/tutorial_events.rst index 9ebac10c..a584800d 100644 --- a/development/extensions/tutorial_events.rst +++ b/development/extensions/tutorial_events.rst @@ -83,22 +83,15 @@ text ``DEMO_PAGE``. We will fix the link text in the next section. look for template listeners when a page is being rendered. Prioritising template event listeners (optional) ---------------------------------------- - -In rare cases, some extensions could cause a conflict when template listeners -from different extensions are subscribed to the same template event. In such cases -phpBB allows to assign the priority to template event listeners, which allows -to determine the order template event listeners will be compiled. -This can be accomplished using PHP core event listener subscribed to the -``core.twig_event_tokenparser_constructor`` core event, which should use -``template_event_priority_array`` array variable to assign the template event listener priority. -``template_event_priority_array`` array has the following format: +------------------------------------------------ -:: +In rare cases, conflicts may occur when multiple extensions subscribe to the same template +event using template listeners. To resolve such conflicts, phpBB allows you to control the +order in which template event listeners are compiled by assigning them priorities. - '_' => [ - 'event/' => , - ], +This is done by subscribing a PHP event listener to the +``core.twig_event_tokenparser_constructor`` event and using the +``template_event_priority_array`` variable to define listener priorities. Example: @@ -112,11 +105,7 @@ Example: class main_listener implements EventSubscriberInterface { - /** - * Assign functions defined in this class to event listeners in the core - * - * @return array - */ + // Subscribe an event listener function to the core.twig_event_tokenparser_constructor static public function getSubscribedEvents() { return [ @@ -124,26 +113,24 @@ Example: ]; } - /** - * Assign priority to template event listener - * - * @param \phpbb\event\data $event The event object - */ + // Give your extension a high priority when rendering the navbar_header_quick_links_after template event. public function set_template_event_priority($event) { $template_event_priority_array = $event['template_event_priority_array']; $template_event_priority_array['acme_demo'] = [ - 'event/navbar_header_quick_links_after' => $priority, + 'event/navbar_header_quick_links_after' => 100, ]; $event['template_event_priority_array'] = $template_event_priority_array; } } -In this example, ``$priority`` is an integer, the value of which defaults to 0. -Setting this integer to higher values equals more importance and therefore that -template event listener will be compiled earlier than others subscribed to the same template event. -In case of equal priority values, template event listeners will be compiled in the order -they have been read from their locations. +In this example, ``100`` is an integer implying the template event priority. Higher values +indicate greater importance, meaning the corresponding template event listener +will be compiled earlier than others listening to the same event. +For example, the content of template event listener which has a priority value of ``100`` +will be rendered above/before the same template event listener which has a priority value of ``99``. +If multiple listeners share the same priority value, they will be rendered in the order they were read +from their respective filesystem locations. If no priority value set, it defaults to ``0``. PHP Core Events & Listeners ===========================