Erweiterungspunkte der WvdS-DW-Suite

Diese Seite ist der Einstieg für Entwicklerinnen und Entwickler, die ein eigenes Plugin an die WvdS-DW-Pakete anschließen wollen. Sie nennt die stabilen Contracts, über die das geschieht, und führt zu der Seite, die den jeweiligen Contract vollständig beschreibt — damit niemand die Erweiterungspunkte im Quelltext der Kernpakete suchen muss.

Erste Schritte

Der kürzeste vollständige Weg von einem leeren Plugin zu einer sichtbaren Erweiterung:

Plugin anlegen → Auf ein Contract-Ereignis registrieren → Descriptor anhängen → Fähigkeit vorher abfragen → Im Workbench prüfen

Vollständig durchgespielt steht dieser Weg im Tutorial. Das kleinste lauffähige Beispiel liegt zusätzlich als installierbares Plugin im Baum: lib/plugins/wkfluentuicontracttest/.

Häufige Aufgaben

Das Manifest wkcomponent.json

Ein Paket, das die hier beschriebenen Erweiterungspunkte benutzt, hängt damit an anderen Paketen. Diese Abhängigkeiten gehören in eine Datei neben den Code, nicht in eine Tabelle daneben: jedes Paket der Suite legt im eigenen Repository eine wkcomponent.json ab, direkt neben plugin.info.txt.

Was darin steht und wozu:

Angabe	Wofür sie gebraucht wird
`requires`	DokuWiki- und PHP-Mindeststand, benötigte PHP-Erweiterungen, Voraussetzungen an das System
`dependencies.required`	ohne dieses Paket lädt oder arbeitet das eigene nicht
`dependencies.features`	eine benannte Fähigkeit braucht es — sie darf fehlen, ohne dass etwas kaputtgeht
`dependencies.optional`	verbessert den Betrieb; wird nie ungefragt mitinstalliert
`conflicts`, `configuration`, `verification`, `notes`	was sich ausschließt, was zwingend einzustellen ist, woran der Betrieb nachweisbar ist, welche Grenzen bleiben
`release`	die Fassung, die als freigegeben gilt, mit ihrer Commit-Kennung

Die drei Abhängigkeitsarten auseinanderzuhalten ist der eigentliche Punkt. Eine Fähigkeitsabhängigkeit ist technisch entbehrlich und für ihren Zweck unumgänglich — beides zugleich. Eine einzelne Spalte „hart/weich„ kann das nicht sagen, und wer sie benutzt, gibt entweder eine falsche Warnung oder eine falsche Entwarnung.

Was daraus entsteht, ohne weiteres Zutun: der Installationssatz einer Auswahl samt Abhängigkeiten der Abhängigkeiten, die Reihenfolge der Installation, die Referenztabellen im Wiki und das ausgelieferte Archiv. Ein Paket ohne Manifest erscheint in all dem nicht. Die erzeugte Aufstellung steht auf der Komponentenmatrix; auswählen und beziehen lässt sich ein Satz im Paket-Baukasten.

Gegenprobe. php bin/plugin.php wkbundle verify vergleicht jedes Manifest mit der zugehörigen plugin.info.txt und meldet jede Abweichung namentlich.

Visuelle Darstellung

Wie ein fremdes Plugin an die Suite andockt. Jede Verbindung ist ein Ereignis oder eine Registerabfrage; keine ist eine Klassenableitung, und keine setzt voraus, dass das Zielpaket installiert ist.

                       ┌──────────────────────────────┐
                       │  (1) Ihr Plugin              │
                       │      action-Komponente       │
                       └──────────────┬───────────────┘
                                      │
        ┌──────────────┬──────────────┼──────────────┬──────────────┐
        │              │              │              │              │
       (2)            (3)            (4)            (5)            (6)
   ═════▼═══════  ═════▼═══════  ═════▼═══════  ═════▼═══════  ═════▼═══════
    wkcore         wkfluentui     wkdocore       wksourceview    wkrequest
    Dienst-        Workbench      Projekt-       Quelltext-      Antrags-
    register       Contract v1    navigation     Provider        posteingang
   ═════╤═══════  ═════════════  ═════════════  ═════════════  ═════════════
        │                                                            ▲
       (7)                                                          (8)
   ═════▼═══════                                              ┌ ─ ─ ─┴─ ─ ─ ┐
    Dienst-IDs                                                  wkidentity
    storage.sqlite · vault.secrets                             Identity
    sql.routines · dwdo.*                                      Contract v1
   ═════════════                                              └ ─ ─ ─ ─ ─ ─ ┘

   ═══  Sie registrieren sich und werden gerufen
   ─ ─  Sie fragen selbst aktiv nach

Nr.	Bereich	Wie Sie andocken
1	Ihr Plugin	eine `action`-Komponente mit `register()`
2	Dienstregister	Ereignis `WKCORE_REGISTER_SERVICES`
3	Workbench	Ereignis `WKFLUENTUI_REGISTER_CONTRIBUTIONS`
4	Projektnavigation	Ereignis `WKDOCORE_REGISTER_HUBS`
5	Quelltextbetrachter	Ereignis `WKSOURCEVIEW_REGISTER_PROVIDERS`
6	Antragsposteingang	Ereignis `WKREQUEST_REGISTER_HANDLERS`
7	Dienst-IDs	`plugin_load('helper', 'wkcore')`, dann `has()` und `get()`
8	Identität	`plugin_load('helper', 'wkidentity_contract')`

Kernfunktionen

Ein Mechanismus je Frage. Beitragen geschieht über ein Ereignis, Nachfragen über einen Helper. Es gibt keinen dritten Weg.
Keine Kopplung in der Deklaration. Kein Interface der Suite ist zu implementieren, keine Klasse zu importieren, kein plugin_load() während der Registrierung nötig. Fehlt das Zielpaket, feuert das Ereignis nicht — Ihr Plugin läuft unverändert weiter.
Fähigkeiten statt Versionsnummern. Vor der Benutzung wird ein Name abgefragt, nicht eine Version verglichen.
Ein Beitrag scheitert allein. Ein Fehler in Ihrem Beitrag kostet diesen Beitrag, nie die Anfrage.
Entfernen braucht keinen Code. Es gibt keinen Deinstallationshaken: ist das Plugin weg, feuert sein Haken nicht mehr, und der Beitrag verschwindet mit der nächsten Anfrage.

Kernkonzepte

Die Suite kennt zwei Arten von Erweiterungspunkten. Ein Registrierungsereignis sammelt Beiträge ein: Ihr Plugin hängt einen Descriptor an eine veränderliche Liste im Ereignis-Datenobjekt, und das aufnehmende Paket entscheidet allein über Reihenfolge, Sichtbarkeit und Darstellung. Ein Contract-Helper beantwortet umgekehrt eine Frage, die nur das andere Paket beantworten kann — ob diese Sitzung einen zweiten Faktor bewiesen hat, ob ein Antrag gerade stellbar ist. Beide sind absichtlich entenartig typisiert: der Beitragende nennt sich selbst beim Namen, statt sich gegen eine Klasse der Suite zu binden. Das Dienstregister in wkcore ist die dritte, darunterliegende Schicht — ein flacher Namensraum aus Zeichenketten-IDs, über den Pakete einander Objekte reichen, ohne sich zu kennen.

Welcher Erweiterungspunkt öffentlich ist und welcher nicht, entscheidet die API-Referenz — nicht die Sichtbarkeit der PHP-Methode.

Administration

docs/KOMPATIBILITAET.md — welche Pakete auf einer Installation überhaupt lauffähig sind, mit den geprüften Mindestversionen.
lib/plugins/wkcore/docs/operator-handbook.md — Betrieb des Dienstregisters.
lib/plugins/wkcore/docs/upgrading.md — was ein Upgrade an Contracts und Daten verändert.
Diagnose zur Laufzeit: ?do=wkcore_diag zeigt die belegten Dienst-IDs und den Ereigniskatalog. Der Bildschirm ist an $conf['allowdebug'] gebunden und auf einer Produktivinstallation nicht erreichbar.

Fehlerbehebung

Für Entwickler

Tutorial: ein Plugin in den Workbench integrieren
How-To: eine Aktion hinter einen zweiten Faktor stellen
API-Referenz aller Erweiterungspunkte
Contracts im Wortlaut: lib/plugins/wkfluentui/docs/contract-v1.md (Workbench), lib/plugins/wkidentity/docs/contract-v1.md (Identity)
Quelltext des Referenzbeispiels: lib/plugins/wkfluentuicontracttest/action.php
Ereigniskataloge: lib/plugins/wkcore/Events.php, lib/plugins/wkdocore/Events.php, lib/plugins/wksourceview/Events.php