Plugins sprechen den Kern ausschließlich über den Namensraum App\Plugin\Api an. Außerdem erlaubt sind Psr\Log, Psr\Clock, Doctrine\DBAL (Verbindung, Parameter-Typen), Symfony\Component\Uid und die eingebauten Klassen von PHP. Interne Klassen von QuickTribe, Symfony-Komponenten wie HttpFoundation oder HttpClient und Klassen anderer Plugins sind tabu (siehe Grenzen und Regeln). Grundsätze für alle Teile der Schnittstelle:
  • IDs sind UUID-Strings, kleingeschrieben (0192f0e4-…).
  • Zeiten sind \DateTimeImmutable in UTC. In Hook-Daten und Schlüsseln stehen sie als Text im Format Y-m-d\TH:i:s\Z (PluginApi::TIME_FORMAT, z. B. 2026-11-03T18:00:00Z).
  • Texte schreibst du auf Deutsch; der deutsche Text ist zugleich der Übersetzungsschlüssel, Platzhalter in geschweiften Klammern ({name}), ohne ICU-Plural. Englisch steht in translations/messages.en.json (siehe Übersetzungen).

Einstiegsklasse

Die Klasse aus entry implementiert App\Plugin\Api\Plugin. Der Kern erzeugt sie mit new Entry($context) – der Konstruktor nimmt genau einen PluginContext (siehe Kern-Dienste) – und ruft register(Registry $registry) einmal je Request, je Worker-Auftrag bzw. je Konsolenlauf auf, solange das Plugin aktiv ist.
  • In register() und im Konstruktor wird nur registriert: keine Datenbank-, Datei- oder Netzzugriffe. Beide laufen schreibgeschützt.
  • Eine ungültige Registrierung wirft Exception\InvalidRegistration (ein Programmierfehler, keine Meldung für Nutzer). Das Plugin gilt dann für diesen Lauf als fehlerhaft; der Plattform-Admin zeigt den Fehler.
  • Weitere, optionale Schnittstellen der Einstiegsklasse: PrivacyAware (Pflicht bei privacy.personalData) und DemoAware (siehe Datenschutz und Beispieldaten) sowie Lifecycle (siehe Erweiterungspunkte).

Registry

sessionData, notice, privacyNotice, settingsValidator, leaderboardRanking und placeholders gibt es je Plugin höchstens einmal, extension() je Ziel höchstens einmal. InvalidRegistration werfen außerdem: doppelte Routen, ungültige Pfade oder Platzhalter, unpassender Zugriff (Tabelle unten), doppelte Feld-Schlüssel und unbekannte Hook-Namen.

Endpunkte

Pfade: Segmente aus a–z, 0–9, ., _, - und Platzhalter {name} (Buchstabe, dann bis zu 30 Buchstaben und Ziffern), höchstens 10 Segmente, '' ist die Wurzel. Die Platzhalter slug, pluginId und rest sind dem Kern vorbehalten, globale Pfade beginnen nie mit /c/. Feste Segmente gehen vor Platzhaltern, sonst entscheidet die Reihenfolge der Registrierung. Erlaubte Methoden: GET, POST, PUT, PATCH, DELETE; HEAD und OPTIONS erreichen nie einen Handler. Zugriff (Access) bildet die Rechte von QuickTribe ab; eigene, feinere Rechte prüft der Handler selbst. Optionen (ApiOptions):
  • UploadRule: maxBytes je Datei höchstens 20 MB, maxFiles 1–5, Endungen aus pdf, jpg, jpeg, png, webp, csv, txt und ab Plugin-API 1.3 xlsx (lesen über csv()->readXlsx()). Nur bei POST, PUT und PATCH. Ohne UploadRule lehnt der Endpunkt multipart/form-data mit 415 ab.
  • RateLimit::perUser|perIp|perCommunity(int $limit, string $interval): gleitendes Fenster, Grenze bis 100 000, Intervall wie '30 seconds', '10 minutes', '1 hour', '1 day' (höchstens 7 Tage); perCommunity nur mit Community. Überschritten → 429 mit Retry-After.
  • platformAdmins: false für besonders sensible Daten (z. B. Dokumente einer Mitgliederakte): Plattform-Admins ohne lesende Mitgliedschaft bekommen 404. Nur mit Community.
Über das Präfix /api/ gilt für Plugin-Endpunkte außerdem alles, was für die Schnittstelle von QuickTribe gilt: Anmeldung über die Sitzung, CSRF-Kopfzeile X-CSRF-Token bei POST, PUT, PATCH und DELETE (das SDK setzt sie), das allgemeine Limit api je Person, die Kopfzeile Idempotency-Key, die Sperre bis zur Zwei-Faktor-Bestätigung (401) und der Wartungsmodus (503).
GET ändert nichts. Solange ein GET-Handler läuft, werfen alle schreibenden Methoden der Kern-Dienste eine LogicException – z. B. Database::insert|update|delete|execute, schreibende Methoden von Speicher, Nachrichten und Einstellungen, Mailer::send, Notifications::notify und Tasks::dispatch. Erlaubt bleibt Audit::log (etwa für Abrufprotokolle). Dasselbe gilt für register(), Ausgabe-Rückrufe (sessionData, notice, Erweiterungen beim Laden) und validate().

Request

UploadedFile hat path (Temp-Datei, löscht der Kern nach dem Request), cleanName (bereinigter Dateiname), size, detectedMimeType (aus dem Inhalt ermittelt, nie die Angabe des Browsers) und extension. Vor dem Handler prüft der Kern je Datei Größe, Endung und passenden Inhaltstyp (sonst 422 am Feld); jede Datei zählt im Upload-Limit von QuickTribe (60 je Stunde und Person, sonst 429). Wer Dokumente oder Bilder dauerhaft ablegt, bereitet sie mit files()->prepareDocument() bzw. prepareImage() auf (siehe Kern-Dienste).

Response

Ein Handler liefert ein Array oder ein \JsonSerializable (wird zu JSON mit Status 200) oder eine App\Plugin\Api\Response: Kopfzeilen setzt ausschließlich der Kern. JSON bekommt Cache-Control: private, no-store; Dateien zusätzlich X-Content-Type-Options: nosniff, eine abschottende Content-Security-Policy (default-src 'none'; … sandbox), Cross-Origin-Resource-Policy: same-origin und Referrer-Policy: no-referrer. inline: true wirkt nur bei PNG, JPEG, WebP, GIF und PDF; alles andere ist immer ein Download. Andere Rückgaben (z. B. Symfony-Responses) ergeben 500. Ein Fehler, nachdem ein Stream begonnen hat, bricht die Übertragung ab und landet im Log. Excel: Ein Blatt beschreibt new Sheet(title, header, rows, formats, currency):
  • Blattnamen: 1–31 Zeichen, ohne [ ] : * ? / \, je Datei ohne Groß/Klein eindeutig; höchstens 200 Spalten und 100 000 Zeilen je Blatt.
  • ColumnFormat: Text (auch Ziffernfolgen wie Postleitzahlen bleiben Text), Integer, Decimal (zwei Nachkommastellen), Money (Betrag in Cent als Integer, angezeigt mit Währung), Date (Y-m-d), DateTime (Y-m-d H:i, bereits in der gewünschten Zeitzone).
  • Text steht immer als Text in der Zelle – Excel wertet ihn nie als Formel aus. Die erste Zeile ist fett, fixiert und hat einen Autofilter.
  • In Aufgaben, die das Ergebnis ablegen statt es auszuliefern, liefern csv()->write() und csv()->xlsx() dieselben Dateien als Bytes.

Prüfreihenfolge

Für jeden Aufruf eines Plugin-Endpunkts prüft der Kern in dieser Reihenfolge; dieselben Regeln gelten für Seiten, Menüpunkte, Hinweise, Session-Daten, Felder, Erweiterungen und Slots:
  1. Das Plugin ist erkannt, gültig und plattformweit aktiv – sonst 404.
  2. Bei Community-Endpunkten: Die Community existiert und ist nicht gelöscht – sonst 404. Eine Sperre der Community wirkt erst beim Zugriff (Schritt 5).
  3. Bei Plugins je Community: Das Plugin ist in dieser Community eingeschaltet – sonst 404. Angemeldete Personen ohne lesende Mitgliedschaft (und ohne Plattform-Admin-Recht) bekommen bei Community-Endpunkten ab hier immer 404 – auch für unbekannte Pfade, falsche Methoden und fehlende Rechte. So verrät die Antwort nicht, ob ein Plugin in einer fremden Community eingeschaltet ist. Ohne Anmeldung gilt das für unbekannte Pfade und Methoden; eine vorhandene Route antwortet mit 401.
  4. Route: unbekannter Pfad 404, falsche Methode 405 mit Allow.
  5. Zugriff (Access): ohne Anmeldung 401, ohne Recht 403 (angemeldete Personen ohne Mitgliedschaft 404, siehe Schritt 3). In einer gesperrten Community verweigert der Kern hier jeden Zugriff außer für Plattform-Admins: Mitglieder bekommen 403, andere 404.
  6. platformAdmins: false: Plattform-Admin ohne lesende Mitgliedschaft → 404.
  7. Größe, Body und Uploads: 413 (zu groß), 400 (ungültiges JSON), 415 (Upload ohne UploadRule), 422 (Datei passt nicht), 429 (Upload-Limit).
  8. Limit der Route (RateLimit) → 429.
  9. Der Handler läuft – bei GET schreibgeschützt, mit der angemeldeten Person als handelnder Person (Protokoll, Aufgaben).

Fehler

Fachliche Fehler wirft der Handler als Unterklasse von Exception\PluginException. Die Meldung ist ein deutscher Übersetzungsschlüssel mit ICU-Parametern; der Kern übersetzt sie mit dem Katalog des Plugins in der Sprache des Requests und antwortet im Format application/problem+json (RFC 9457) wie die übrige Schnittstelle.
Jede andere Ausnahme ergibt 500 ohne detail – nichts aus dem Plugin dringt nach außen. Die Ausnahme steht im Log (Kanal plugins, plugin.<id>.api_failed) und als letzter Fehler im Plattform-Admin.