Alle Erweiterungspunkte registriert die Einstiegsklasse in 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; title ist 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 /api oder /dist.
  • guard: fn(Viewer $viewer, ?CommunityInfo $community): bool prüft eigene Rechte; false oder eine Ausnahme ergibt 404 wie bei Seiten von QuickTribe.
  • Unbekannte oder gelöschte Communities leiten zur Startseite; Mitglieder ohne das nötige Recht bekommen 403, Fremde 404.

Menüpunkte

  • label: Übersetzungsschlüssel, höchstens 60 Zeichen. path ohne Platzhalter; dort sollte eine Seite registriert sein.
  • icon: eines von award, 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): bool blendet 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 unter extra.<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 über PUT /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 nach visibleTo, 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 eine ResponseExtension 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 kein extra.
  • 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ässt extra.<pluginId> weg, die Antwort bleibt 200.
  • Nie in öffentlichen Seiten, Kalenderdateien, der REST-API, E-Mails, der Suche oder im Profil-Abschnitt „letzte Beiträge“.
Eingaben im Event-Editor: Eine 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): array prüft fachlich vor dem Speichern und liefert Feldpfad → Übersetzungsschlüssel bzw. [Schlüssel, Parameter]; der Kern antwortet mit 422 unter extra.<pluginId>.<feld>. validate() läuft für alle in der Community eingeschalteten Plugins mit Eingabe-Erweiterung, auch ohne eigene Daten (data() ist dann null) – 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): void speichert in derselben Transaktion wie das Event und nur, wenn data() nicht null ist. Hier keine fachlichen Prüfungen – eine Ausnahme rollt alles zurück (500).
  • ExtensionInput liefert community(), actor(), creating(), eventId() (beim Anlegen null), draft() (Werte nach der Änderung als Model\EventDraft), previous() (vorher) und data().
  • 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.
Eingaben an Beitrag, Kurs und Lektion (ab 1.2): Eine 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:
  • TargetInput liefert community(), actor(), target(), creating(), targetId() (beim Anlegen null), core() und data(). 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 (challenge oder all), from/to (Zeitraum in UTC, bei all null), entries (ganze Rangliste, höchstens 1000 Einträge mit membershipId und points).
  • 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-Serien eventId und occurrenceStart) – und bei der Testmail (preview = true; fehlende Werte nimmt der Kern aus example()).
  • 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 ExtraField ohne on(), visibleTo() und editableBy(); der Kern prüft sie wie Zusatzfelder (422 unter blocks[<i>].data.<feld>).
  • Auf der öffentlichen Landingpage rendert der Kern die Vorlage templates/blocks/… des Plugins mit data (Feldwerte), vars (Ergebnis von prepare()), block, community, page und locale. prepare() bekommt einen BlockContext mit viewer – null fü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: plugin mit pluginType: <pluginId>.<key>.
  • Auf der Ausfüllseite rendert der Kern Beschriftung, Hilfe und Fehler, die Vorlage templates/forms/… nur das Eingabefeld: Variablen field (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 liefert FieldResult::ok($normalisiert) (gespeichert und in Einreichungen angezeigt, höchstens 2000 Zeichen) oder FieldResult::error($schlüssel, $parameter). Ohne validate() 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.
Sicherheit für Bausteine und Feldtypen: Vorlagen liegen nur unter 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 mit perCommunity – ohne perCommunity braucht jede Einstellung ->scope(Scope::Platform), sonst wirft setting() InvalidRegistration. Scope::Platform: Plattform-Admin auf der Detailseite unter /admin/plugins/<id>.
  • Weitere Methoden: help(), default() (nicht bei secret), required(), maxLength(), min(), max(), options(). exposeToMembers() (nur Community-Felder, nie secret) gibt den Wert ans Frontend (sdk.settings).
  • Der Kern rendert das Formular, prüft Typen und Grenzen (422 mit violations je Schlüssel) und ruft danach den settingsValidator für Abhängigkeiten zwischen Feldern. Einen eigenen Bereich unter dem Formular bringt der Slot settings.plugin.<id>.
  • Lesen und schreiben: $this->ctx->settings()->community($communityId)->get('maxSeats') bzw. ->platform()->get('apiKey') – ohne gespeicherten Wert gilt der Standard. get() liefert bei secret den Klartext, all() alle Werte außer Geheimnissen, set() prüft wie das Formular; null entfernt den Wert.
  • Protokoll: community.plugin_settings_updated bzw. platform.plugin.settings_updated, nur mit den Schlüsseln.
Zustand ohne Formular: $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() und forEachCommunity(\Closure) sowie shouldStop() (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 über forEachCommunity(): 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.
Je Community prüft reconcile() mit den Kern-Diensten:
  • communities()->exists() – ist die Community gelöscht, kommen alle ihre Daten weg (das Netz unter deleteCommunityData());
  • 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 mit end für Fristen ab dem Ende des Termins;
  • members()->manyByMembership() mit canRead() – Daten ausgetretener, entfernter und gesperrter Mitglieder.
Das vollständige Muster zeigt 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): string liefert sofort die taskId. 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 per Response::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. text und linkLabel sind Übersetzungsschlüssel (reiner Text) mit Parametern aus params; path nur ein lokaler Pfad; level Notice::INFO oder Notice::WARNING.
  • Session-Daten: stehen dem Frontend als sdk.data zur 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 Einstiegsklasse Lifecycle, 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.