register() (siehe PHP-Schnittstelle). Die Klassen liegen im Namensraum App\Plugin\Api.
Seiten
- Eine Seite ist ein Präfix: Sie passt auf ihren Pfad und alles darunter; der längste Treffer gewinnt. Die Unterseiten definiert das Frontend mit
sdk.registerRoutes()(siehe Frontend-SDK → Seiten). - Der Kern rendert eine Hülle mit Navigation, Kopf und Fuß der Plattform;
titleist ein Übersetzungsschlüssel für den Seitentitel. - Zugriff wie bei Endpunkten, aber ohne
Access::Public: Seiten setzen immer eine Anmeldung voraus (sonst Umleitung zum Login). Seitenpfade beginnen nie mit/apioder/dist. guard: fn(Viewer $viewer, ?CommunityInfo $community): boolprüft eigene Rechte;falseoder eine Ausnahme ergibt404wie bei Seiten von QuickTribe.- Unbekannte oder gelöschte Communities leiten zur Startseite; Mitglieder ohne das nötige Recht bekommen
403, Fremde404.
Menüpunkte
label: Übersetzungsschlüssel, höchstens 60 Zeichen.pathohne Platzhalter; dort sollte eine Seite registriert sein.icon: eines vonaward,bell,book-open,calendar,car,clipboard-list,crosshair,file-text,folder,heart,info,map-pin,message-circle,puzzle,settings,shield,star,target,trophy,user,users,wallet,wrench.order: Reihenfolge (Standard 100). Ein Menüpunkt ist aktiv, wenn der aufgerufene Pfad mit seinem Ziel beginnt.visible: fn(Viewer, ?CommunityInfo): boolblendet den Punkt nach eigenen Regeln aus; einmal je Seitenaufbau ausgewertet, eine Ausnahme blendet ihn aus und landet im Log.
Zusatzfelder
Deklarative Zusatzfelder an Events und Mitgliedern – ab Plugin-API 1.2 auch an Beiträgen, Kursen und Lektionen – prüft, speichert und zeigt der Kern selbst, ganz ohne eigenen Code im Plugin. Die Werte erscheinen in den Antworten unterextra.<pluginId>.<key>.
Wer bearbeiten darf, muss den Wert auch sehen:
Self passt zu Members und Self, Team zusätzlich zu Team, Manage zu allen, EventCreator und Author nur zu Members. Visibility::Self gibt es nur an Mitgliedern. Widersprüche wirft der Builder als InvalidRegistration.
- Events: Die Felder erscheinen im Event-Editor und in der Event-Ansicht; sie gelten für die ganze Serie.
- Mitglieder: Die Felder erscheinen – je nach Sichtbarkeit – im Profil unter Zusatzangaben und bei Beitrittsanfragen; in den Antworten des Mitgliederverzeichnisses stehen sie unter
extra. Gespeichert wird überPUT /api/v1/communities/<slug>/members/<userId>/plugin-fields; das Protokoll nennt nur die Feldnamen. Datenexport und Kontolöschung übernimmt der Kern. - Beiträge, Kurse, Lektionen (ab 1.2): Die Felder erscheinen im jeweiligen Editor und in der Ansicht (Beitragskarte und -ansicht, Kursseite, Lektion). Beim Löschen entfernt der Kern die Werte – bei einem Kurs auch die seiner Lektionen. Geburtstags-Einträge haben keine Zusatzfelder.
- Lesen im Plugin:
members()->extraFields($communityId, $membershipIds, $viewer)bzw.events()->extraFields($communityId, $eventIds, $viewer)– mit Viewer gefiltert nachvisibleTo, ohne Viewer alle Werte (für Jobs, Aufgaben, PDF).
Erweiterungen von Kern-Antworten
Für Angaben, die ein Plugin selbst berechnet (z. B. „3 freie Plätze“), ergänzt eineResponseExtension die Antworten des Kerns um extra.<pluginId>:
- Je Liste und Plugin gibt es genau einen Aufruf von
load()– alle IDs (ids()) bzw. Vorkommen (occurrences()) auf einmal. In Listen nur knappe Daten (Zähler), im Detail mehr. - Übergeben wird nur, was der Betrachter (
viewer()) sehen darf; gesperrte Vorkommen fehlen und haben keinextra. - Ein Vorkommens-Schlüssel gewinnt vollständig vor der Event-ID. Werte deklarierter Zusatzfelder führt der Kern in denselben
extra.<pluginId>-Block; bei gleichem Schlüssel gewinnt der Kern. - Läuft
load()länger als 200 ms, gibt es eine Warnung im Log; eine Ausnahme lässtextra.<pluginId>weg, die Antwort bleibt200. - Nie in öffentlichen Seiten, Kalenderdateien, der REST-API, E-Mails, der Suche oder im Profil-Abschnitt „letzte Beiträge“.
EventInputExtension (nur Target::Event) nimmt zusätzlich den Block extra.<pluginId> entgegen, den der Editor-Slot des Plugins befüllt (siehe Slots).
validate(ExtensionInput $input): arrayprüft fachlich vor dem Speichern und liefert Feldpfad → Übersetzungsschlüssel bzw.[Schlüssel, Parameter]; der Kern antwortet mit422unterextra.<pluginId>.<feld>.validate()läuft für alle in der Community eingeschalteten Plugins mit Eingabe-Erweiterung, auch ohne eigene Daten (data()ist dannnull) – so kann ein Plugin z. B. eine Verschiebung ablehnen. Andere Wege, Events anzulegen (REST-API, Formular-Freigabe), liefern nie Plugin-Daten; Plugins müssen fehlende Werte aushalten.store(ExtensionInput $input, string $eventId): voidspeichert in derselben Transaktion wie das Event und nur, wenndata()nichtnullist. Hier keine fachlichen Prüfungen – eine Ausnahme rollt alles zurück (500).ExtensionInputliefertcommunity(),actor(),creating(),eventId()(beim Anlegennull),draft()(Werte nach der Änderung alsModel\EventDraft),previous()(vorher) unddata().- Grenzen des Blocks: höchstens 20 Plugin-Schlüssel, je Plugin 64 KB JSON, Verschachtelung bis Tiefe 5.
- Erweiterungen wirken auf die ganze Serie. Werte je Termin pflegt das Plugin über eigene Endpunkte und gibt sie unter dem Vorkommens-Schlüssel aus.
InputExtension (Ziele Target::Post, Target::Course, Target::Lesson) nimmt den Block extra.<pluginId> aus CreatePostRequest/UpdatePostRequest, CreateCourseRequest/UpdateCourseRequest bzw. CreateLessonRequest/UpdateLessonRequest entgegen – mit denselben Regeln wie bei Events:
TargetInputliefertcommunity(),actor(),target(),creating(),targetId()(beim Anlegennull),core()unddata().core()sind die Kernwerte nach der Änderung – Beitrag:title,categoryId,isPublic,status; Kurs:title,published,access; Lektion:title,courseId,moduleId–, nie Texte.validate()läuft auch ohne eigene Daten (z. B. eine Kategorie ablehnen);store()nur mit Daten, in derselben Transaktion. Die Rechte am Objekt prüft der Kern vorher.- Lesende Kern-Dienste für Beiträge und Kurse gibt es nicht: Daten je Objekt gibt das Plugin über
load()aus – dort nur für Objekte, die der Betrachter sehen darf.
Filter-Hooks
Ab Plugin-API 1.2 ("pluginApi": "^1.2"). Filter-Hooks laufen synchron und liefern etwas zurück: einen Eingriff in die Rangliste, Werte für Platzhalter, einen Baustein oder ein Formularfeld. Sie laufen lesend (wie ein GET-Handler: keine schreibenden Kern-Dienste), je Plugin einmal je Liste bzw. Gruppe. Über dem Zeitbudget gibt es eine Warnung im Log; eine Ausnahme bricht nie die Seite oder den Versand – der Kern protokolliert sie und macht ohne dieses Plugin weiter. In einer Community ausgeschaltete Plugins wirken nicht.
Rangliste
RankingQuery:community,viewer,period(challengeoderall),from/to(Zeitraum in UTC, beiallnull),entries(ganze Rangliste, höchstens 1000 Einträge mitmembershipIdundpoints).RankingChange(points: [membershipId => Delta], exclude: [membershipId, …]): Deltas sind ganze Zahlen bis ±1 000 000; Mitglieder ohne Eintrag beginnen bei 0. Nur lesende Mitglieder der Community zählen. Deltas mehrerer Plugins addieren sich; jedes Plugin sieht die ungefilterte Liste.- Der Kern sortiert neu, vergibt Ränge und berechnet die eigene Position. Der Filter wirkt nur auf die Anzeige – nicht auf Level, Punkteverlauf oder Challenge-Ergebnisse.
Platzhalter in E-Mail-Serien
- Im Betreff und Text einer Serie heißen sie
{<pluginId>.<key>}, z. B.{example-plugin.items}; der Serien-Editor listet sie unter „Platzhalter aus Erweiterungen“. Höchstens 20 je Plugin. - Der Kern ruft das Plugin nur, wenn ein Schritt einen seiner Platzhalter enthält – einmal je Serie, Schritt und Lauf für alle Empfänger, die in diesem Lauf wirklich eine Mail bekommen (
recipients:membershipId,userId,locale,timezone, bei Event-SerieneventIdundoccurrenceStart) – und bei der Testmail (preview = true; fehlende Werte nimmt der Kern ausexample()). - Solche Schritte verschickt der Plugin-Worker, nicht der Worker der Plattform: Ein langsamer Platzhalter verzögert nur diese Mails. Beendet der Aufruf den Prozess (Zeitgrenze, schwerer Fehler), gehen die Mails ohne die Werte dieses Plugins raus (siehe Zeitgrenzen).
- Werte sind reiner Text, höchstens 500 Zeichen: im HTML-Teil escaped, Zeilenumbrüche als Umbruch, im Betreff einzeilig. Fehlt ein Wert oder ist das Plugin aus, bleibt der Platzhalter leer; unbekannter Text in geschweiften Klammern bleibt stehen.
Bausteine für Landingpages
- Der Owner wählt den Baustein im Seiten-Editor (Einstellungen → Landingpages) und füllt die Felder. Felder sind
ExtraFieldohneon(),visibleTo()undeditableBy(); der Kern prüft sie wie Zusatzfelder (422unterblocks[<i>].data.<feld>). - Auf der öffentlichen Landingpage rendert der Kern die Vorlage
templates/blocks/…des Plugins mitdata(Feldwerte),vars(Ergebnis vonprepare()),block,community,pageundlocale.prepare()bekommt einenBlockContextmitviewer–nullfür Gäste: Die Seite ist öffentlich, also nur öffentliche Daten ausgeben. - Ist das Plugin in der Community aus, bleibt der Baustein gespeichert und erscheint nicht; neue Bausteine eines ausgeschalteten Plugins lehnt der Editor ab (
409).
Feldtypen für Formulare
- Der Owner wählt den Typ im Formular-Editor (Einstellungen → Formulare); gespeichert wird er als
type: pluginmitpluginType: <pluginId>.<key>. - Auf der Ausfüllseite rendert der Kern Beschriftung, Hilfe und Fehler, die Vorlage
templates/forms/…nur das Eingabefeld: Variablenfield(key,label,help,required),name(answers[<key>]– gelesen wird nur dieser Wert, Text oder Liste von Texten),id,value,error,viewer,community. Ohne Vorlage rendert der Kern ein Textfeld. validate()bekommt nur nicht leere Antworten (FormFieldInput:community,formId,context,fieldKey,label,required,value,viewer) und liefertFieldResult::ok($normalisiert)(gespeichert und in Einreichungen angezeigt, höchstens 2000 Zeichen) oderFieldResult::error($schlüssel, $parameter). Ohnevalidate()gilt die Prüfung des Kerns für Text (höchstens 500 Zeichen).- Ist das Plugin in der Community aus, entfällt das Feld beim Ausfüllen (auch ein Pflichtfeld); das Formular behält es.
templates/blocks/ bzw. templates/forms/; Twig escaped alle Werte; nie |raw, {% apply raw %} oder {% autoescape false %}, nie source() oder template_from_string(), und include/embed/import/extends nur auf eigene Vorlagen (@plugin_<id>/…; Ausnahme: das Mail-Layout email/_layout.html.twig unter templates/email/). Verstöße findet schon der Scan – das Plugin ist dann nicht ladbar und app:plugin:validate nennt den Grund (siehe Grenzen). Das fertige HTML prüft zusätzlich ein Sanitizer des Kerns: Struktur-, Text-, Listen- und Tabellenelemente, Links nur http(s) oder relativ auf /media/, /plugin-assets/ und /c/ (nie //…, mit rel="noopener nofollow ugc"), Bilder nur aus /media/ und /plugin-assets/, die Attribute class, ARIA, data-testid und data-ui; Feldtypen zusätzlich Eingabeelemente und id, name nur answers[<key>] bzw. answers[<key>][] des eigenen Felds. Skripte, style, iframes, Formulare und on…-Attribute entfernt er. Auf diesen Seiten lädt der Kern dist/plugin.css des Plugins; Plugin-JavaScript läuft dort nicht. Damit die Klassen der Vorlagen in dist/plugin.css landen, nennt frontend/plugin.css die Ordner als Quelle (@source "../templates/forms"; bzw. "../templates/blocks"). Die Plattform stellt jeden Baustein und jedes Feld in ein Element data-plugin="<id>"; die Klassen wirken nur darin, auch hidden oder block (siehe Geltungsbereich).
Einstellungen
scope(Scope::Community)ist der Standard: Owner und Admins pflegen die Werte unter Einstellungen → Plugins (auch vor dem Einschalten). Das gibt es nur bei Plugins mitperCommunity– ohneperCommunitybraucht jede Einstellung->scope(Scope::Platform), sonst wirftsetting()InvalidRegistration.Scope::Platform: Plattform-Admin auf der Detailseite unter/admin/plugins/<id>.- Weitere Methoden:
help(),default()(nicht beisecret),required(),maxLength(),min(),max(),options().exposeToMembers()(nur Community-Felder, niesecret) gibt den Wert ans Frontend (sdk.settings). - Der Kern rendert das Formular, prüft Typen und Grenzen (
422mitviolationsje Schlüssel) und ruft danach densettingsValidatorfür Abhängigkeiten zwischen Feldern. Einen eigenen Bereich unter dem Formular bringt der Slotsettings.plugin.<id>. - Lesen und schreiben:
$this->ctx->settings()->community($communityId)->get('maxSeats')bzw.->platform()->get('apiKey')– ohne gespeicherten Wert gilt der Standard.get()liefert beisecretden Klartext,all()alle Werte außer Geheimnissen,set()prüft wie das Formular;nullentfernt den Wert. - Protokoll:
community.plugin_settings_updatedbzw.platform.plugin.settings_updated, nur mit den Schlüsseln.
$this->ctx->state($communityId) (bzw. state() global) ist ein Schlüssel-Wert-Speicher für interne Merker, z. B. „zuletzt abgeglichen“. Schlüssel aus Kleinbuchstaben, Ziffern, _, ., - (bis 100 Zeichen), Werte als JSON bis 64 KB, je Schlüssel atomar; nie über die Einstellungen erreichbar und nicht verschlüsselt.
Jobs
Schedule::everyMinutes(int $n)(5–1440, Takt ab Mitternacht UTC),Schedule::hourly()(volle Stunde UTC),Schedule::dailyAt('HH:MM', $tz = 'Europe/Berlin')(einmal je Kalendertag in dieser Zeitzone; bei der Zeitumstellung rückt eine fehlende Uhrzeit nach hinten, eine doppelte gilt beim ersten Mal).- Der Worker prüft alle 5 Minuten, welche Jobs fällig sind: noch nie gelaufen oder seit dem letzten Fälligkeitszeitpunkt nicht mehr erfolgreich. Ein Job läuft nie doppelt gleichzeitig.
JobContext:now(),lastRunAt()(letzter erfolgreicher Lauf),communities()undforEachCommunity(\Closure)sowieshouldStop()(wird nach 4 Minuten wahr – dann sauber aufhören und beim nächsten Takt weitermachen).communities()liefert nur Communities, in denen das Plugin eingeschaltet ist, ohne gesperrte;forEachCommunity()ruft die Arbeit je solcher Community auf und fängt Ausnahmen je Community ab. Das passt für Arbeit, die nur dort anfällt (Erinnerungen, Auswertungen) – nicht für Abgleich und Löschfristen (unten).- Bei einer Ausnahme speichert der Kern den Fehler und versucht es beim nächsten Takt erneut; nach drei Versuchen je Fälligkeit wartet er bis zur nächsten. Ab 60 Sekunden Laufzeit gibt es eine Warnung.
- Ist das Plugin plattformweit aus, entfällt der Job.
Abgleich und Löschfristen
Hooks kommen höchstens einmal und können bei einem Ausfall fehlen. Ein täglicher Job gleicht die eigenen Daten deshalb mit dem Kern ab (siehe Datenbank → Verweise auf den Kern) und hält die Löschfristen ein, die der Absatz für die Datenschutzerklärung nennt. Er läuft über die Communities der eigenen Tabellen, nicht überforEachCommunity(): Das kennt nur Communities, in denen das Plugin eingeschaltet ist, und keine gesperrten. Schaltet ein Owner das Plugin aus, bleiben dessen Daten erhalten – die Fristen gelten dort weiter.
reconcile() mit den Kern-Diensten:
communities()->exists()– ist die Community gelöscht, kommen alle ihre Daten weg (das Netz unterdeleteCommunityData());events()->existing()– Daten gelöschter Events;events()->occurrence()je Termin –null, wenn es den Termin nicht mehr gibt (z. B. nach einer Änderung der Serie), sonst mitendfür Fristen ab dem Ende des Termins;members()->manyByMembership()mitcanRead()– Daten ausgetretener, entfernter und gesperrter Mitglieder.
ExamplePlugin::cleanup() im Beispiel-Plugin.
Aufgaben
Für Arbeit, die nicht in einen Request passt (große Exporte, PDF mit vielen Seiten, Massenaktionen):Tasks::dispatch(string $name, array $payload = [], ?string $communityId = null, ?int $delaySeconds = null): stringliefert sofort dietaskId. Payload als JSON höchstens 64 KB, Verzögerung höchstens 7 Tage. In GET-Handlern nicht erlaubt.- Abgeschickt wird erst nach dem Commit der äußersten Transaktion; bei einem Rollback entfällt die Aufgabe.
TaskContext:taskId,communityId,actorUserId(wer sie ausgelöst hat; entfällt, wenn die Person in dieser Community nicht mehr lesendes Mitglied ist),now.- Aufgaben laufen höchstens einmal, ohne automatische Wiederholung. Ein Fehler steht im Log und beim Plugin; die Person startet die Aktion neu. Ist das Plugin inzwischen aus, entfällt die Aufgabe.
- Muster für große Exporte: Aufgabe erzeugt die Datei →
storage()→ Glocke mit Link auf einen eigenen Endpunkt → der Endpunkt liefert perResponse::stream→ ein Job löscht alte Dateien nach 24 Stunden.
Hinweise und Session-Daten
- Hinweis: höchstens einer je Plugin und Seite, oberhalb des Seiteninhalts der Community (nach den Hinweisen zu Zahlung und Profil), nur für Personen mit Lesezugriff auf die Community.
textundlinkLabelsind Übersetzungsschlüssel (reiner Text) mit Parametern ausparams;pathnur ein lokaler Pfad;levelNotice::INFOoderNotice::WARNING. - Session-Daten: stehen dem Frontend als
sdk.datazur Verfügung, z. B. für eigene Rechte. Höchstens 4 KB JSON – größere verwirft der Kern mit einer Warnung. - Beide Rückrufe laufen bei jedem Seitenaufbau und schreibgeschützt; sie sollten schnell sein und dürfen nichts ändern.
Lebenszyklus
Implementiert die EinstiegsklasseLifecycle, ruft der Kern nach der jeweiligen Umschaltung (synchron, nach dem Commit):
Eine Ausnahme landet im Log; die Umschaltung gilt trotzdem. Steht eine Migration aus, entfällt der Aufruf (mit Warnung) und wird nicht nachgeholt.