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
\DateTimeImmutablein UTC. In Hook-Daten und Schlüsseln stehen sie als Text im FormatY-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 intranslations/messages.en.json(siehe Übersetzungen).
Einstiegsklasse
Die Klasse ausentry 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 beiprivacy.personalData) undDemoAware(siehe Datenschutz und Beispieldaten) sowieLifecycle(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:maxBytesje Datei höchstens 20 MB,maxFiles1–5, Endungen auspdf,jpg,jpeg,png,webp,csv,txtund ab Plugin-API 1.3xlsx(lesen übercsv()->readXlsx()). Nur bei POST, PUT und PATCH. OhneUploadRulelehnt der Endpunktmultipart/form-datamit415ab.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);perCommunitynur mit Community. Überschritten →429mitRetry-After.platformAdmins: falsefür besonders sensible Daten (z. B. Dokumente einer Mitgliederakte): Plattform-Admins ohne lesende Mitgliedschaft bekommen404. Nur mit Community.
/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).
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()undcsv()->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:- Das Plugin ist erkannt, gültig und plattformweit aktiv – sonst
404. - Bei Community-Endpunkten: Die Community existiert und ist nicht gelöscht – sonst
404. Eine Sperre der Community wirkt erst beim Zugriff (Schritt 5). - 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 immer404– 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 mit401. - Route: unbekannter Pfad
404, falsche Methode405mitAllow. - Zugriff (
Access): ohne Anmeldung401, ohne Recht403(angemeldete Personen ohne Mitgliedschaft404, siehe Schritt 3). In einer gesperrten Community verweigert der Kern hier jeden Zugriff außer für Plattform-Admins: Mitglieder bekommen403, andere404. platformAdmins: false: Plattform-Admin ohne lesende Mitgliedschaft →404.- Größe, Body und Uploads:
413(zu groß),400(ungültiges JSON),415(Upload ohneUploadRule),422(Datei passt nicht),429(Upload-Limit). - Limit der Route (
RateLimit) →429. - 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 vonException\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.
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.