---
title: "PHP-Schnittstelle"
description: "Einstiegsklasse, Registry, eigene Endpunkte mit Zugriff und Optionen, Request und Response (JSON, Datei, Stream, CSV, XLSX), Prüfreihenfolge und Fehlerformat"
---

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](/plugins/grenzen)).

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](/plugins/testen#ü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](/plugins/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](/plugins/datenschutz)) sowie `Lifecycle` (siehe [Erweiterungspunkte](/plugins/erweiterungspunkte#lebenszyklus)).

## Registry

| Methode | Zweck |
| --- | --- |
| `on(string $hook, \Closure $listener)` | auf ein Ereignis reagieren, `fn(HookEvent $e): void` (siehe [Hook-Katalog](/plugins/hooks)) |
| `api(string $method, string $path, \Closure $handler, Access $access = Access::Member, bool $community = true, ?ApiOptions $options = null)` | eigener JSON-Endpunkt, `fn(Request $r): Response\|array\|\JsonSerializable` |
| `page(string $path, string $title, Access $access = Access::Member, bool $community = true, ?\Closure $guard = null)` | Vue-Seite (siehe [Seiten](/plugins/erweiterungspunkte#seiten)) |
| `navItem(NavItem $item)` | Menüpunkt |
| `extraField(ExtraField $field)` | deklaratives Zusatzfeld an Events, Mitgliedern und (ab 1.2) Beiträgen, Kursen und Lektionen |
| `extension(Target $target, ResponseExtension $extension)` | Kern-Antworten zu Events, Mitgliedern, Leaderboard und (ab 1.2) Beiträgen, Kursen und Lektionen ergänzen; bei Events (`EventInputExtension`) bzw. Beiträgen, Kursen und Lektionen (`InputExtension`) auch Eingaben im Editor annehmen |
| `setting(SettingField $field)`, `settingsValidator(\Closure $validator)` | Einstellungen des Plugins und ihre Prüfung über Felder hinweg |
| `job(string $name, Schedule $schedule, \Closure $job)` | wiederkehrender Job, `fn(JobContext $c): void` |
| `task(string $name, \Closure $handler)` | Aufgabe im Hintergrund, `fn(TaskContext $c, array $payload): void` |
| `sessionData(\Closure $provider)` | Daten für das Frontend (`sdk.data`), `fn(Viewer, CommunityInfo): array` |
| `notice(\Closure $provider)` | Hinweis über dem Seiteninhalt, `fn(Viewer, CommunityInfo): ?Notice` |
| `privacyNotice(\Closure $provider)` | Absatz für die Datenschutz-Vorlage, `fn(?CommunityInfo): ?string` |
| `leaderboardRanking(\Closure $filter)` *(ab 1.2)* | [Filter](/plugins/erweiterungspunkte#filter-hooks) der Rangliste, `fn(RankingQuery): ?RankingChange` |
| `placeholders(array $placeholders, \Closure $provider)` *(ab 1.2)* | Platzhalter für E-Mail-Serien, `fn(PlaceholderQuery): array` |
| `pageBlock(PageBlock $block)` *(ab 1.2)* | Baustein für Landingpages |
| `formField(FormFieldKind $kind)` *(ab 1.2)* | Feldtyp für Formulare |

`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

```php
$registry->api('POST', '/offers/{offerId}/accept', $this->accept(...), Access::Writer);
$registry->api('GET', '/status', fn (Request $r) => ['ok' => true], Access::Public, community: false);
```

| | mit Community (`community: true`, Standard) | ohne Community |
| --- | --- | --- |
| Adresse | `/api/plugins/<id>/c/<slug><path>` | `/api/plugins/<id><path>` |
| Erlaubter Zugriff | `Member`, `Writer`, `Team`, `Manage`, `Owner`, `PlatformAdmin` | `Public` (nur GET), `User`, `PlatformAdmin` – also immer `access` angeben |
| Plugin je Community | antwortet nur, wo es eingeschaltet ist | – |

**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.

| `Access` | Wer |
| --- | --- |
| `Public` | jeder, auch ohne Anmeldung – nur GET, nur ohne Community |
| `User` | jede angemeldete Person |
| `Member` | lesendes Mitglied der Community (aktiv oder stummgeschaltet); Plattform-Admins ja |
| `Writer` | Mitglied, das schreiben darf (nicht stummgeschaltet); Plattform-Admins nur mit eigener schreibender Mitgliedschaft |
| `Team` | Moderator, Admin, Owner; Plattform-Admins ja |
| `Manage` | Admin und Owner; Plattform-Admins ja |
| `Owner` | Owner; Plattform-Admins ja |
| `PlatformAdmin` | Plattform-Admins |

**Optionen** (`ApiOptions`):

```php
new ApiOptions(
    maxJsonBytes: 1_048_576,                                         // Standard 1 MiB, höchstens 10 MiB; größer → 413
    upload: new UploadRule(maxBytes: 10_000_000, extensions: ['pdf', 'jpg', 'png'], maxFiles: 3),
    rateLimit: RateLimit::perUser(20, '10 minutes'),                 // zusätzlich zum allgemeinen API-Limit
    platformAdmins: false,                                           // Plattform-Admins ohne Mitgliedschaft → 404
)
```

- `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`).

<Warning>
**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()`.
</Warning>

## Request

| Methode | Liefert |
| --- | --- |
| `method()` | HTTP-Methode |
| `param(string $name)` | Wert eines Platzhalters `{name}` (unbekannter Name → `LogicException`) |
| `query(string $name, ?string $default = null)` | Abfrageparameter |
| `json()` | JSON-Body als Array; größer als `maxJsonBytes` → `413`, kaputt → `400` |
| `input(string $name, ?string $default = null)` | Formularfeld bei `multipart/form-data` |
| `file(string $name)`, `files(string $name)` | vom Kern geprüfte Upload-Datei(en) als `UploadedFile` |
| `viewer()` | handelnde Person als `Model\Viewer`; `null` nur bei `Access::Public` ohne Anmeldung |
| `community()` | `Model\CommunityInfo` bei Community-Endpunkten, sonst `null` |
| `header(string $name)` | Kopfzeile |
| `locale()` | Sprache des Requests (`de` oder `en`) |

`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](/plugins/kern-dienste#dateien-und-dokumente)).

## Response

Ein Handler liefert ein Array oder ein `\JsonSerializable` (wird zu JSON mit Status 200) oder eine `App\Plugin\Api\Response`:

| Fabrik | Ergebnis |
| --- | --- |
| `Response::json(mixed $data, int $status = 200)` | JSON mit Status 200–299 |
| `Response::noContent()` | `204` |
| `Response::file(string\|resource $content, string $filename, string $mimeType, bool $inline = false)` | Datei |
| `Response::stream(\Closure $producer, string $filename, string $mimeType, ?int $size = null, bool $inline = false)` | Datei blockweise: `$producer` bekommt einen Schreiber `fn(string $chunk)` |
| `Response::csv(array $header, iterable $rows, string $filename)` | CSV: UTF-8 mit BOM, Trennzeichen `;`, Zeilenende CRLF, Textzellen gegen Formel-Einschleusung geschützt, Kommazahlen mit Dezimalkomma |
| `Response::xlsx(array $sheets, string $filename)` | Excel-Datei mit 1–20 Blättern (`Model\Sheet`) |
| `Response::redirect(string $path)` | Umleitung (302), nur auf Pfade derselben Seite |

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)`:

```php
use App\Plugin\Api\ColumnFormat;
use App\Plugin\Api\Model\Sheet;
use App\Plugin\Api\Response;

return Response::xlsx([
    new Sheet(
        title: 'Buchungen',
        header: ['Datum', 'Mitglied', 'Nummer', 'Betrag'],
        rows: $this->bookings($communityId),   // iterable<list<scalar|null>>, auch ein Generator
        formats: [0 => ColumnFormat::Date, 2 => ColumnFormat::Text, 3 => ColumnFormat::Money],
        currency: 'EUR',
    ),
], 'buchungen-2026-10.xlsx');
```

- 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.

| Ausnahme | Status |
| --- | --- |
| `NotFound` | `404` – auch für fremde und gelöschte IDs |
| `Forbidden` | `403`, ohne Anmeldung `401` |
| `Conflict` | `409` – Zustand passt nicht, Grenze erreicht |
| `PayloadTooLarge` | `413` |
| `ValidationFailed(array $violations)` | `422` mit `violations` – je Feldpfad ein Schlüssel oder `[Schlüssel, Parameter]` |
| `TooManyRequests(int $retryAfter)` | `429` mit `Retry-After` |
| `TimestampUnavailable` | `409` (kein Zeitstempel möglich, mit Grund) |

```php
throw new ValidationFailed([
    'seats' => ['Höchstens {max} Plätze.', ['max' => 8]],
    'phone' => 'Bitte gib eine gültige Mobilnummer an.',
]);
```

```json
{
  "type": "urn:problem:validation-failed",
  "title": "Die Eingaben sind ungültig.",
  "status": 422,
  "detail": "Die Eingaben sind ungültig.",
  "instance": "/api/plugins/mitfahren/c/demo/offers",
  "violations": [
    { "propertyPath": "seats", "message": "Höchstens 8 Plätze.", "code": null },
    { "propertyPath": "phone", "message": "Bitte gib eine gültige Mobilnummer an.", "code": null }
  ]
}
```

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.
