phpBB-Extension entwickeln: Aufbau, Events und Migrationen

Eine phpBB-Extension ist ein eigenständiges Paket im Ordner ext/hersteller/name/, das sich über Events in das Forum einklinkt, ohne eine einzige Kerndatei zu verändern. Sie besteht aus einer composer.json, einer Service-Konfiguration, Event-Listenern für PHP und Templates sowie Migrationen, die Datenbank, Einstellungen und Rechte verwalten. Aktiviert wird sie im Administrationsbereich unter „Anpassen“.

Die Grundidee kennen Sie vielleicht aus WordPress: Auch dort klinken sich Plugins an festgelegten Stellen ein, siehe WordPress-Hooks erklärt. phpBB setzt dafür auf den Event-Dispatcher von Symfony.

Ordnerstruktur einer Extension

ext/beispiel/hinweisleiste/
├── composer.json
├── ext.php                      (optional)
├── config/
│   └── services.yml
├── event/
│   └── main_listener.php
├── migrations/
│   └── install_v100.php
├── language/
│   ├── de/common.php
│   └── en/common.php
└── styles/
    └── prosilver/template/event/
        └── overall_header_navigation_append.html

Hersteller- und Extension-Name werden kleingeschrieben und ohne Sonderzeichen gewählt. Aus ihnen ergibt sich der PHP-Namensraum, hier beispiel\hinweisleiste.

Die composer.json

{
  "name": "beispiel/hinweisleiste",
  "type": "phpbb-extension",
  "description": "Zeigt einen konfigurierbaren Hinweis in der Navigationsleiste.",
  "version": "1.0.0",
  "license": "GPL-2.0-only",
  "authors": [{ "name": "Beispiel" }],
  "require": { "php": ">=7.2" },
  "extra": {
    "display-name": "Hinweisleiste",
    "soft-require": { "phpbb/phpbb": ">=3.3.0,<4.0.0@dev" }
  }
}

Wichtig sind type mit dem Wert phpbb-extension und unter extra der Anzeigename sowie soft-require mit den unterstützten phpBB-Versionen. phpBB prüft diese Angaben, bevor sich die Extension aktivieren lässt. Die Lizenz sollte zur Lizenz von phpBB passen, das unter der GPL steht.

Services anmelden

phpBB nutzt einen Service-Container. Jede Klasse, die das Forum laden soll, wird in config/services.yml angemeldet, ihre Abhängigkeiten gibt der Container automatisch mit:

services:
    beispiel.hinweisleiste.listener:
        class: beispiel\hinweisleiste\event\main_listener
        arguments:
            - '@config'
            - '@template'
            - '@language'
        tags:
            - { name: event.listener }

Das Tag event.listener sorgt dafür, dass phpBB die Klasse beim Event-Dispatcher registriert.

PHP-Events: Logik einklinken

<?php
namespace beispiel\hinweisleiste\event;

use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class main_listener implements EventSubscriberInterface
{
    protected $config;
    protected $template;
    protected $language;

    public function __construct(\phpbb\config\config $config, \phpbb\template\template $template, \phpbb\language\language $language)
    {
        $this->config = $config;
        $this->template = $template;
        $this->language = $language;
    }

    public static function getSubscribedEvents()
    {
        return [
            'core.user_setup'  => 'sprache_laden',
            'core.page_header' => 'hinweis_setzen',
        ];
    }

    public function sprache_laden($event)
    {
        $this->language->add_lang('common', 'beispiel/hinweisleiste');
    }

    public function hinweis_setzen($event)
    {
        $this->template->assign_vars([
            'HINWEISLEISTE_TEXT' => $this->config['hinweisleiste_text'],
        ]);
    }
}

core.user_setup eignet sich, um eigene Sprachdateien zu laden. core.page_header läuft beim Aufbau jeder Seite und gibt hier eine Variable an die Templates weiter. Viele Events übergeben zusätzlich Daten, die Sie lesen und verändern können, etwa SQL-Abfragen oder Beitragsdaten. Geänderte Werte müssen Sie dabei in das Event-Objekt zurückschreiben, sonst gehen sie verloren.

Template-Events: Ausgabe einklinken

Für die Oberfläche bietet phpBB Template-Events. Eine Datei mit dem Namen des Events im Ordner styles/<stil>/template/event/ wird an der passenden Stelle eingefügt. Liegt sie unter styles/all/, gilt sie für alle Stile.

<!-- IF HINWEISLEISTE_TEXT -->
<li class="hinweisleiste">{HINWEISLEISTE_TEXT}</li>
<!-- ENDIF -->

So ergänzt die Extension die Navigationsleiste, ohne overall_header.html anzufassen. Bei einem Stil-Update bleibt die Ergänzung erhalten.

Migrationen: Datenbank, Einstellungen, Rechte

Migrationen sind PHP-Klassen, die Änderungen an Datenbank und Konfiguration versioniert beschreiben. phpBB merkt sich, welche bereits gelaufen sind.

<?php
namespace beispiel\hinweisleiste\migrations;

class install_v100 extends \phpbb\db\migration\migration
{
    public function effectively_installed()
    {
        return isset($this->config['hinweisleiste_text']);
    }

    public static function depends_on()
    {
        return ['\phpbb\db\migration\data\v330\v330'];
    }

    public function update_data()
    {
        return [
            ['config.add', ['hinweisleiste_text', '']],
            ['permission.add', ['a_hinweisleiste_verwalten']],
        ];
    }
}

Die wichtigsten Methoden:

Viele Datenänderungen wie config.add oder permission.add kann phpBB beim Löschen der Daten automatisch umkehren. Für eigene Tabellen beschreiben Sie in revert_schema() ausdrücklich, was entfernt werden soll. Für eine neue Version legen Sie eine neue Migration an, statt eine alte zu ändern, denn bereits gelaufene Migrationen werden nicht erneut ausgeführt.

Sprachdateien

Texte gehören nicht fest in den Code, sondern in Sprachdateien. Eine Datei language/de/common.php liefert ein Array mit Schlüsseln und Übersetzungen:

<?php
if (!defined('IN_PHPBB'))
{
    exit;
}

if (empty($lang) || !is_array($lang))
{
    $lang = [];
}

$lang = array_merge($lang, [
    'HINWEISLEISTE_TITEL'     => 'Hinweisleiste',
    'HINWEISLEISTE_TEXT_FELD' => 'Text der Hinweisleiste',
]);

Englisch gilt als Rückfallsprache und sollte immer vorhanden sein. Für die Customisation Database ist eine englische Sprachdatei Pflicht.

Ein Modul im Administrationsbereich

Damit Administratoren den Hinweistext ändern können, braucht die Extension eine Einstellungsseite. phpBB nennt solche Seiten Module. Eine Extension liefert dafür zwei Klassen im Ordner acp/: eine Info-Klasse, die Titel, Modus und benötigte Rechte beschreibt, und eine Modul-Klasse, die das Formular anzeigt und speichert. Angelegt wird das Modul über die Migration:

['module.add', ['acp', 'ACP_CAT_DOT_MODS', 'HINWEISLEISTE_TITEL']],
['module.add', ['acp', 'HINWEISLEISTE_TITEL', [
    'module_basename' => '\beispiel\hinweisleiste\acp\main_module',
    'modes'           => ['einstellungen'],
]]],

Die erste Zeile legt eine Kategorie im Reiter für Erweiterungen an, die zweite hängt das eigentliche Modul darunter. Beim Löschen der Daten entfernt phpBB die Module wieder.

Aktivieren, testen, aufräumen

1. Extension-Ordner nach ext/beispiel/hinweisleiste/ kopieren.
2. Im Administrationsbereich unter „Anpassen“ und „Erweiterungen verwalten“ die Extension aktivieren. Alternativ auf der Kommandozeile: php bin/phpbbcli.php extension:enable beispiel/hinweisleiste.
3. Nach Änderungen an Templates oder Services den Cache leeren, im Administrationsbereich oder mit php bin/phpbbcli.php cache:purge.
4. Deaktivieren und Daten löschen testen. Danach sollten keine Tabellen, Einstellungen oder Rechte der Extension zurückbleiben.

Entwickeln Sie in einer lokalen Testinstallation mit eingeschalteter Debug-Ausgabe, nicht im Live-Forum. Für automatisierte Tests bietet phpBB eine Testumgebung auf Basis von PHPUnit, in der sich auch Extensions prüfen lassen. Wer PHP, Composer oder Namensräume auffrischen möchte, findet die Basis in den Programmiergrundlagen.

Versionen und Kompatibilität

Geben Sie in soft-require nur die phpBB-Versionen an, mit denen Sie die Extension tatsächlich getestet haben. Kündigt phpBB eine neue Hauptversion an, prüfen Sie früh in einer Testinstallation, ob genutzte Events, Services und Template-Variablen weiterhin existieren. Über die Methode is_enableable() in der Datei ext.php kann eine Extension zusätzlich selbst prüfen, ob die Umgebung passt, etwa eine Mindestversion von PHP, und die Aktivierung andernfalls mit einer verständlichen Meldung verweigern. Das ist freundlicher als ein Fehler nach der Aktivierung.

Sicherheit in Extensions

• Eingaben über die Request-Klasse lesen: $request->variable('name', '') statt direkt $_GET oder $_POST. Der Standardwert bestimmt den erwarteten Typ.
• SQL-Werte absichern: Ganzzahlen typisieren, Zeichenketten mit $db->sql_escape() behandeln oder die Hilfsfunktionen zum Aufbau von Abfragen verwenden.
• Formulare schützen: add_form_key() beim Anzeigen und check_form_key() beim Absenden verhindern untergeschobene Anfragen.
• Rechte prüfen: $auth->acl_get('a_hinweisleiste_verwalten') vor jeder geschützten Aktion.
• Ausgabe maskieren: $request->variable() wandelt HTML-Sonderzeichen bereits beim Einlesen um. Werte aus anderen Quellen maskieren Sie vor der Übergabe an das Template selbst, und HTML reichen Sie nur bewusst und geprüft durch.

Veröffentlichen in der Customisation Database

phpBB.com betreibt eine Customisation Database für Extensions und Stile. Eingereichte Extensions werden vom Team geprüft, bevor sie dort erscheinen. Vor der Einreichung lohnt ein Lauf mit dem Extension Pre Validator (EPV), der typische formale Fehler findet: falsche Namensräume, fehlende Sprachdateien oder unsichere Funktionen. Wie sich Forenerweiterungen von den Datei-Mods der frühen Jahre bis zu heutigen Systemen entwickelt haben, zeigt der Artikel vBulletin, phpBB, Discourse: Geschichte der Forensoftware und ihrer Add-ons.