API-Referenz: Erweiterungspunkte

Diese Seite ist der vollständige Katalog der Erweiterungspunkte der WvdS-DW-Suite. Sie nennt für jeden öffentlichen Punkt Zweck, Lebenszyklus, Ein- und Ausgaben, Fehlerverhalten, Berechtigungen, ein lauffähiges Minimalbeispiel und die Regel, nach der er sich versionieren darf — und sie trennt ausdrücklich, was öffentlicher Contract ist und was interne Umsetzung.

Was diese Seite besitzt und was nicht. Diese Seite besitzt die paketübergreifende Sicht: welche Erweiterungspunkte es gibt, welche Stufe sie tragen, wie man sie anspricht. Die vollständige Behandlung eines einzelnen Contracts — jedes Feld, jede Messung, jede Begründung — bleibt bei dem Paket, dem er gehört; jeder Abschnitt verweist darauf. Werte werden hier nicht zweitverwaltet.

Die PHP-Sichtbarkeit einer Methode entscheidet nicht, ob sie Contract ist. Mehrere Klassen der Suite haben public-Methoden, die ausschließlich für eigene Bildschirme desselben Pakets gedacht sind. Verbindlich ist ausschließlich diese Tabelle.

Fünf entenartig typisierte Methoden, die der Workbench-Contract v1 ablöst. Ein Anpassungsstück (helper_plugin_wkfluentui_legacyadapter) übersetzt sie weiterhin in dieselbe Form, sodass bestehende Pakete unverändert laufen. Einzelheiten stehen weiter unten unter „Veraltete Mechanismen„.

Diese Klassen und Methoden sind kein Contract, auch wo sie public sind. Sie dürfen sich ohne Ankündigung ändern.

Die Stufe eines Ereignisses steht maschinenlesbar im catalog() seines Trägers, nicht in dieser Tabelle: lib/plugins/wkcore/Events.php, lib/plugins/wkdocore/Events.php, lib/plugins/wksourceview/Events.php.

Jedes Paket ist ein eigenes Repository mit eigenem Manifest. plugin.info.txt hat kein Feld für eine semantische Version; das Feld date ist der Versionsstempel — es ist der Wert, den Erweiterungsmanager und dokuwiki.org vergleichen, um ein Update zu erkennen. Ein Paket mit stehendem Datum meldet sich als die Fassung von damals und wird nie als Update angeboten.

Folgerung für Sie: Fragen Sie nie eine Version ab, um eine Fähigkeit zu erschließen. Es gibt keine Zahl, die das beantworten könnte.

Der einzige zugesicherte Weg, vor der Benutzung nach einer Fähigkeit zu fragen, ist ein Name:

$caps = plugin_load('helper', 'wkfluentui_capabilities');
if ($caps !== null && $caps->has('workbench.contribution.bottomPanel')) { /* … */ }

Warum kein Versionsvergleich genügt, ist an dieser Suite gemessen: Der untere Panelbereich existierte in der Ablage und im Raster, lange bevor der zusammensetzende Teil ihn weiterreichte. Eine Versions- oder method_exists()-Prüfung hätte die ganze Zeit „vorhanden“ gemeldet, während er in jeder Anfrage, auf die es ankam, abwesend war. Der Fähigkeitsname wurde erst mit der Änderung wahr, die den Bereich tatsächlich funktionsfähig machte.

1. Die Endung .v1 markiert das Bruchrisiko. Namen, die später eine unverträgliche zweite Fassung bekommen können — eine Beitragsart, eine Form der Berechtigungsangabe, die Bedeutung einer Identitätsforderung — tragen die Endung. Ein altes Paket fragt für immer nach .v1 und bekommt auch dann eine wahrheitsgemäße Antwort, wenn .v2 daneben existiert.
2. Reine Vokabularnamen tragen keine Version. Region-, Befehls- und Tonnamen wachsen additiv. Ein unbekannter Wert wird verworfen, nie fatal — diese Toleranz nimmt additives Wachstum ohne Versionssprung auf.
3. Bei gleicher Kennung gewinnt der spätere Eintrag. Das gilt für Workbench-Beiträge, Hubs, Quelltext-Provider und Repositoriumsquellen gleichermaßen. Wer eine Kennung eines anderen Pakets wiederverwendet, ersetzt dessen Eintrag.
4. Neue Pflichtfelder sind ein Bruch, neue Kannfelder nicht. Jedes Feld eines Descriptors hat eine Vorgabe, die nichts verändert. Ein Feld hinzuzufügen ist deshalb verträglich; eines zur Pflicht zu machen, ist es nicht.

Es gibt in dieser Installation keinen Deinstallationshaken — auch DokuWiki selbst hat keinen: der Erweiterungsmanager löscht das Verzeichnis unmittelbar. Ein entferntes oder abgeschaltetes Plugin wird von plugin_list() nicht mehr genannt, sein Haken feuert nicht mehr, und das Register enthält bei der nächsten Anfrage keinen Eintrag dieses Eigentümers. Das ist kein Aufräumen, sondern eine Eigenschaft der Bauform: die Register rechnen bei jeder Anfrage neu und schreiben nichts fort.

Was ein Verbraucher eines Beitrags sich merkt — die bevorzugte Region einer Ansicht, die Reihenfolge einer Leiste — ist davon getrennt und trägt seine eigene Regel, veraltete Einträge zu dulden und zu deckeln.

$controller->register_hook('WKCORE_REGISTER_SERVICES', 'BEFORE', $this, 'registerServices');
 
public function registerServices(Event $event): void;
// $event->data === helper_plugin_wkcore

Quelle: lib/plugins/wkcore/helper.php, lib/plugins/wkcore/Events.php

Veröffentlicht ein Objekt oder einen Wert unter einer Zeichenketten-Kennung im Dienstregister der Suite, damit andere Pakete es benutzen können, ohne Ihr Paket zu kennen.

$event→data ist die Registerinstanz. Sie rufen darauf:

Kennungen sind flach und nur per Konvention namensraumiert (Bereich, Punkt, Dienst — etwa storage.sqlite). Eine Kennung darf nicht leer sein.

Kein Rückgabewert. Verbraucher lesen anschließend:

Das Register ist kein Behälter für Abhängigkeitsinjektion: keine automatische Verdrahtung, keine Reflexion über Konstruktoren, kein Konfigurationsformat.

Ein Paket veröffentlicht einen eigenen Dienst und benutzt einen fremden.

<?php
 
use dokuwiki\Extension\ActionPlugin;
use dokuwiki\Extension\EventHandler;
use dokuwiki\Extension\Event;
 
class action_plugin_wkexample extends ActionPlugin
{
    public function register(EventHandler $controller)
    {
        // Ausgeschrieben, nicht als Konstante: wkcore kann fehlen.
        $controller->register_hook('WKCORE_REGISTER_SERVICES', 'BEFORE', $this, 'registerServices');
    }
 
    public function registerServices(Event $event)
    {
        $registry = $event->data;
        if (!is_object($registry) || !method_exists($registry, 'registerFactory')) {
            return;   // fremde Nutzlast: nichts tun, nie annehmen
        }
 
        // Träge: erst beim ersten get() gebaut.
        $registry->registerFactory('example.reports', static function ($reg) {
            $storage = $reg->has('storage.sqlite') ? $reg->get('storage.sqlite') : null;
            return new \dokuwiki\plugin\wkexample\ReportService($storage);
        });
    }
 
    /** So benutzt ein Verbraucher einen fremden Dienst. */
    public function readVaultSecret(string $id): ?array
    {
        $core = plugin_load('helper', 'wkcore');
        if ($core === null || !$core->has('vault.secrets')) {
            return null;   // Paket abwesend: Funktion fehlt, nichts stürzt ab
        }
        return $core->get('vault.secrets')->read($id);
    }
}

Wird von helper_plugin_wkcore::bootstrap() gefeuert. Läuft vor WKCORE_READY. Die belegten Kennungen stehen weiter unten im Dienstregister.

$controller->register_hook('WKCORE_READY', 'BEFORE', $this, 'onCoreReady');
 
public function onCoreReady(Event $event): void;
// $event->data === helper_plugin_wkcore

Quelle: lib/plugins/wkcore/Events.php

Meldet, dass die Registrierungsrunde abgeschlossen ist und das Register gefahrlos abgefragt werden darf.

Die Registerinstanz, vollständig befüllt.

Kein Rückgabewert. Der Haken beobachtet; er trägt nichts bei.

Registrieren Sie hier nicht. Zu diesem Zeitpunkt können Verbraucher bereits gelesen haben; eine Registrierung käme für sie zu spät.

public function register(EventHandler $controller)
{
    $controller->register_hook('WKCORE_READY', 'BEFORE', $this, 'onCoreReady');
}
 
public function onCoreReady(Event $event)
{
    $registry = $event->data;
    if (!is_object($registry) || !method_exists($registry, 'has')) {
        return;
    }
    // Eine Fähigkeit einmal je Anfrage feststellen, statt an jeder Aufrufstelle.
    $this->hasVault = $registry->has('vault.secrets');
}

Folgt auf WKCORE_REGISTER_SERVICES. Nutzlast identisch.

$controller->register_hook('WKCORE_CONTEXT_BUILD', 'BEFORE', $this, 'enrichContext');
 
public function enrichContext(Event $event): void;
// $event->data === dokuwiki\plugin\wkcore\Context

Quelle: lib/plugins/wkcore/Context.php, lib/plugins/wkcore/action.php

Hängt einen eigenen, typisierten Teilkontext an die Anfrage-Momentaufnahme, ohne dass Context Ihr Paket kennen muss.

$event→data ist die Context-Instanz. Sie rufen darauf setExtension(string $name, mixed $context). Der Name ist konventionell namensraumiert, etwa dwdo.project.

Lesbar sind auf derselben Instanz unter anderem user(), userName(), groups(), pageId(), namespace(), action(), language() und permission() — die aufgelöste ACL-Stufe als AUTH-Konstante.

Kein Rückgabewert. Ihr Teilkontext ist anschließend über die Context-Instanz erreichbar, die get('core.context') liefert.

Lösen Sie aus diesem Haken heraus keine erneute Auflösung von core.context aus — das Ereignis feuert, während dieser Dienst gerade aufgelöst wird; ein erneuter Zugriff läuft in eine Rekursion.

public function register(EventHandler $controller)
{
    $controller->register_hook('WKCORE_CONTEXT_BUILD', 'BEFORE', $this, 'enrichContext');
}
 
public function enrichContext(Event $event)
{
    $ctx = $event->data;
    if (!is_object($ctx) || !method_exists($ctx, 'setExtension')) {
        return;
    }
    $ctx->setExtension('example.tenant', [
        'key'      => $this->resolveTenantKey($ctx->namespace()),
        'readonly' => $ctx->permission() < AUTH_EDIT,
    ]);
}

Gefeuert von der Erzeugerfunktion des Dienstes core.context. Das DevOps-Gegenstück auf der Ebene darunter ist WKDOCORE_CONTEXT_BUILD.

$controller->register_hook('WKFLUENTUI_REGISTER_CONTRIBUTIONS', 'BEFORE', $this, 'registerContributions');
 
public function registerContributions(Event $event): void;
// $event->data['contributions'] ist eine veränderliche Liste von Descriptor-Arrays

Quelle: lib/plugins/wkfluentui/helper/contract.php. Contract im Wortlaut: lib/plugins/wkfluentui/docs/contract-v1.md

Das eine Registrierungsereignis, über das ein Paket alles beiträgt, was im Workbench sichtbar wird: Abzeichen, Ansichten, Befehle, Statusleisteneinträge, Module — und die Erklärung, dass es seine Schale selbst zeichnet.

Sie hängen Descriptor-Arrays an $event→data['contributions'] an. Pflicht sind nur owner und id.

Regionen (geschlossenes Vokabular): activityBar, sidebar, auxbar, bottomPanel, statusBar, commandPalette, adminModule.

Zwei Regionen setzen etwas beim Eigentümer voraus, nicht beim Descriptor. activityBar (und das badge, das denselben Eintrag schmückt) und adminModule verlangen, dass der Eigentümer ein Admin-Plugin ist. Die Aktivitätsleiste wird aus plugin_list('admin') gebaut, das Modulverzeichnis löst den Wirt mit plugin_load('admin', $owner) auf. Ein Beitrag eines Nicht-Admin-Pakets wird hier trotzdem angenommen, erscheint im Register — und zeichnet nichts.

Kein Rückgabewert. Das Ergebnis ist über helper_plugin_wkfluentui_contract lesbar:

Jeder normalisierte Eintrag trägt zusätzlich source (native oder legacy) und disabled.

Vollständige action-Komponente. Sie registriert ein Abzeichen, eine Ansicht und einen Befehl und ist ohne weitere Datei lauffähig, sobald das Paket ein plugin.info.txt und — wegen des Abzeichens — eine admin.php hat.

<?php
 
use dokuwiki\Extension\ActionPlugin;
use dokuwiki\Extension\EventHandler;
use dokuwiki\Extension\Event;
 
class action_plugin_wkexample extends ActionPlugin
{
    public function register(EventHandler $controller)
    {
        $controller->register_hook(
            'WKFLUENTUI_REGISTER_CONTRIBUTIONS', 'BEFORE', $this, 'registerContributions'
        );
    }
 
    public function registerContributions(Event $event)
    {
        $event->data['contributions'][] = [
            'owner' => 'wkexample',
            'id'    => 'badge',
            'badge' => ['count' => 3, 'tone' => 'warning', 'label' => $this->getLang('badge_label')],
        ];
 
        $event->data['contributions'][] = [
            'owner'  => 'wkexample',
            'id'     => 'sidebar',
            'kind'   => 'view',
            'region' => 'sidebar',
            'label'  => $this->getLang('view_title'),
            'html'   => '<p>' . hsc($this->getLang('view_body')) . '</p>',
        ];
 
        $event->data['contributions'][] = [
            'owner'          => 'wkexample',
            'id'             => 'command',
            'kind'           => 'action',
            'region'         => 'commandPalette',
            'label'          => $this->getLang('command_label'),
            'href'           => DOKU_BASE . 'lib/plugins/wkexample/plugin.info.txt',
            // Sichtbar nur für Angemeldete …
            'permission'     => static fn(): bool => isset($_SERVER['REMOTE_USER']),
            // … und betätigbar nur, wenn es etwas zu tun gibt.
            'enabled'        => fn(): bool => $this->pendingCount() > 0,
            'disabledReason' => $this->getLang('nothing_pending'),
        ];
    }
 
    private function pendingCount(): int
    {
        return 3;
    }
}

Die vollständig gebaute Fassung liegt als installierbares Paket im Baum: lib/plugins/wkfluentuicontracttest/action.php.

Gelesen von den Zeichnern des Workbench, die selbst kein Contract sind. Vorher abzufragen mit helper_plugin_wkfluentui_capabilities. Löst die veralteten Mechanismen ab.

$caps = plugin_load('helper', 'wkfluentui_capabilities');
 
public function has(string $capability): bool;
public function list(): array;   // string[]

Quelle: lib/plugins/wkfluentui/helper/capabilities.php

Beantwortet mit einem Namen, ob der Wirt eine Fähigkeit tatsächlich erbringt — die Frage, die weder eine Versionsnummer noch method_exists() beantworten kann.

Ein Fähigkeitsname. Das Kernvokabular dieser Fassung:

• workbench.contract.v1
• workbench.contribution.activityBar
• workbench.contribution.sidebar
• workbench.contribution.auxbar
• workbench.contribution.bottomPanel
• workbench.contribution.statusBar
• workbench.contribution.adminModule
• workbench.command.registry
• workbench.command.palette
• workbench.identity.requirement.v1
• workbench.surface.selfHosted

Dazu kommt alles, was ein aktives Paket über das Feld provides seines Descriptors zusichert.

has() liefert bool. list() liefert alle derzeit angebotenen Namen, entdoppelt.

public function registerContributions(Event $event)
{
    $caps = plugin_load('helper', 'wkfluentui_capabilities');
    $hasPanel = $caps !== null && $caps->has('workbench.contribution.bottomPanel');
 
    $event->data['contributions'][] = [
        'owner'  => 'wkexample',
        'id'     => $hasPanel ? 'panel' : 'sidebar',
        'kind'   => 'view',
        'region' => $hasPanel ? 'bottomPanel' : 'sidebar',
        'label'  => $this->getLang('view_title'),
        'html'   => $this->renderView(),
        // Eine eigene Zusicherung für andere Pakete:
        'provides' => ['example.reports.v1'],
    ];
}

Liest das Ergebnis von WKFLUENTUI_REGISTER_CONTRIBUTIONS mit. Das inhaltliche Gegenstück bei der Identität ist helper_plugin_wkidentity_contract::supports(), beim Antragswesen helper_plugin_wkrequest::supports().

$identity = plugin_load('helper', 'wkidentity_contract');
 
public function currentIdentity(): array;      // login, name, mail, groups
public function currentAssurance(): string;    // NONE, AUTHENTICATED, TOTP, MAIL_OTP
public function supports(string $capability): bool;
public function satisfies(?string $requirement, ?array $scope = null): bool;
public function require(string $requirement, ?array $scope, array $returnTarget): bool;

Quelle: lib/plugins/wkidentity/helper/contract.php. Contract im Wortlaut: lib/plugins/wkidentity/docs/contract-v1.md

Sagt, wer die Sitzung ist und was sie in dieser Sitzung bewiesen hat, und fordert bei Bedarf eine höhere Nachweisgüte an, bevor eine empfindliche Aktion läuft.

private const CATEGORIES = ['secret-write' => 'MFA_ANY', 'remove' => 'MFA_ANY'];
 
/** Aus ACTION_ACT_PREPROCESS gerufen. @return string|null Sprachschlüssel einer Absage */
private function decide(): ?string
{
    global $INPUT, $ID;
 
    $category = $INPUT->str('category');
    if (!isset(self::CATEGORIES[$category])) {
        return 'stepup_bad_category';
    }
 
    $identity = plugin_load('helper', 'wkidentity_contract');
    if ($identity === null) {
        send_redirect($this->backUrl());   // Paket abwesend: nichts zu beweisen
        return null;
    }
 
    $scope  = ['type' => 'adminAction', 'id' => 'wkexample:' . $category];
    $target = ['type' => 'page', 'id' => (string) $ID, 'act' => 'wkexample'];
 
    if ($identity->require(self::CATEGORIES[$category], $scope, $target)) {
        send_redirect($this->backUrl());   // war schon erfüllt
        return null;
    }
    // Nur der unerfüllbare Fall kommt hier an: kein passender Faktor hinterlegt.
    return 'stepup_cannot';
}
 
/** An der schreibenden Stelle noch einmal fragen — ohne Nebenwirkung. */
private function mayWrite(string $category): bool
{
    if (!$this->userHoldsRole('maintainer')) {
        return false;   // Ihre eigene Berechtigung zuerst
    }
    $identity = plugin_load('helper', 'wkidentity_contract');
    return $identity === null
        || $identity->satisfies('MFA_ANY', ['type' => 'adminAction', 'id' => 'wkexample:' . $category]);
}

Schritt für Schritt, mit der Sackgassenbehandlung: How-To: eine Aktion hinter einen zweiten Faktor stellen.

Gebaute Vorbilder im Baum: lib/plugins/wkdoado/StepUpBridge.php, lib/plugins/wkblog/StepUpBridge.php, lib/plugins/wkdoadogit/AdminSupport.php. Der Ausweg für ein Konto ohne Faktor ist helper_plugin_wkrequest::stepUpPanel().

$req = plugin_load('helper', 'wkrequest');
 
public function supports(string $capability): bool;
public function available(string $type): bool;
public function urlFor(array $draft): string;
public function requestAction(array $draft, string $labelKey = '', ?object $labels = null): array;
public function signInAction(string $returnTo = ''): array;
public function panel(array $spec): string;
public function accessPanel(array $spec): string;
public function stepUpPanel(array $spec): string;
public function permissionLabel(int $level): string;
public function currentPermissionLabel(string $id): string;
public function assuranceLabel(string $requirement): string;

Quelle: lib/plugins/wkrequest/helper.php

Macht aus dem Satz „wenden Sie sich an Ihren Administrator“ ein Bedienelement: einen strukturierten, auswertbaren Antrag, den ein Mensch von genau dem Bildschirm aus stellt, der ihn ausgesperrt hat.

Ein Entwurf — nur type ist Pflicht:

[
    'type'          => 'REPOSITORY_ACCESS_REQUEST',
    'owner'         => 'wkexample',
    'handler'       => 'wkexample:mounts',
    'resource'      => 'example:repo/wkcore',
    'resourceLabel' => 'Beispiel-Repositorium wkcore',
    'reasonCode'    => 'acl_denied',
    'context'       => ['namespace' => $ns],
]

Antragsarten: ACCESS_REQUEST, MFA_RESET_REQUEST, ROLE_REQUEST, REPOSITORY_ACCESS_REQUEST, REPOSITORY_MOUNT_REQUEST, ACCOUNT_SUPPORT_REQUEST, ADMIN_ACTION_REQUEST. Ohne Sitzung sind nur MFA_RESET_REQUEST und ACCOUNT_SUPPORT_REQUEST stellbar.

Fähigkeiten: request.raise, request.anonymous, request.inbox, request.notify, request.panel.

accessPanel() nimmt Tatsachen, nie Bedienelemente: resourceLabel, required, current, facts, draft, alternatives, selfservice, back. Welche Bedienelemente daraus folgen, in welcher Reihenfolge und ob sie überhaupt anbietbar sind, entscheidet die Methode.

Aus einer verschlossenen Tür wird ein Antrag samt Auswegen.

/** Zeichnet die vollständige Absage: warum nicht, und was jetzt. */
private function renderDenied(string $repo, string $ns): string
{
    $req = plugin_load('helper', 'wkrequest');
    if ($req === null) {
        return '<p>' . hsc($this->getLang('denied_plain')) . '</p>';
    }
 
    return $req->accessPanel([
        'title'         => $this->getLang('denied_title'),
        'resourceLabel' => $repo,
        'required'      => $req->permissionLabel(AUTH_READ),
        'current'       => $req->currentPermissionLabel($ns),
        'draft'         => [
            'type'          => 'REPOSITORY_ACCESS_REQUEST',
            'owner'         => 'wkexample',
            'handler'       => 'wkexample:mounts',
            'resource'      => $repo,
            'resourceLabel' => $repo,
            'reasonCode'    => 'acl_denied',
            'context'       => ['namespace' => $ns],
        ],
        'back'          => wl($ns, [], true, '&'),
    ]);
}

Anmelden, „meine offenen Anträge“ und der Rückweg werden von accessPanel() selbst angehängt: sie sind Eigenschaften der Sitzung, nicht des Bildschirms — ein Bildschirm, der sie sich merken müsste, vergisst einen davon.

Sie sollten zusätzlich WKREQUEST_REGISTER_HANDLERS bedienen, damit der Posteingang weiß, wo Ihr Antrag entschieden wird. Für die Absage wegen eines fehlenden zweiten Faktors ist stepUpPanel() die richtige Tafel.

$controller->register_hook('WKREQUEST_REGISTER_HANDLERS', 'BEFORE', $this, 'registerRequestHandlers');
 
public function registerRequestHandlers(Event $event): void;
// $event->data['handlers'] ist eine veränderliche Liste

Quelle: lib/plugins/wkrequest/helper.php

Erklärt, welcher Bildschirm eine bestimmte Art von Antrag tatsächlich entscheiden kann.

Kein Rückgabewert. Lesbar über handlers(), handler(string $key) und handlersForType(string $type).

public function register(EventHandler $controller)
{
    // Ausgeschrieben statt über die Konstante: wkrequest ist optional, und eine
    // Klasse zu nennen, die fehlen kann, nähme register() im Ganzen mit.
    $controller->register_hook('WKREQUEST_REGISTER_HANDLERS', 'BEFORE', $this, 'registerRequestHandlers');
}
 
public function registerRequestHandlers(Event $event)
{
    if (!is_array($event->data) || !isset($event->data['handlers'])) {
        return;
    }
    $label = (string) $this->getLang('menu');
    $event->data['handlers'][] = [
        'owner' => 'wkexample',
        'id'    => 'mounts',
        'label' => $label !== '' ? $label : 'Example mounts',
        'url'   => wl('', ['do' => 'admin', 'page' => 'wkexample', 'area' => 'mounts'], true, '&'),
        'types' => ['REPOSITORY_ACCESS_REQUEST', 'REPOSITORY_MOUNT_REQUEST'],
    ];
}

Benennen Sie den Bildschirm, der die Sache wirklich entscheidet. Liest Ihr Paket seine Rechte aus einer eigenen Matrix und nicht aus DokuWiki-Gruppen, dann ändert ein Eintrag in der Benutzerverwaltung daran nichts — und die Benutzerverwaltung ist dann die falsche Adresse.

Gegenstück zum Admin Request Contract.

Die Punkte in diesem Teil sind benutzbar und werden benutzt, tragen aber im Katalog ihres Trägers die Stufe experimental: Signatur oder Nutzlast können sich ohne Abkündigungszyklus ändern.

$controller->register_hook('WKDOCORE_REGISTER_HUBS', 'BEFORE', $this, 'registerHubs');
 
public function registerHubs(Event $event): void;
// $event->data === dokuwiki\plugin\wkdocore\Domain\HubRegistry

Quelle: lib/plugins/wkdocore/Domain/HubRegistry.php, lib/plugins/wkdocore/Model/Hub.php

Fügt der Projektnavigation einen eigenen Hub hinzu oder ersetzt einen der mitgelieferten.

$event→data→register($hub). Der Hub ist unveränderlich:

Kein Rückgabewert. Das Register liefert danach all() (in Anzeigereihenfolge), get(string $id) und ids().

use dokuwiki\plugin\wkdocore\Model\Hub;
use dokuwiki\plugin\wkdocore\Model\Role;
 
public function register(EventHandler $controller)
{
    $controller->register_hook('WKDOCORE_REGISTER_HUBS', 'BEFORE', $this, 'registerHubs');
}
 
public function registerHubs(Event $event)
{
    $registry = $event->data;
    if (!is_object($registry) || !method_exists($registry, 'register')) {
        return;
    }
 
    $registry->register(new Hub(
        'releases',                  // id
        'hub_releases',              // Sprachschlüssel, nicht der Text
        '',                          // kein voreingetragenes Kürzel …
        25,                          // … zwischen boards (20) und repos (30)
        'releases',                  // Route innerhalb des Projekts
        AUTH_READ,
        Role::CONTRIBUTOR,
        'hub.releases',
        'codicon codicon-rocket',    // eigenes Symbol, ohne Kürzeleintrag
        'wkexample_releases'         // die Aktion, die den Bildschirm füllt
    ));
}

Der Hub erscheint in der Navigation, die helper_plugin_wkdocore::renderHubNav() zeichnet. Der Kontext, aus dem die Sichtbarkeit stammt, entsteht über WKDOCORE_CONTEXT_BUILD.

$controller->register_hook('WKDOCORE_CONTEXT_BUILD', 'BEFORE', $this, 'enrichDwdoContext');
 
public function enrichDwdoContext(Event $event): void;
// $event->data === dokuwiki\plugin\wkdocore\Model\DwdoContext

Quelle: lib/plugins/wkdocore/Model/DwdoContext.php

Hängt einen eigenen Teilkontext an den DevOps-Kontext, nachdem Projekt, Rolle, sichtbare Hubs und Merkmalsschalter feststehen.

$event→data→setExtension(string $name, mixed $value).

Kein Rückgabewert.

Lösen Sie aus diesem Haken heraus keine erneute Auflösung von core.context oder dwdo.context aus — das Ereignis feuert, während diese Dienste gerade aufgelöst werden.

public function enrichDwdoContext(Event $event)
{
    $ctx = $event->data;
    if (!is_object($ctx) || !method_exists($ctx, 'setExtension')) {
        return;
    }
    $project = method_exists($ctx, 'project') ? $ctx->project() : null;
    if ($project === null) {
        return;   // außerhalb eines Projekts gibt es nichts anzuhängen
    }
    $ctx->setExtension('example.releases', [
        'projectKey' => $project->key,
        'open'       => $this->countOpenReleases($project->key),
    ]);
}

Die Ebene darüber ist WKCORE_CONTEXT_BUILD.

$controller->register_hook('WKDOCORE_PROJECT_DISCOVER', 'BEFORE', $this, 'discoverProjects');
 
public function discoverProjects(Event $event): void;
// $event->data hat die Schlüssel 'keys' und 'root'

Quelle: lib/plugins/wkdocore/Domain/AggregateProjectDirectory.php

Steuert Projektschlüssel zur Kandidatenliste des Projektverzeichnisses bei.

$event→data['keys'] ist veränderlich; hängen Sie Ihre Schlüssel an. $event→data['root'] ist der Projektwurzel-Namensraum der aktiven Sprache und wird nur zum Lesen mitgegeben, damit ein Haken sieht, wohin ein Schlüssel ohne eigenen Namensraum geleitet würde.

Kein Rückgabewert.

public function discoverProjects(Event $event)
{
    if (!is_array($event->data) || !isset($event->data['keys'])) {
        return;
    }
    foreach ($this->externalProjectKeys() as $key) {
        $event->data['keys'][] = $key;
    }
}

Speist das Projektverzeichnis, das als Dienst dwdo.projectdirectory im Register steht.

$controller->register_hook('WKDOCORE_REGISTER_REPOSITORY_SOURCES', 'BEFORE', $this, 'registerRepoSources');
 
public function registerRepoSources(Event $event): void;
// $event->data === dokuwiki\plugin\wkdocore\Domain\RepositoryDirectory

Quelle: lib/plugins/wkdocore/Domain/RepositorySource.php

Meldet ein Repositoriums-Backend beim projektübergreifenden Verzeichnis an.

$event→data→register($source) mit einer Umsetzung von RepositorySource:

interface RepositorySource extends \dokuwiki\plugin\wkcore\Contract
{
    public function id(): string;
    /** @return RepositoryDescriptor[] */
    public function repositories(string $projectKey = ''): array;
}

Kein Rückgabewert.

Das Anmelden ist zugleich das Einschalten: Das Plugin zu installieren genügt, und es zu entfernen nimmt seine Repositorien aus jeder Liste, jeder Zählung und jeder Suche, ohne dass irgendwo ein Rest darauf zeigt.

use dokuwiki\plugin\wkdocore\Domain\RepositorySource;
use dokuwiki\plugin\wkdocore\Model\RepositoryDescriptor;
 
final class ExampleRepositorySource implements RepositorySource
{
    public function id(): string
    {
        return 'example';
    }
 
    /** @return RepositoryDescriptor[] */
    public function repositories(string $projectKey = ''): array
    {
        $out = [];
        foreach ($this->backend->list($projectKey) as $row) {
            $out[] = new RepositoryDescriptor(/* … */);
        }
        return $out;
    }
}
 
// in der action-Komponente:
public function registerRepoSources(Event $event)
{
    $directory = $event->data;
    if (is_object($directory) && method_exists($directory, 'register')) {
        $directory->register(new ExampleRepositorySource());
    }
}

Das Verzeichnis steht als dwdo.repodirectory im Dienstregister.

$controller->register_hook('WKSOURCEVIEW_REGISTER_PROVIDERS', 'BEFORE', $this, 'registerProviders');
 
public function registerProviders(Event $event): void;
// $event->data === dokuwiki\plugin\wksourceview\Provider\SourceProviderRegistry

Quelle: lib/plugins/wksourceview/Events.php, lib/plugins/wksourceview/Provider/WkSourceProvider.php

Liefert Quelltext aus einem eigenen Backend an {{source>…}} und an die Quelltext-Schublade.

$event→data→register(string $scheme, $provider):

interface WkSourceProvider extends \dokuwiki\plugin\wkcore\Contract
{
    public function scheme(): string;
    public function supports(SourceRef $ref): bool;
    public function fetch(SourceRef $ref, string $pageId): SourceDocument;
}

fetch() liefert immer ein SourceDocument, nie null. Ein Misserfolg wird über dessen Status ausgedrückt, nicht über eine Ausnahme.

public function register(EventHandler $controller)
{
    $controller->register_hook('WKSOURCEVIEW_REGISTER_PROVIDERS', 'BEFORE', $this, 'registerProviders');
}
 
public function registerProviders(Event $event)
{
    $registry = $event->data;
    if (!is_object($registry) || !method_exists($registry, 'register')) {
        return;
    }
    $provider = new \dokuwiki\plugin\wkexample\Source\ExampleSourceProvider(
        $this->backend(),
        (int) $this->getConf('max_bytes'),
        (int) $this->getConf('max_lines')
    );
    // Ein Provider darf mehrere Schemata bedienen.
    $registry->register('example', $provider);
    $registry->register('ex', $provider);
}

Damit löst {{source>example:pfad/zur/datei.php}} über Ihr Backend auf.

Die mitgelieferten Schemata sind media und page; wkdogit trägt git und repo bei, wkdoadogit das Schema ado.

$controller->register_hook('WKSQLITEDS_REGISTER_ROUTINE_SETS', 'BEFORE', $this, 'registerRoutineSets');
 
public function registerRoutineSets(Event $event): void;

Quelle: lib/plugins/wksqliteds/helper.php

Meldet ein Verzeichnis mit benannten SQL-Routinen an, damit ein eigenes Paket seine Abfragen als versionierte Dateien mit Manifest ausliefern kann, statt SQL im PHP-Quelltext zu führen.

Der Satzname und das Basisverzeichnis. Der Helfer deklariert seine öffentliche Oberfläche zusätzlich über DokuWikis eigene getMethods()-Konvention:

Siehe Tabelle. Der Rückgabetyp von execute() steht im Manifest der Routine, nicht im Aufruf.

public function register(EventHandler $controller)
{
    $controller->register_hook('WKSQLITEDS_REGISTER_ROUTINE_SETS', 'BEFORE', $this, 'registerRoutineSets');
}
 
public function registerRoutineSets(Event $event)
{
    $registry = $event->data;
    if (is_object($registry) && method_exists($registry, 'register')) {
        $registry->register('wkexample', __DIR__ . '/sql');
    }
}
 
/** Aufruf einer Routine aus dem eigenen Satz. */
public function closeItem(int $id, string $user): int
{
    $routines = plugin_load('helper', 'wksqliteds');
    if ($routines === null) {
        throw new \RuntimeException('wksqliteds is required for this feature');
    }
    return $routines->execute('reporting', 'wkexample:close_item', ['id' => $id, 'user' => $user]);
}

Der Dienst sql.routines im Dienstregister liefert denselben Ausführer.

$controller->register_hook('WKOPENGRAPH_VALUES', 'BEFORE', $this, 'provideOgValues');
 
public function provideOgValues(Event $event): void;
// $event->data hat die Schlüssel 'id' und 'og'

Quelle: lib/plugins/wkopengraph/action.php

Ersetzt einzelne Open-Graph-Werte, nachdem die reguläre Auflösungskette durchlaufen ist — der Weg für Angaben, die außerhalb der Seitenmetadaten gepflegt werden.

$event→data['id'] ist die Seiten-ID (nur zum Lesen). $event→data['og'] ist das veränderliche Wertefeld; erwartet werden title, description, url, site_name, type und image.

Kein Rückgabewert. Ein zurückgegebener Wert überschreibt den zuvor aufgelösten.

Für image genügt eine Wiki-Medien-Kennung mit führendem Doppelpunkt; sie wird für Sie zu einer absoluten URL aufgelöst. Zeichenkettenwerte dürfen sprachabhängige Varianten tragen, geschrieben als Sprachkürzel, Doppelpunkt, Text, getrennt durch senkrechte Striche.

public function provideOgValues(Event $event)
{
    if (!is_array($event->data) || !is_array($event->data['og'] ?? null)) {
        return;
    }
    $post = $this->postFor((string) $event->data['id']);
    if ($post === null) {
        return;   // keine eigene Angabe: die reguläre Kette behält recht
    }
    $event->data['og']['description'] = $post['teaser'];
    $event->data['og']['image']       = ':' . $post['cover'];   // wird aufgelöst
}

Eigenständig. Keine Abhängigkeit zu wkcore.

$controller->register_hook('WKREQUEST_REFINE_DENIED', 'BEFORE', $this, 'refineDenied');
 
public function refineDenied(Event $event): void;
// $event->data === die Tafelangabe (Array)

Quelle: lib/plugins/wkrequest/action.php

Lässt das Paket, dem der verschlossene Bereich gehört, die Absagetafel schärfen, die wkrequest auf einer verweigerten Seite gleich zeichnen wird.

Die bereits von wkrequest zusammengestellte Angabe. Übernommen werden ausschließlich diese Schlüssel:

Kein Rückgabewert; Sie verändern das Datenfeld.

public function refineDenied(Event $event)
{
    if (!is_array($event->data)) {
        return;
    }
    $ns = getNS((string) ($GLOBALS['ID'] ?? ''));
    if (!$this->ownsNamespace($ns)) {
        return;   // fremder Bereich: nichts sagen
    }
    $event->data['resourceLabel'] = $this->humanNameFor($ns);
    $event->data['facts'][] = [
        'label' => $this->getLang('fact_group'),
        'value' => $this->openingGroupFor($ns),
    ];
}

Verfeinert die Tafel des Admin Request Contract.

Die Kennungen, die die Pakete der Suite belegen. Ein Verbraucher prüft immer zuerst mit has(); ein get() auf eine unbekannte Kennung wirft.

Stabilität: Die Kennung selbst und die Tatsache, dass etwas dahintersteht, sind so stabil wie das eintragende Paket. Die Form des hinterlegten Objekts gehört dem eintragenden Paket; wo es dafür ein Interface gibt, ist es in diesem Katalog genannt. Prüfen Sie vor der Benutzung mit method_exists(), statt einen Typ anzunehmen — genau so tun es die Pakete der Suite untereinander.

Diese fünf entenartig typisierten Mechanismen sind vom Workbench-Contract v1 abgelöst. Sie funktionieren unverändert weiter: ein Anpassungsstück übersetzt sie in dieselbe Descriptor-Form, und ein Paket, das auf ihnen geschrieben ist, läuft ohne Änderung.

Warum sich der Umstieg lohnt, auch wenn nichts kaputtgeht. Eine Fähigkeit, die man nur prüfen kann, indem man eine Methode ruft und nachsieht, ob das Ergebnis zufällig leer ist, ist nicht auffindbar — sie muss einmal im Quelltext gelesen und dann erinnert werden. Der Contract ist das Gegenteil: ein Ereignis, ein Descriptor, und eine Fähigkeit, nach der man fragen kann, bevor man etwas versucht.

Drei Regeln aus vier durchgeführten Umstellungen:

1. Die Schalenankündigung gehört außerhalb jeder Absicherung. Sie ist eine feste Eigenschaft des Pakets. Steht sie in derselben Absicherung wie ein Haken, der für ein Abzeichen eine Datenbank befragt, dann hebt ein Datenbankausfall die Selbstzeichnung auf — und der Bildschirm erscheint in zwei Schalen. Die Ursache wäre eine fehlgeschlagene Zählabfrage in einer anderen Datei.
2. Erst jeden Verbraucher belehren, dann den ersten Erzeuger umstellen. Die Eigentümerfrage wird an drei Stellen gestellt. Ein Verbraucher, der nur den alten Weg kennt, fängt am Tag der ersten Umstellung an, das Falsche zu tun — und nichts scheitert dabei: es erscheint lediglich ein zweites Inhaltsverzeichnis neben der Navigation, die das Modul schon selbst zeichnet.
3. Eigentümerschaft und Nutzlast sind zwei Fragen. Eine v1-Anmeldung kündigt eine Fläche an; sie übergibt keine fertig gezeichneten Regionen.

Sichtbarkeit folgt dem Eigentümer. Ein Beitrag, dessen Eigentümer ein installiertes Admin-Plugin ist, entfällt, wenn die Sitzung dieses Plugin nicht erreichen darf. Ein Paket ohne Admin-Bildschirm hat diese Prüfung nicht und muss permission selbst mitbringen — passend zu dem, was sein Ziel durchsetzt. Das falsch zu machen ist unsichtbar: das Register reicht einen Descriptor heraus, den niemand zeichnet, bis eines Tages jemand ihn zeichnet.

Das Anpassungsstück verschwindet, sobald kein Paket mehr seine Schale über getShellRegions() erklärt. Eines tut es noch — die Datenbankumgebung, deren Umsetzung eine echte Nutzlast trägt, die die Hausvorlage vor dem Inhalt platziert.

• Übersicht — der Einstieg, mit der Routing-Karte.
• Tutorial — ein Plugin von Grund auf in den Workbench hängen.
• How-To — eine Aktion hinter einen zweiten Faktor stellen.
• Fehlerbehebung — Symptome und ihre Ursachen.
• die Kompatibilitätsmatrix in docs/KOMPATIBILITAET.md — ob ein Paket auf dieser Installation überhaupt lauffähig ist.
• Contracts im Wortlaut: lib/plugins/wkfluentui/docs/contract-v1.md, lib/plugins/wkidentity/docs/contract-v1.md
• Ereigniskataloge zum Nachschlagen der Stufe: lib/plugins/wkcore/Events.php, lib/plugins/wkdocore/Events.php, lib/plugins/wksourceview/Events.php
• lib/plugins/wkcore/docs/upgrading.md — was ein Upgrade an Contracts und Daten verändert.