Wykorzystanie systemu event listenerów w phpBB – jak „podłączyć się” do działania forum

Jednym z najpotężniejszych narzędzi, jakie oferuje phpBB, jest system event listenerów – mechanizm pozwalający na modyfikowanie zachowania forum bez edytowania jego kodu źródłowego.
To właśnie dzięki eventom rozszerzenia mogą dodawać własne funkcje, zmieniać wygląd, przetwarzać dane użytkowników czy reagować na określone akcje, takie jak logowanie, rejestracja czy publikacja posta.

W tym poradniku wyjaśnię krok po kroku, czym są eventy, jak działają i jak wykorzystać je w praktyce, by stworzyć czyste i bezpieczne modyfikacje w phpBB.

Czym jest event listener?

W prostych słowach, event listener to fragment kodu, który „nasłuchuje” określonego zdarzenia w phpBB.
Gdy takie zdarzenie nastąpi, listener wykonuje zaprogramowaną akcję.

Eventy są częścią systemu Symfony Event Dispatcher, z którego korzysta phpBB.
Dzięki temu możesz rozszerzyć lub zmienić zachowanie forum w dowolnym momencie – bez potrzeby edytowania plików rdzenia.

Każde zdarzenie ma swoją unikalną nazwę, np.:

core.user_add_after – wywoływane po utworzeniu nowego użytkownika,
core.posting_modify_submit_post_before – przed zapisaniem nowego posta,
core.viewtopic_modify_post_row – podczas generowania widoku posta,
core.page_header – przy ładowaniu nagłówka strony.

Dlaczego warto korzystać z event listenerów?

Zamiast modyfikować pliki systemowe (co jest ryzykowne i utrudnia aktualizacje), eventy pozwalają:

dodawać funkcje niezależnie od kodu phpBB,
przechwytywać dane i je zmieniać,
rozszerzać istniejące procesy (np. logowanie, rejestracja),
utrzymywać pełną kompatybilność z przyszłymi aktualizacjami.

To oficjalny i wspierany sposób modyfikacji phpBB — dlatego każda dobra wtyczka działa właśnie w oparciu o eventy.

1. Struktura listenera w rozszerzeniu

Załóżmy, że chcemy stworzyć prosty listener, który po każdym dodaniu użytkownika zapisze informację w logu forum.

Struktura rozszerzenia wygląda tak:

/ext/example/eventdemo/
├── composer.json
├── ext.php
└── event/
    └── main_listener.php

Plik composer.json:

{
    "name": "example/eventdemo",
    "type": "phpbb-extension",
    "description": "Przykład użycia event listenera w phpBB.",
    "version": "1.0.0",
    "time": "2025-10-22",
    "license": "GPL-2.0",
    "authors": [
        {
            "name": "phpBB3-Mods.pl"
        }
    ],
    "extra": {
        "display-name": "Event Demo",
        "soft-require": {
            "phpbb/phpbb": ">=3.3.0"
        }
    }
}

Plik ext.php:

<?php
namespace example\eventdemo;

class ext extends \phpbb\extension\base {}

2. Tworzenie pliku event listenera

W katalogu /event/ tworzymy plik main_listener.php:

<?php
namespace example\eventdemo\event;

use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class main_listener implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [
            'core.user_add_after' => 'log_new_user'
        ];
    }

    protected $user;
    protected $log;

    public function __construct(\phpbb\user $user, \phpbb\log\log $log)
    {
        $this->user = $user;
        $this->log = $log;
    }

    public function log_new_user($event)
    {
        $username = $event['user_row']['username'];
        $this->log->add('admin', $this->user->data['user_id'], $this->user->ip, "Dodano nowego użytkownika: $username");
    }
}

Jak to działa?

phpBB wywołuje event core.user_add_after po zakończeniu rejestracji nowego użytkownika.
Listener main_listener przechwytuje to zdarzenie i wykonuje funkcję log_new_user().
Zmienna $event zawiera dane użytkownika, które możemy odczytać lub modyfikować.
W tym przykładzie funkcja zapisuje informację do logów ACP.

Efekt: po każdym nowym rejestrującym się użytkowniku, w panelu administracyjnym pojawi się nowy wpis w logach.

3. Przykład modyfikacji danych z eventu

Niektóre eventy pozwalają nie tylko reagować, ale też modyfikować dane, zanim zostaną zapisane.

Weźmy event core.posting_modify_submit_post_before – wywoływany tuż przed zapisaniem posta w bazie danych.

Dzięki niemu możemy np. automatycznie dodać podpis do każdego posta:

public static function getSubscribedEvents()
{
    return [
        'core.posting_modify_submit_post_before' => 'modify_post_content'
    ];
}

public function modify_post_content($event)
{
    $data = $event['data'];
    $data['message'] .= "\n\n[color=gray]Post automatycznie oznaczony przez system.[/color]";
    $event['data'] = $data;
}

phpBB zapisze zmienioną treść, bo $event['data'] przekazywane jest dalej do systemu zapisu posta.

4. Wykorzystanie wielu eventów w jednym listenerze

Możesz nasłuchiwać dowolnej liczby zdarzeń w jednym pliku.
Przykład:

public static function getSubscribedEvents()
{
    return [
        'core.user_add_after' => 'log_new_user',
        'core.posting_modify_submit_post_before' => 'modify_post_content',
        'core.page_header' => 'add_template_variable'
    ];
}

A następnie definiujesz trzy osobne funkcje.
W praktyce wiele dużych rozszerzeń phpBB (np. Cleantalk, SEO Ultimate) działa właśnie w ten sposób — reagując na różne zdarzenia w całym cyklu życia strony.

5. Dodawanie zmiennych do szablonu przez eventy

Dzięki eventom możesz też przekazywać dane do szablonów Twig, np. dodać własną zmienną w nagłówku strony:

public function add_template_variable($event)
{
    global $template;
    $template->assign_var('CUSTOM_MESSAGE', 'Witaj na forum phpBB3-Mods.pl!');
}

A następnie w pliku szablonu (overall_header.html) możesz ją wyświetlić:

<p class="custom-message">{CUSTOM_MESSAGE}</p>

To sposób na dynamiczne dodawanie elementów bez edycji plików rdzenia.

6. Gdzie znaleźć listę dostępnych eventów?

Oficjalna dokumentacja phpBB udostępnia pełną listę eventów dla każdej wersji:
👉 https://area51.phpbb.com/docs/dev/3.3.x/events/

Eventy są podzielone na kategorie:

core.* – logika silnika forum,
ucp.* – panel użytkownika,
acp.* – panel administratora,
posting.* – tworzenie i edycja postów,
viewtopic.* – generowanie strony tematu,
memberlist.* – obsługa profili użytkowników.

Każdy event ma opis argumentów $event, które można odczytywać i modyfikować.

7. Debugowanie eventów

Aby łatwiej zrozumieć, które eventy są wywoływane na danej stronie, możesz tymczasowo dodać w listenerze:

error_log("Event wywołany: " . __FUNCTION__);

Dzięki temu zobaczysz w logu serwera, które eventy zostały aktywowane i w jakiej kolejności.
To świetny sposób na poznanie „mapy zdarzeń” phpBB.

8. Dobre praktyki przy pracy z eventami

Nie modyfikuj plików rdzenia. Używaj tylko eventów i API.
Nazwy funkcji listenerów powinny jasno wskazywać, do czego służą.
Nie nadużywaj eventów – każdy listener to dodatkowe wywołanie PHP, więc nie uruchamiaj ich bez potrzeby.
Czyszcz cache po każdej zmianie w plikach eventów. phpBB buforuje definicje klas.
Dokumentuj eventy, z których korzystasz – ułatwi to przyszłą aktualizację forum.

9. Co dalej?

Po opanowaniu podstaw możesz:

tworzyć własne eventy w swoich rozszerzeniach (np. example.simplefooter.event.custom_action),
łączyć eventy z panelami ACP lub własnymi API,
budować bardziej złożone systemy reakcji (np. logi, powiadomienia, punkty, integracje).

System eventów to potężne narzędzie, które sprawia, że phpBB staje się platformą naprawdę elastyczną.

Podsumowanie

Event listenery to fundament nowoczesnego systemu rozszerzeń phpBB.
Pozwalają modyfikować forum bez grzebania w jego kodzie, co gwarantuje bezpieczeństwo, kompatybilność i łatwość aktualizacji.

W tym poradniku nauczyłeś się:

jak stworzyć listener,
jak reagować na konkretne zdarzenia,
jak modyfikować dane przed zapisaniem,
jak dodać własne zmienne do szablonów.

Dzięki temu możesz teraz tworzyć własne, w pełni zgodne z systemem modyfikacje – tak jak robią to profesjonalni twórcy rozszerzeń dla phpBB.