---
title: "Kern-Dienste"
description: "PluginContext und alle Fassaden: Communities, Mitglieder, Einladungen, Events, Postleitzahlen, Gruppen-Chats, Benachrichtigungen, E-Mail, Forderungen und Lastschrift, Speicher, Dokumente, Signaturen, Zeitstempel, PDF, CSV/Excel, Protokoll und mehr"
---

Der `PluginContext`, den der Konstruktor der Einstiegsklasse bekommt, ist der einzige Weg zu Daten und Diensten von QuickTribe. Die Schnittstellen der Dienste liegen unter `App\Plugin\Api\Service`, die Modelle unter `App\Plugin\Api\Model`.

## Regeln für alle Dienste

1. **Community zuerst.** Jede Methode, die Daten einer Community liest oder ändert, nimmt die Community-ID als **ersten** Parameter und prüft die Zugehörigkeit jeder übergebenen ID selbst. Eine fremde ID ergibt `null`, eine leere Liste oder `NotFound` – nie fremde Inhalte.
2. **Gelöschte Communities** verhalten sich wie fremde. **Gesperrte** liefern Daten (für Jobs und Aufräumen); `communities()->enabledFor()` und `JobContext::communities()` lassen sie aus – Abgleichs- und Löschjobs laufen deshalb über die Communities der eigenen Tabellen (siehe [Abgleich und Löschfristen](/plugins/erweiterungspunkte#abgleich-und-löschfristen)).
3. **Sichtbarkeit wie im Kern.** Wo ein `Viewer` übergeben wird, liefert der Dienst höchstens, was diese Person in QuickTribe sehen darf. Rechte des Plugins erweitern das nie (einzige Ausnahme: `members()->snapshotName()`, protokolliert).
4. **Viewer erzeugt nur der Kern** – über `Request::viewer()`, `ExtensionQuery::viewer()` oder `members()->viewerFor()` (für Jobs, Hooks und Aufgaben).
5. **GET ändert nichts.** Schreibende Methoden werfen in GET-Handlern und Ausgabe-Rückrufen eine `LogicException` (siehe [PHP-Schnittstelle](/plugins/php-api#endpunkte)).
6. E-Mail-Adressen gibt kein Dienst heraus – Ausnahmen für Plugins mit `privacy.memberEmails` (protokolliert): ab Plugin-API 1.3 der Abgleich `members()->verifiedEmail()`/`matchEmails()`, ab 1.4 die Anzeige `members()->loginEmails()` für Owner und Admins; ab 1.8 darf ein solches Plugin Adressen ohne Konto über `mailer()->sendToAddress()` anschreiben; das volle Geburtsdatum nur `members()->birthDates()` an Owner und Admins (wie das Alter).

## PluginContext

| Methode | Liefert |
| --- | --- |
| `id()`, `version()` | Plugin-ID und Version aus `plugin.json` |
| `path(string $rel = '')` | absoluter Pfad im Plugin-Ordner (ohne `..`) |
| `communities()`, `members()`, `invites()`, `events()`, `geo()`, `messages()` | Daten der Plattform (unten) |
| `notifications()`, `mailer()` | Glocke, Push, E-Mail |
| `debits()` | Forderungen melden und ihren Stand lesen (ab Plugin-API 1.1, unten) |
| `db()` | eigene Tabellen (siehe [Datenbank und Migrationen](/plugins/datenbank)) |
| `storage()`, `files()`, `crypto()`, `timestamps()` | Dateien, Uploads, Verschlüsselung, Signaturen, Zeitstempel |
| `pdf()`, `views()`, `html()`, `csv()` | Dokumente und Formate |
| `settings()`, `state(?string $communityId = null)` | Einstellungen und Zustand (siehe [Einstellungen](/plugins/erweiterungspunkte#einstellungen)) |
| `security()`, `audit()`, `translator()`, `urls()`, `tasks()` | Bestätigung, Protokoll, Übersetzung, Adressen, Aufgaben |
| `limiter(string $name, int $limit, string $interval)`, `cache(?string $communityId = null)` | eigene Limits und Zwischenspeicher |
| `clock()`, `logger()` | Uhr (PSR-20) und Log (PSR-3, Kanal `plugins`) |

Plugin-API 1.2 bringt keine neuen Dienste, nur einen neuen Aufruf (`members()->birthDates()`, unten): Beiträge, Kurse, Lektionen, E-Mail-Serien, Landingpages und Formulare liest ein Plugin nicht direkt. IDs kommen aus den [Hooks](/plugins/hooks), eigene Angaben je Objekt gibt das Plugin über [Erweiterungen](/plugins/erweiterungspunkte#erweiterungen-von-kern-antworten) aus (nur für Objekte, die der Betrachter sehen darf), und die [Filter-Hooks](/plugins/erweiterungspunkte#filter-hooks) bekommen alles, was sie brauchen, als Anfrage.

## Communities

| Methode | Zweck |
| --- | --- |
| `get(string $idOrSlug): ?CommunityInfo` | gelöschte nie, gesperrte mit `suspended = true` |
| `exists(string $communityId): bool` | für Abgleichs-Jobs |
| `enabledFor(): list<CommunityInfo>` | Communities, in denen das Plugin eingeschaltet ist (weder gesperrt noch gelöscht) – nicht für Abgleich und Löschfristen |
| `branding(string $communityId): Branding` | Logo als PNG-`data:`-URI, rechtlicher Name und Anschrift aus den Rechnungsangaben – für PDF-Dokumente |

## Mitglieder

| Methode | Zweck |
| --- | --- |
| `get($communityId, $userId)` | Mitglied mit Lesezugriff (aktiv oder stummgeschaltet) oder `null` |
| `byMembership($communityId, $membershipId)` | Mitgliedschaft in jedem Status |
| `many($communityId, $userIds, ?Viewer $viewer = null)` | mehrere lesende Mitglieder (`userId →`); Abzeichen nur mit Viewer |
| `manyByMembership($communityId, $membershipIds)` | mehrere Mitgliedschaften in jedem Status |
| `all($communityId, ?array $statuses = null)` | alle als `iterable` (intern seitenweise) |
| `list($communityId, ?string $status, int $offset, int $limit)`, `count($communityId, ?string $status = null)` | Seiten (höchstens 200) und Anzahl |
| `search($communityId, string $query, Viewer $viewer, int $limit = 20)` | Suche ab 2 Zeichen, höchstens 50 Treffer; Vor- und Nachnamen nur, wenn der Viewer sie sehen darf, nie E-Mail-Adressen |
| `findByEmail($communityId, string $email, Viewer $actor)` | exakter Abgleich einer Adresse, nur für Owner/Admins (`Manage`), protokolliert; die Adresse selbst kommt nie zurück |
| `verifiedEmail($communityId, $membershipId, string $purpose)` | Ab Plugin-API **1.3**, nur mit `privacy.memberEmails: true` im Manifest (sonst `LogicException`). Bestätigte E-Mail-Adresse einer lesenden oder wartenden Mitgliedschaft dieser Community (nicht bestätigt, ausgetreten, gesperrt, gelöschtes Konto oder fremd: `null`). Zum Abgleich mit eigenen Daten, nicht zur Anzeige – z. B. eine Akte aus einer Vereinsliste dem beitretenden Konto zuordnen. `purpose` Pflicht (1–200 Zeichen); jeder Aufruf steht im Protokoll der Community (`plugin.<id>.email_read`, ohne die Adresse). Nur in Hooks, Jobs und Aufgaben oder im Request von Owner, Admins und Plattform-Admins (sonst `Forbidden`) – nie die Adresse an Personen ohne Verwalterrecht weitergeben |
| `matchEmails($communityId, array $emails, string $purpose)` | Ab Plugin-API **1.3**, nur mit `privacy.memberEmails`. Welche der übergebenen Adressen (höchstens 500) gehören einem bestätigten Konto mit Mitgliedschaft in dieser Community? Ergebnis: normalisierte Adresse → `MemberInfo`. Gibt keine Adressen heraus, die das Plugin nicht schon kennt; `MemberInfo::$status` sagt, ob die Mitgliedschaft lesend ist. Kontext wie `verifiedEmail()`; ein Protokolleintrag je Aufruf (`plugin.<id>.email_match` mit Zahl der Adressen und Treffer) – Ergebnisse besser zwischenspeichern (als Prüfsumme) als je Seite neu fragen |
| `team($communityId, Role $minRole = Role::Moderator)`, `isTeam()`, `isManager()` | Team der Community (die Prüfungen zählen Plattform-Admins mit) |
| `customRoles($communityId, Viewer $viewer)`, `withCustomRole()`, `hasCustomRole()` | eigene Rollen (interne nur für das Team) |
| `viewerFor($communityId, $userId)` | `Viewer` für Jobs, Hooks und Aufgaben; `null` ohne bzw. bei gelöschtem Konto |
| `personalData($communityId, $userIds, Viewer $viewer)` | Name und Anschrift (`PersonalDataView`) mit derselben Sichtbarkeit wie im Kern. Zeigt die Community allen Mitgliedern nur den Vornamen, ist für Viewer außerhalb des Kreises für den vollen Namen `firstNameOnly` true und `lastName` null. `lastName` null heißt sonst „verborgen oder nicht eingetragen“ – nur `firstNameOnly` unterscheidet. Den vollen Namen nur zeigen, wenn `firstNameOnly` false ist. Ab Plugin-API **1.4** zusätzlich `street`, `addressExtra`, `postalLines` (Anschrift ohne Name und Firma: Zusatz, Straße, „PLZ Ort“, Land nur bei Ausland) und `phone` (Handynummer, nur wenn die Community sie abfragt und der Viewer sie laut Einstellung sieht – Team bzw. nur Owner und Admins) |
| `correctionScope($communityId, $membershipId, Viewer $viewer)` | Ab Plugin-API **1.4**. Was der Viewer an Name, Geburtsdatum, Anschrift und Handynummer dieser Mitgliedschaft korrigieren darf (`CorrectionScope`: je Feldgruppe `…Asked` und `…Editable`, `addressScope` `full` oder `postal_code`, `companyAsked`, `sharedHint`, `defaultCountry`) – dieselbe Regel wie „Persönliche Angaben korrigieren“ im Kern: Owner und Admins nur nach unten bei aktiven oder stummen Mitgliedschaften, Plattform-Admins. Nutzt eine andere Community der Person dasselbe Feld, ist es nicht `…Editable` – Text für die Oberfläche in `sharedHint`. `null` = gar nichts |
| `correctPersonalData($communityId, $membershipId, PersonalDataCorrection $correction, Viewer $viewer)` | Ab Plugin-API **1.4**. Korrigiert die Angaben am Konto wie der Kern (wirkt in allen Communities der Person, Glocke und Pflicht-Mail mit Begründung, Protokoll `member.personal_identity_corrected` nur mit Feldnamen). Name und Geburtsdatum kann die Person danach nicht mehr selbst ändern, Anschrift und Handynummer schon. Je Feld `null` = unverändert, leer = entfernen; `address` (`AddressInput`) immer als Ganzes; `reason` Pflicht. Nur im schreibenden Request der angemeldeten Person (`$viewer` = Akteur). Fehler: `Forbidden`, `NotFound`, `Conflict` (Feld nicht abgefragt oder auch von anderen Communities genutzt), `ValidationFailed` (Feldpfade `reason`, `firstName`, `lastName`, `birthday`, `address.street`, `address.postalCode` …, `phone`), `TooManyRequests` (10 je Stunde je Akteur und Person). Rückgabe: geänderte Felder (`firstName`, `lastName`, `birthday`, `address`, `phone`) – für ein eigenes Änderungsprotokoll ohne Werte |
| `loginEmails($communityId, array $membershipIds, Viewer $viewer)` | Ab Plugin-API **1.4**, nur mit `privacy.memberEmails`. Anmelde-E-Mail-Adresse (`LoginEmail`: `email`, `verified`) je Mitgliedschaft zur **Anzeige** für Owner, Admins und Plattform-Admins, nur im Request (sonst `Forbidden`); jeder Status, gelöschte Konten und fremde fehlen, höchstens 500. Protokoll `plugin.<id>.email_viewed` höchstens einmal je Betrachter, Mitgliedschaft und Tag. Nur in Detailansichten nutzen, nicht in Listen |
| `missingProfileData($communityId, array $membershipIds, Viewer $viewer)` | Ab Plugin-API **1.4**. Welche Pflichtangaben laut aktueller Community-Einstellung am Konto fehlen (`birthday`, `name`, `address`, `phone` – dieselbe Regel wie beim Beitritt; „nur Postleitzahl“ ist nie Pflicht). Nur für Team-Viewer (sonst leer), nie Werte; Mitgliedschaften ohne Fehlendes fehlen im Ergebnis, höchstens 500 |
| `snapshotName($communityId, $membershipId, string $purpose)` | Vor- und Nachname **unabhängig von der Sichtbarkeit** – nur für gesetzlich vorgeschriebene Dokumentation, nur wenn die Community Namen abfragt; `purpose` Pflicht, protokolliert als `plugin.<id>.personal_data_read`. Als Momentaufnahme speichern – Vor- und Nachname getrennt – und Betrachtern nur im Umfang der Kern-Sichtbarkeit zeigen: liefert `personalData()` für den Betrachter nichts, keinen Namen; bei `firstNameOnly` nur den Vornamen |
| `accountSnapshot($communityId, $userId)` | Ab Plugin-API **1.5**, nur mit `privacy.accountSnapshot: true` (sonst `LogicException`). Momentaufnahme der Personendaten eines eben gelöschten Kontos (`AccountSnapshot`: `displayName`, `firstName`, `lastName`, `company`, `street`, `addressExtra`, `postalCode`, `city`, `country`, `birthDate` `Y-m-d`, `phone` E.164, `deletedAt`) – je Community nur, was sie abfragt, sonst `null`. Liefert nur etwas, während der Kern `deleteUserData()` für genau diese Person aufruft (auch bei Wiederholungen); sonst `null`. Nie E-Mail-Adressen; die Daten stehen in keinen Hook-Daten |
| `ageCheck($communityId, $membershipId, int $years, string $localDate)` | Ist die Person am Tag `Y-m-d` mindestens `$years` alt? `atLeast`, `below`, `missing` (kein Geburtsdatum) oder `notCollected` (Community fragt keinen Geburtstag ab) – nie das Alter selbst |
| `ages(…, Viewer $viewer)`, `birthdays(…, Viewer $viewer)` | Alter (nur für Owner/Admins) bzw. Tag und Monat des Geburtstags (wie im Profil) – nur, wenn die Community Geburtstage abfragt |
| `birthDates($communityId, array $membershipIds, Viewer $viewer)` | Ab Plugin-API **1.2** (`"pluginApi": "^1.2"`). Volles Geburtsdatum `Y-m-d` je Mitgliedschaft – nur für Owner/Admins und Plattform-Admins (derselbe Kreis wie `ages`), nur wenn die Community Geburtstage abfragt, Mitgliedschaften dieser Community in jedem Status – lesend, wartend (Anträge), ausgetreten bzw. entfernt und gesperrt, weil eine Verwaltung ihre Akten über die Mitgliedschaft hinaus führt (fremde fehlen im Ergebnis; ohne Angabe oder bei gelöschtem Konto `null`). Das Opt-out „Geburtstag zeigen“ gilt hier wie beim Alter nicht – es betrifft Tag und Monat für andere Mitglieder. Für Verwaltungsansichten wie eine Mitgliedsakte; nicht an Mitglieder weitergeben. Ein Plugin, das es nutzt, meldet das im Manifest (`privacy.birthDates: true`), damit die Datenschutz-Vorlage es nennt |
| `extraFields($communityId, $membershipIds, ?Viewer $viewer = null)` | Werte der eigenen [Zusatzfelder](/plugins/erweiterungspunkte#zusatzfelder) |
| `ownPhone(Viewer $viewer)`, `normalizePhone(string $input, ?string $country = null)` | Mobilnummer der Person selbst – nur lesende Mitglieder, nur die angemeldete Person selbst (im eigenen Request bzw. Ausgabe-Rückruf; ein Viewer aus `viewerFor()`, Jobs und Hooks bekommen `null`). Normalisierung ins internationale Format (`null` = unbrauchbar): Leerzeichen, `-`, `/`, `.`, Klammern und `(0)` werden entfernt, `00` wird `+`; ab Plugin-API **1.4** auch nationale Schreibweisen wie `0151 23456789` oder `172 123123` im Land `$country` (ISO-Code; ohne Angabe das Standard-Land der Community des laufenden Aufrufs, sonst DE). Sonder- und Mehrwertrufnummern gelten nie |
| `ownAddress(string $communityId, Viewer $viewer)` | Anschrift der Person selbst ohne Namen (`addressLines`, `postalCode`, `city`, `country`) – nur lesende Mitglieder, nur die angemeldete Person selbst (wie `ownPhone`, Community = die des Viewers), nur wenn die Community die volle Anschrift abfragt und Straße, Postleitzahl und Ort gepflegt sind; für Formulare, die die Person selbst ausfüllt |
| `endMembership($communityId, $userId, $actorUserId)` | Mitgliedschaft beenden mit denselben Folgen wie „Entfernen“ (Pläne und Abos enden, Zusagen werden frei); prüft die Rangfolge des Akteurs, nie beim Owner. Nur nach ausdrücklicher Bestätigung in der Oberfläche aufrufen |

`MemberInfo` enthält `membershipId`, `userId`, `communityId`, `displayName`, `avatarUrl`, `role` (`Role::Member|Moderator|Admin|Owner`), `status` (`pending`, `active`, `muted`, `banned`, `left`), `joinedAt`, `profilePath`, `accountDeleted`, `badges`, `nameColor` und `canRead()`.

## Einladungen

`invites()->create($communityId, $actorUserId, int $maxUses = 1, ?\DateTimeImmutable $expiresAt = null, ?string $planId = null): InviteInfo` legt einen Einladungslink an – mit denselben Rechten (Admin aufwärts) und demselben Protokoll wie in der Oberfläche; `revoke($communityId, $inviteId, $actorUserId)` zieht ihn zurück. `InviteInfo` liefert die absolute `url`. Plugins zeigen den Link an und geben ihn von Hand weiter – oder verschicken ihn ab Plugin-API 1.3 mit `send()`. Wer über den Link beitritt, erscheint im Hook `member.joined` mit `inviteId`.

`invites()->send($communityId, $actorUserId, string $email, ?string $recipientName = null, ?\DateTimeImmutable $expiresAt = null, string $locale = 'de'): ?InviteInfo` (ab Plugin-API **1.3**) legt einen Einladungslink für genau einen Beitritt an (Beitritt ohne Freigabe, Ablauf Standard 30 Tage, höchstens 365) und schickt ihn per E-Mail an die Adresse – auch an Personen ohne Konto. Der Text stammt immer vom Kern („… lädt dich ein, der Community … beizutreten“, `de` oder `en`); Plugins können ihn nicht ändern, damit sich die Funktion nicht zum Versand beliebiger Inhalte eignet. `recipientName` erscheint nur als Anrede. Rechte wie `create()` (Admin aufwärts). Grenzen: höchstens 3 Einladungen je Adresse und Community in 24 Stunden (darüber `null`; gezählt wird erst der Versand) und das [Einladungs-Kontingent](/plugins/grenzen) des Plugins (Standard 50 je Stunde und Community, getrennt von `mailer()->send()`) – ist es erschöpft, wirft `send()` `TooManyRequests` mit `retryAfter()`; das Plugin reiht den Rest ein und versucht es später (z. B. in einem Job). Wird ein Link nicht mehr gebraucht (neue Einladung, Datensatz gelöscht), zieht das Plugin ihn mit `revoke()` zurück. Protokoll `invite.mailed` mit gekürzter Adresse.

## Events

| Methode | Zweck |
| --- | --- |
| `get($communityId, $eventId)`, `many()` | Event bzw. Serie (`EventInfo`) – **ungeprüft**: vor einer Ausgabe `viewable()` oder `lockReason()` fragen |
| `viewable($communityId, $eventIds, Viewer $viewer)` | die Events, die der Viewer sehen darf (nicht gesperrt durch Plan, Level, Alter, Kurs) |
| `lockReason($communityId, $eventId, Viewer $viewer)` | übersetzter Sperrtext oder `null` |
| `canManage($communityId, $eventId, Viewer $viewer)` | darf das Event bearbeiten (Team oder anlegende Person) |
| `existing($communityId, $eventIds)` | noch vorhandene Events (Abgleichs-Job) |
| `occurrence($communityId, $eventId, $start)` | ein Termin (`Occurrence`): `$start` als RFC 3339 oder Zeitpunkt; ohne Start der nächste, sonst der letzte; `null`, wenn es ihn nicht gibt |
| `occurrenceExists()`, `occurrencesOf($communityId, $eventId, $from, $to)`, `occurrences($communityId, $from, $to)` | Termine einer Serie bzw. aller Events (Zeitraum höchstens 366 Tage) |
| `isGoing()`, `goingKeys($communityId, $membershipId, $eventIds)`, `attendees($communityId, $eventId, $start)` | Zusagen |
| `isCancelled($communityId, $eventId, $start): bool` | ab Plugin-API **1.9**: Ist dieser Termin abgesagt (von Hand oder weil die Mindestteilnehmerzahl zum Stichtag nicht erreicht war)? `false` bei unbekanntem Event |
| `cancelledKeys($communityId, $eventIds): list<string>` | ab Plugin-API **1.9**: Vorkommens-Schlüssel aller abgesagten Termine dieser Events in einer Abfrage – für Listen statt `isCancelled()` je Termin |
| `extraFields($communityId, $eventIds, ?Viewer $viewer = null)` | Werte der eigenen Zusatzfelder |

Ein `Occurrence` hat `eventId`, `start`, `end`, `draft` (Termin einer Vorschau, ab 1.3 – nur an Terminen aus `events()` verlässlich, nicht an selbst gebauten) und `key()` = `<eventId>|<Y-m-d\TH:i:s\Z>` – derselbe Schlüssel wie in Hook-Daten und Erweiterungen. **Der Kern verschiebt keine Zusagen:** Nach einer Änderung des Zeitplans (Hook `event.updated` mit `scheduleChanged`) prüft das Plugin seine Termine mit `occurrenceExists()`. Bei Serien vergleicht man mit `recurrenceEnd` (UTC), nicht mit `recurrenceUntil` (Kalendertag in der Zeitzone des Events).

**Abgesagte Termine (ab 1.9):** Abgesagt wird immer ein einzelner Termin, nie die ganze Serie; Zusagen und Wartelistenplätze bleiben dabei gespeichert – `isGoing()`, `goingKeys()` und `attendees()` liefern sie weiter. Ein `Occurrence` trägt den Zustand nicht; frage ihn mit `isCancelled()` bzw. für Listen einmal mit `cancelledKeys()` ab (die Schlüssel entsprechen `Occurrence::key()`). Für abgesagte Termine sollte ein Plugin nichts erinnern und nichts Neues anbieten, vorhandene Daten aber behalten: Die Absage kann zurückgenommen werden (Hooks `event.cancelled` und `event.reinstated`, siehe [Hooks](/plugins/hooks#regeln)).

## Postleitzahlen und Entfernungen

`geo()` arbeitet mit dem eingebauten Verzeichnis der Postleitzahlen (Deutschland, Österreich, Schweiz, Polen, Frankreich, Spanien, Niederlande, Italien, Tschechien; Niederlande nur über die vier Ziffern) ohne externe Dienste: `supports($country)`, `locate($country, $postalCode): ?GeoPoint`, `placeName()`, `postalCodeError()` (übersetzte Meldung oder `null`), `viewerLocation($communityId, Viewer)` (nur, wenn die Community Postleitzahl oder Anschrift abfragt), `status($communityId, Viewer)` (ob Entfernungen möglich sind, mit Hinweis und Link zum Konto), `distanceKm(GeoPoint, GeoPoint)` und `displayKm()` (unter 10 km eine Nachkommastelle).

## Gruppen-Chats

Plugins legen **eigene, verwaltete Gruppen** an; alle anderen Methoden wirken nur auf Gruppen dieses Plugins in derselben Community (sonst `NotFound`).

| Methode | Zweck |
| --- | --- |
| `groupsAllowed($communityId)` | Gruppen-Chats in der Community nicht ganz ausgeschaltet |
| `createGroup($communityId, $ownerUserId, $title, $userIds, ?string $firstMessage = null, bool $notify = false)` | neue Gruppe; liefert die ID oder `null`, wenn Gruppen-Chats aus sind. Teilnehmer nur lesende Mitglieder mit aktivem Konto (andere still übersprungen), höchstens 50; Titel reiner Text (auf 80 Zeichen gekürzt); der Owner wird Teilnehmer und Verwalter |
| `exists()`, `participants()` | Gruppe noch da? Teilnehmer (User-IDs) |
| `addParticipants($communityId, $conversationId, $userIds, ?string $actorUserId = null, bool $notify = false)` | Personen hinzufügen – nur bei Zustandswechseln (z. B. Bestätigung), nie in Abgleichsschleifen; liefert die tatsächlich Hinzugefügten |
| `removeParticipant($communityId, $conversationId, $userId, ?string $actorUserId = null)` | entfernen; `actorUserId = userId` heißt „hat die Gruppe verlassen“ |
| `systemMessage($communityId, $conversationId, $senderUserId, string $key, array $params = [])` | Systemhinweis in der Sprache des Absenders, ohne Benachrichtigung |

`notify: false` unterdrückt die Glocke „… hat dich hinzugefügt“ – das Plugin benachrichtigt dann selbst. Die Oberfläche zeigt bei solchen Gruppen ein Schildchen mit dem Plugin-Namen und sperrt Umbenennen, Hinzufügen und Entfernen; Verlassen bleibt möglich. Gruppen können jederzeit verschwinden (alle sind gegangen) – vorher `exists()` prüfen und bei Bedarf neu anlegen. Auf eine gelöschte Gruppe werfen `addParticipants` und `systemMessage` `Conflict`.

## Benachrichtigungen

```php
$this->ctx->notifications()->notify(
    $communityId, $userId,
    'Neue Mitfahranfrage', '{name} möchte am {date} mitfahren.',
    $this->ctx->urls()->eventPath($slug, $eventId, $start),
    ['name' => $name, 'date' => $date],
    email: true, actorUserId: $viewer->userId, collapse: true,
);
```

- Empfänger ist ein lesendes Mitglied mit aktivem Konto und nie der Akteur selbst; sonst `false`.
- `path` beginnt mit `/c/<slug derselben Community>/`, höchstens 500 Zeichen, ohne Schema oder `//` – sonst `InvalidArgumentException`.
- Titel und Text übersetzt der Kern in die Sprache des Empfängers; reiner Text, gekürzt auf 160 bzw. 300 Zeichen.
- Glocke und Push gehen immer zusammen. `email: true` schickt zusätzlich eine E-Mail, wenn eine neue Glocke entsteht und der Empfänger „E-Mails von Erweiterungen“ nicht abbestellt hat. `collapse: true` legt keine neue Glocke an, solange eine ungelesene Glocke dieses Plugins mit demselben Pfad existiert; dann entfällt auch die E-Mail, nur der Push geht hinaus.
- Höchstens 60 je Stunde, Empfänger und Plugin; darüber `false` und ein Log-Eintrag.
- Eine Glocke gilt automatisch als gelesen, sobald der Empfänger die Plugin-Seite des Pfads geöffnet hat und sie zu sehen ist – verglichen wird der Pfad ohne Abfrage und Anker (z. B. `/c/<slug>/plugins/<id>/fahrten`), gezählt werden nur Glocken, die vor dem Öffnen der Seite entstanden sind. Zeigt der Pfad auf einen Beitrag (`/feed/posts/<id>`) oder einen Kommentar (`#comment-<id>`), zählt erst, wenn dieser zu sehen war.
- `forget($communityId, $path, ?string $userId = null)` entfernt Glocken des Plugins mit diesem Pfad, z. B. wenn eine Anfrage zurückgezogen wurde.
- **Zweite Mitteilung zum selben Ziel:** Eine Erinnerung nach einer ersten Glocke mit demselben Pfad schickt man **ohne** `collapse` und entfernt die alte vorher mit `forget($communityId, $path, $userId)` – sonst geht sie bei allen unter, die die erste Glocke noch nicht gelesen haben, samt E-Mail.

## E-Mails

`mailer()->send($communityId, $userId, string $subjectKey, string $template, array $vars = [], array $params = [], array $attachments = [], bool $mandatory = false): bool`

- Vorlagen liegen unter `templates/email/` des Plugins (`'email/angebot.html.twig'`) und erweitern das Layout der Plattform; Texte darin übersetzt der Filter `ptrans`:

  ```twig
  {% extends 'email/_layout.html.twig' %}
  {% block content %}
      <p>{{ 'Hallo {name}, deine Fahrt am {date} ist bestätigt.'|ptrans({ name: recipientName, date: date }) }}</p>
  {% endblock %}
  ```

  Der Kern setzt `recipientName`, `communityName`, `communityUrl` und `unsubscribeUrl` sowie Absender, Sprache und Signatur der Community. Der Betreff `subjectKey` ist ein Übersetzungsschlüssel mit `params`.
- Empfänger: Mitglied der Community mit gültiger Adresse. Gewöhnliche Mails gehen nur an lesende Mitglieder mit eingeschalteter Einstellung „E-Mails von Erweiterungen“ und bekommen einen Abmeldelink und `List-Unsubscribe`.
- `mandatory: true` nur für Bestätigungen eigener Handlungen und rechtlich nötige Mitteilungen – erreicht dann auch nicht lesende Mitglieder und ignoriert die Einstellung.
- Anhänge (`[['name' => …, 'mimeType' => …, 'content' => …]]`) zusammen höchstens 10 MB. Höchstens so viele Mails je Stunde, Plugin und Community, wie der Plattform-Admin unter **Plugins** einstellt (Standard 300, ab Plugin-API 1.3 einstellbar; Einladungen über `invites()->send()` haben ein eigenes Kontingent); darüber `false`.

`mailer()->sendToAddress($communityId, string $email, string $name, string $locale, string $subjectKey, string $template, array $vars = [], array $params = [], array $attachments = [], bool $mandatory = false): bool` (ab Plugin-API **1.8**)

- Mail an eine Adresse **ohne Konto**, z. B. ein Rundschreiben an Mitglieder, die nur als Akte geführt werden. Nur mit `privacy.memberEmails: true` im Manifest, sonst `LogicException`.
- Gleiche Vorlagen, Anhänge und dasselbe Kontingent wie `send()`; `recipientName` in der Vorlage ist der übergebene `name` (reiner Text, höchstens 100 Zeichen). Sprache `locale` `de` oder `en`, sonst `de`. Ungültige Adressen (höchstens 180 Zeichen) ergeben `false`.
- Gewöhnliche Mails bekommen einen Abmeldelink und `List-Unsubscribe` je **Adresse, Community und Plugin**. Wer sich abmeldet, bekommt von diesem Plugin in dieser Community nur noch Mails mit `mandatory: true` (ohne Abmeldelink); `sendToAddress()` gibt dann `false` zurück und verbraucht kein Kontingent. Die Plattform speichert dafür nur einen Prüfwert der Adresse, nie die Adresse selbst; die Abmeldeseite nennt Community und Plugin, nicht die Adresse. Groß- und Kleinschreibung der Adresse spielen keine Rolle.
- Ob jemand ein Konto hat, prüft der Kern nicht – hat eine Person ein Konto, nimmt das Plugin `send()` (dort gelten die Einstellungen ihres Kontos).

`mailer()->remaining($communityId): int` (ab Plugin-API **1.8**) nennt die noch freien Mails im laufenden Stunden-Kontingent des Plugins in der Community, ohne etwas zu buchen – auch in GET-Handlern erlaubt. Für Versand in Blöcken: im Job höchstens `remaining()` Mails schicken und den Rest später.

`mailer()->signatureStatus($communityId): ?string` (ab Plugin-API **1.8**) sagt, ob die E-Mail-Signatur der Community, die unter jeder Mail steht, Aufmerksamkeit braucht: `missing` (keine eigene Signatur), `review` (Angaben zum Anbieter seit dem letzten Speichern geändert) oder `null`. Gepflegt wird sie unter Einstellungen → Rechtstexte (`/c/{slug}/settings/legal#mail-signature`). Zeige den Hinweis nur Owner und Admins (`viewer.isManager`) – nur sie können die Signatur ändern. Nur lesend, auch in GET-Handlern erlaubt.

## Forderungen und Lastschrift

Ab Plugin-API **1.1** (`"pluginApi": "^1.1"` im Manifest). Plugins melden **Forderungen** – Beiträge, Standgebühren, Munition, Verzehr –, QuickTribe zieht sie per SEPA-Lastschrift ein (SEPA-Datei der Bank oder Stripe), mahnt und gleicht aus. Bankverbindung, Mandat und Einzug gehören der Plattform; ein Plugin sieht nie IBAN, BIC, Kontoinhaber oder Bankname und nur Forderungen, die es selbst gemeldet hat.

| Methode | Zweck |
| --- | --- |
| `setup(string $communityId): DebitSetup` | Lastschrift an/aus, Verfahren, Zeitzone, Frist der Vorabinformation, Rhythmus, Gebühr, Pfad der Kasse |
| `submit(string $communityId, ClaimInput $input, ?string $actorUserId = null): Claim` | eine Forderung melden |
| `submitMany(string $communityId, array $inputs, ?string $actorUserId = null): list<SubmitResult>` | bis zu 500 auf einmal; je Eintrag `created`, `existing` oder `skipped` mit Grund |
| `get()`, `byReference()`, `byReferences()` | eigene Forderungen lesen |
| `list(string $communityId, ClaimQuery $query): ClaimPage` | eigene Forderungen in Änderungsreihenfolge, mit Cursor zum Abgleichen |
| `cancel(string $communityId, string $claimId, string $reason, ?string $actorUserId = null): Claim` | offene Forderung stornieren (ohne Teilausgleich und ohne nicht stornierte Gegenforderung) |
| `settleCash(string $communityId, string $claimId, int $amountCents, string $settledOn, ?string $note, string $actorUserId): Claim` | bar ausgleichen, auch in Teilen (z. B. an der Theke bezahlt) |
| `mandates(string $communityId, list<string> $membershipIds): array` | Mandatsstand je Mitgliedschaft: Status, Art, Referenz, Datum, „einziehbar“ |
| `standings(string $communityId, list<string> $membershipIds, Viewer $viewer): array` | Zahlungsstand über alle Quellen – nur für Betrachter mit Mitgliedschaft in dieser Community; ob ein Zahlungsproblem besteht, sehen die Person selbst und das Team (sonst `null`), Beträge nur Kasse und Verwaltung |

- **`ClaimInput`**: zahlungspflichtige Mitgliedschaft, Betrag in Cent (negativ = Gutschrift), Text (≤ 140 Zeichen), `reference`, Fälligkeit `dueOn` (`Y-m-d`), Währung nur `EUR`; optional Kategorie (z. B. „Munition“, „Beitrag“), Leistungszeitraum, Leistung für eine andere Mitgliedschaft (`subjectMembershipId`, z. B. Kind im Haushalt) oder eine Bezeichnung (`subjectLabel`, z. B. Gast), korrigierte Forderung (`correctsClaimId`) und `detailPath` (eine Seite des Plugins mit den Einzelposten).
- **Idempotenz:** Die `reference` ist je Plugin und Community eindeutig (Groß-/Kleinschreibung egal). Dieselbe Meldung noch einmal liefert dieselbe Forderung; abweichende Beträge, Mitglieder oder Fälligkeiten unter derselben Referenz werden abgelehnt (`reference_conflict`). Eine gemeldete Forderung ändert sich nie – korrigiert wird durch Stornieren (solange offen) oder eine Gegenforderung mit negativem Betrag. **Nach einem Storno ist die Referenz verbraucht:** erneut gemeldet wird sie übersprungen (`reference_cancelled`, `submit()` wirft `Conflict`); wer neu melden will, nimmt eine neue Referenz, z. B. mit dem Zusatz `:v2`.
- **Formfehler** (`ClaimInput::violations()`) brechen den ganzen Aufruf ab (`ValidationFailed`, bei `submitMany` mit Pfaden wie `3.amountCents`); fachliche Ausschlüsse – Mitglied unbekannt, Konto gelöscht, Referenz vergeben, Korrektur passt nicht – meldet `submitMany` je Eintrag.
- Melden geht nur, solange das Plugin in der Community eingeschaltet ist; lesen, stornieren und bar ausgleichen auch danach. Schreibende Methoden werfen in GET-Handlern eine `LogicException`.
- **Wer handelt** (`$actorUserId`, `null` = das Plugin selbst): ein lesendes Mitglied der Community mit bestehendem Konto, in einem Request nur die angemeldete Person – sonst `InvalidArgumentException`. Bei `settleCash()` ist der Akteur Pflicht; wer kein lesendes Mitglied ist, bekommt `Forbidden`.
- **Datumsangaben** (`dueOn`, Leistungszeitraum, `ClaimQuery`-Filter, `settledOn`) sind echte Kalendertage `JJJJ-MM-TT` – `2026-02-30` ergibt `ValidationFailed`.
- **Überfällig** (`Claim::$overdue`) rechnet QuickTribe bei jedem Lesen gegen die aktuelle Uhr; ein Teilausgleich lässt eine Überfälligkeit stehen, erst der volle Ausgleich beendet sie.
- Trifft ein Schreibvorgang auf eine Sperre (Deadlock), wiederholt QuickTribe ihn bis zu dreimal – außer innerhalb von `db()->transactional()`, dort entscheidet das Plugin.
- **Abgleich:** `list()` liefert einen Cursor; das Plugin speichert ihn und liest später weiter – so verpasst es keine Änderung, auch wenn ein Hook nicht ankam.
- Hooks dazu: [Forderungen](/plugins/hooks#forderungen). Was die Kasse mit den Forderungen tut – Einzug, Rückläufer, Mahnung, Ausgleich –, beschreibt das [Handbuch für die Kasse](/handbuch/kasse/ueberblick).
- **Testen:** `App\Tests\Support\Plugin\InMemoryDebits` verhält sich wie der Dienst (derselbe Vertragstest prüft beide, mehr unter [Testen](/plugins/testen#forderungen-ohne-kern-testen)):

```php
$debits = new InMemoryDebits('schiessbuch', $clock);
$debits->addCommunity($communityId, 'sv-musterhausen');
$debits->addMembership($communityId, $membershipId, $userId);
$claim = $debits->submit($communityId, new ClaimInput($membershipId, 1250, 'Schießbuch Oktober 2026 – Munition', 'sb:2026-10:'.$membershipId.':ammo', '2026-11-01', category: 'Munition'));
// wie ein GET-Handler der Person $userId: schreibende Methoden werfen LogicException
$debits->request($userId, true, fn () => $debits->get($communityId, $claim->id));
// Rückbuchung nachstellen: zurückgebucht und ab dem 24.11. überfällig
$debits->simulate($claim->id, ClaimStatus::Returned, overdueOn: '2026-11-24', returnReason: 'insufficient_funds');
```

### Ergebnisse und Modelle

**`submitMany()`** liefert je Eintrag in derselben Reihenfolge ein `SubmitResult` mit `index`, `outcome` und – bei `created`/`existing` – der Forderung (`claim`). Fachlich ausgeschlossene Einträge kommen als `skipped` mit `reason`:

| `reason` | Bedeutung |
| --- | --- |
| `membership_not_found` | Mitgliedschaft bzw. `subjectMembershipId` unbekannt oder aus einer anderen Community |
| `account_deleted` | das Konto der zahlungspflichtigen Person ist gelöscht |
| `reference_conflict` | die Referenz ist schon mit anderen Beträgen, Mitgliedern oder Fälligkeiten vergeben |
| `reference_cancelled` | die Referenz gehört zu einer stornierten Forderung und ist verbraucht |
| `correction_invalid` | `correctsClaimId` passt nicht (unbekannt, fremd, storniert, andere Mitgliedschaft, oder die Korrekturen übersteigen den Betrag) |

**`DebitSetup`** (`setup()`, auch bei ausgeschalteter Lastschrift): `enabled`, `method` (`DebitMethod::SepaFile` bzw. `Stripe`), `currency` (immer `EUR`), `timezone` (in dieser Zone liest der Kern `dueOn` und die Leistungsdaten, Standard `Europe/Berlin`), `prenotificationDays`, `schedule` (`manual` beim Datei-Verfahren – die Kasse legt Einzüge an; bei der Stripe-Lastschrift `monthly`, `weekly` oder `daily`), `nextCollectionOn` (nur Stripe: Tag, an dem der nächste automatische Einzug angelegt wird – eingezogen wird erst nach der Ankündigungsfrist), `returnFeeEnabled`, `returnFeeCents` und `treasuryPath` (`/c/<slug>/debit`, für einen Link „Zur Kasse“ in Team-Ansichten).

**`MandateInfo`** (`mandates()`, ohne Bankdaten): `status` (`MandateStatus::None`, `Pending`, `Active`, `Revoked`, `Expired`), `method`, `kind` (`paper`, `online`, …), `reference`, `signedOn`, `lastCollectedAt` und `collectible` (Mandat aktiv, Verfahren passt, Lastschrift an). `collectible` ist eine notwendige, keine hinreichende Bedingung: Eine nach einer Rückgabe gesperrte Bankverbindung oder eine zu kurze Ankündigungsfrist berücksichtigt es nicht – ob tatsächlich eingezogen wird, entscheidet die Kasse mit dem Einzug. Eine **gemahnte Forderung** (`dunningLevel > 0`, auch nach einer Zahlungsaufforderung) zieht der Kern nie von selbst ein, auch nicht bei `collectible`: nur, wenn die Kasse „erneut einziehen“ wählt – sonst gleicht das Mitglied per Überweisung aus. Die Mandatsreferenz darf in Team-Ansichten erscheinen.

**`PaymentStanding`** (`standings()`): `hasPaymentProblem` folgt derselben Regel wie die Event-Sperre (Plan mit ruhenden Rechten oder überfällige Forderung, über alle Quellen). Welche Felder gefüllt sind, hängt vom Betrachter ab:

| Betrachter | `hasPaymentProblem` | `detailed`, `planRightsPaused`, `overdueCents`, `overdueCount`, `dunningLevel`, `openCents` |
| --- | --- | --- |
| die Person selbst | ja | nein (`null`) |
| Team (Moderator aufwärts) | ja | nein |
| Kasse, Admins, Owner, Plattform-Admins | ja | ja (`detailed = true`) |
| andere Mitglieder | `null` | nein |

Ohne Mitgliedschaft in **dieser** Community wirft `standings()` `Forbidden`. Fremde Mitgliedschafts-IDs fehlen im Ergebnis von `mandates()` und `standings()`.

**`Claim`** enthält neben den Angaben der Meldung `status` (`ClaimStatus`, mit `isFinal()` und `isOutstanding()`), `openCents` (Vorzeichen wie der Betrag, `0` bei `paid`, `settled`, `cancelled`), `overdue` und `overdueOn`, `dunningLevel` (0–3), `returnReason`, die ID des letzten Einzugs und die Zeitpunkte `paidAt`, `returnedAt`, `settledAt`, `cancelledAt` (UTC).

### Abgleich über den Cursor

Hooks kommen höchstens einmal. Ein Plugin, das den Stand seiner Forderungen spiegelt, liest deshalb regelmäßig – etwa in einem täglichen Job – alle Änderungen seit dem letzten Lauf:

```php
use App\Plugin\Api\Model\ClaimQuery;

$cursor = $ctx->state($communityId)->get('claims.cursor');   // null beim ersten Lauf
do {
    $page = $ctx->debits()->list($communityId, new ClaimQuery(cursor: $cursor, limit: 500));
    foreach ($page->claims as $claim) {
        $this->mirror->update($claim->reference, $claim->status, $claim->openCents, $claim->overdue);
    }
    $cursor = $page->cursor;
} while ($page->hasMore);
$ctx->state($communityId)->set('claims.cursor', $cursor);
```

`ClaimQuery` filtert zusätzlich nach `membershipId`, `statuses` (Liste von `ClaimStatus`), `category`, `dueFrom` und `dueTo` (`Y-m-d`, inklusive). Der Cursor ist undurchsichtig; `list()` liefert immer einen, auch auf der letzten Seite.

### Fehler

| Ausnahme | Wann |
| --- | --- |
| `ValidationFailed` | Formfehler der Meldung (`ClaimInput::violations()`, Pfade wie `3.amountCents` bei `submitMany`), ungültiges Datum (`2026-02-30`), `detailPath` einer anderen Community |
| `NotFound` | fremde oder unbekannte Community bei `setup()` und den schreibenden Methoden; unbekannte Forderung (`cancel()`, `settleCash()`) oder Mitgliedschaft (`submit()`). Die lesenden Methoden `get()`, `byReference()`, `byReferences()`, `list()`, `mandates()` und `standings()` liefern bei fremder oder unbekannter Community stattdessen `null` bzw. ein leeres Ergebnis |
| `Conflict` | Plugin in der Community ausgeschaltet (`submit()`, `submitMany()`); Referenz vergeben oder verbraucht, Konto gelöscht, Korrektur ungültig (`submit()`); Storno nicht mehr möglich; `settleCash()` mit Datum in der Zukunft oder mehr als dem offenen Betrag |
| `Forbidden` | `settleCash()` mit einem Akteur, der kein lesendes Mitglied ist; `standings()` ohne Mitgliedschaft des Betrachters |
| `InvalidArgumentException` | Programmierfehler: mehr als 500 Einträge, ungültiger Cursor, Akteur nicht die angemeldete Person |
| `LogicException` | schreibende Methode in einem GET-Handler oder Ausgabe-Rückruf |

## Dienste

Ab Plugin-API **1.6** (`"pluginApi": "^1.6"`, `"quicktribe": ">=2.33"`; Startjahr ab **1.7**, `"quicktribe": ">=2.34"`; Bestätigung durch das Team ab **1.9**, `"quicktribe": ">=2.37"`). Der Kern führt **Dienst-Arten** (Einstellungen → Dienste: Name, Soll je Kalenderjahr, Startjahr, optional an Pläne gebunden), markiert Events als **Dienst-Event** (jede Zusage zählt) oder gibt ihnen **Dienst-Slots** (Aufgaben mit eigener Platzzahl neben der Teilnehmerzahl) und schreibt nach dem Ende eines Termins jeden geleisteten Dienst in ein Ledger – wie bei den Punkten zählen nur Eingecheckte, sobald es am Termin Check-ins gab. Das Soll gilt für lesende Mitglieder ohne Team-Rolle, bei Plan-Bindung nur mit einem der Pläne. Plugins lesen Dienst-Arten, Stand und Einträge, lesen und buchen Slots; Soll, Ledger, Regeln, Glocken, Protokoll und die Oberfläche bleiben beim Kern.

| Methode | Zweck |
| --- | --- |
| `all(string $communityId): list<DutyInfo>` | Dienst-Arten der Community in Reihenfolge |
| `get(string $communityId, string $dutyId): ?DutyInfo` | eine Dienst-Art; fremd → `null` |
| `standing(string $communityId, string $membershipId, ?int $year, Viewer $viewer): list<DutyStanding>` | Stand eines Mitglieds: geltende Arten zuerst, dann Arten mit Einträgen (auch gelöschte, `dutyId` `null`) und geplanten Buchungen; Jahr `null` = laufendes Jahr in der Zeitzone des Mitglieds. Nur die Person selbst, das Team (ab Moderator) und Plattform-Admins (sonst `Forbidden`) |
| `standings(string $communityId, list<string> $membershipIds, ?int $year, Viewer $viewer): array` | Stand vieler Mitglieder (bis 500) in zwei Abfragen – alle Dienst-Arten der Community je Mitgliedschaft, gelöschte fehlen; nur Team und Plattform-Admins; fremde IDs fehlen |
| `completions(string $communityId, string $membershipId, int $year, Viewer $viewer): list<DutyCompletion>` | geleistete Dienste eines Mitglieds im Jahr, neueste zuerst – nur Dienste, die zählen (bestätigt); Sichtbarkeit wie `standing()` |
| `pendingCount(string $communityId, ?int $year = null): int` *(ab 1.9)* | Zahl der geleisteten Dienste, die noch auf die Bestätigung des Teams warten – in der ganzen Community, mit Jahr nur die des Kalenderjahres; fremde Community → 0 |
| `slots(string $communityId, string $eventId, \DateTimeImmutable $start): list<DutySlotInfo>` | Slots eines Termins mit Belegung – alle, auch Plan-gebundene (die Sichtbarkeit je Mitglied ergibt sich aus `DutyInfo::$planIds`, oder das Plugin überlässt sie `book()`) |
| `book(string $communityId, string $eventId, \DateTimeImmutable $start, string $slotId, string $membershipId, Viewer $viewer): void` | Slot übernehmen: für die eigene Mitgliedschaft wie „Dienst übernehmen“ (ohne Zusage entsteht sie mit, wer wartet, wird „going“), für andere als Team wie „Mitglied eintragen“ |
| `release(...)` | Slot abgeben – die Zusage bleibt und zählt wieder auf die Teilnehmerzahl; für andere nur als Team |

- **Regeln beim Buchen:** dieselben wie bei einer Zusage – Schreibrecht, Sperre des Events (Plan, Level, Alter), keine Vorschau, Termin nicht vorbei, Anmeldezeitraum, Zahlungssperre, verlangtes Formular, dazu die Plan-Bindung der Dienst-Art und die Platzzahl des Slots (voll → `Conflict`, keine Warteliste). Trägt das Team ein, gelten Formular, Anmeldezeitraum und Zahlungssperre nicht, die Slot-Grenze schon. Im Request ist der Viewer die angemeldete Person (sonst `InvalidArgumentException`); in GET-Handlern und Ausgabe-Rückrufen werfen `book()`/`release()` eine `LogicException`.
- **Sichtbarkeit:** Der Schalter „Stand im Profil für alle Mitglieder sichtbar“ betrifft nur die Oberfläche – für Plugins sehen den Stand immer nur die Person selbst, das Team und Plattform-Admins. Wer den Stand anderer Mitglieder anzeigt, prüft selbst, wem er ihn zeigt.
- **Zählung:** `completed` = Ledger-Zeilen (eine je Mitgliedschaft und Termin, Slot vor Dienst-Event), `planned` = künftige Zusagen zu Dienst-Events bzw. gebuchte Slots (nach dem Jahr des Terminbeginns in UTC); `DutyStanding::missing()` = fehlende Dienste gegenüber dem Soll, `isBehind()` = erledigt plus geplant unter dem Soll. **Startjahr (ab 1.7):** Das Soll gilt erst ab `DutyInfo::$startYear`; für frühere Jahre ist `DutyStanding::$expected` `null` (wie bei einer nicht geltenden Dienst-Art – `applies` sagt, ob die Art für die Person gilt), `missing()` 0 und `isBehind()` false, Einträge und Buchungen zählen trotzdem. Dienst-Arten vor ihrem Startjahr erscheinen in `standing()` nur mit Einträgen oder Buchungen im Jahr; wer ein Soll berechnet, nutzt `expected` statt `expectedPerYear`. Ein nachträglich als Dienst markiertes vergangenes Event bringt keine Einträge; das Ledger behält Einträge auch nach dem Austritt und nach einer Kontolöschung (ohne Personenbezug).
- **Bestätigung durch das Team (ab 1.9):** Eine Community kann verlangen, dass geleistete Dienste vom Team bestätigt werden – immer oder je Dienst-Art (`DutyInfo::$needsConfirmation`); wer am Termin eingecheckt wurde, ist sofort bestätigt. Für Plugins gilt eine Regel: **Nur bestätigte Dienste zählen.** `DutyStanding::$completed`, `completions()` und der Hook `duty.completed` kennen nur sie; Dienste, die noch warten, stehen in `DutyStanding::$pending` (sie halten wie geplante aus dem Rückstand: `isBehind()` = erledigt plus wartend plus geplant unter dem Soll; `missing()` zählt sie nicht) und in `pendingCount()`. Abgelehnte Dienste sieht kein Plugin. Bestätigen und Ablehnen bleibt Sache des Kerns. Wer über ein Jahr abrechnet (etwa einen Ausgleich für fehlende Dienste), wartet, bis `pendingCount($communityId, $year)` 0 ist – sonst würde ein Dienst als fehlend berechnet, über den das Team noch nicht entschieden hat. Ein Plugin mit `"pluginApi": "^1.6"` läuft unverändert weiter und sieht wartende Dienste schlicht noch nicht als erledigt.
- **Hooks:** `duty.booked`, `duty.released`, `duty.completed`, siehe [Hooks](/plugins/hooks#katalog).

## Speicher

`storage()->forCommunity($communityId)` bzw. `storage()->global()` liefern einen Bereich im Upload-Speicher der Plattform (lokal oder S3), getrennt je Plugin und Community.

| Methode | Zweck |
| --- | --- |
| `put($path, string\|resource $content)`, `read($path)` (bis 20 MB), `stream($path)` | schreiben, lesen, als Stream lesen |
| `exists()`, `size()`, `delete()`, `deleteDirectory($prefix)` | verwalten |
| `putEncrypted($path, $plain, $documentId): EncryptedFile` | verschlüsselt ablegen (XChaCha20-Poly1305, eigener Schlüssel je Datei); `documentId` ist eine UUID. Den `keyBlob` aus dem Ergebnis neben dem Pfad in der eigenen Tabelle speichern |
| `streamEncrypted($path, $keyBlob, $documentId, \Closure $sink)`, `readEncrypted()` (bis 20 MB) | entschlüsselt lesen |
| `putZip($path, iterable $entries): int` | ab Plugin-API **1.8**: ZIP-Archiv schreiben (Plugins dürfen `ZipArchive` nicht nutzen). `$entries` liefert Paare `[Name im Archiv, string\|resource]`, etwa aus einem Generator; Rückgabe ist die Größe in Bytes |

Pfade bestehen aus höchstens 8 Segmenten (je `[A-Za-z0-9][A-Za-z0-9._-]`, bis 100 Zeichen) und 255 Zeichen. Namen im ZIP-Archiv folgen derselben Form, dürfen zusätzlich Leerzeichen und `( ) + ,` enthalten, müssen ohne Groß-/Kleinschreibung eindeutig sein und dürfen nicht zugleich Datei und Ordner sein; höchstens 50 000 Einträge und 2 GiB unkomprimiert, sonst `InvalidArgumentException` – abgelegt wird dann nichts. Der Kern baut das Archiv in einer temporären Datei; Streams als Inhalt halten den Speicherbedarf klein. Dateien sind nie öffentlich erreichbar; ausgeliefert werden sie nur über eigene Endpunkte mit `Response::stream`. Verschlüsselte Dateien hängen an `APP_SECRET` – ändert der Betreiber es, sind sie verloren.

## Dateien und Dokumente

`files()->prepareDocument(UploadedFile $file, array $extensions = ['pdf', 'jpg', 'jpeg', 'png'], int $maxBytes = 10_485_760): PreparedFile` prüft Endung, Inhaltstyp und Signatur der Datei; Bilder werden neu kodiert (höchstens 4000 Pixel, ohne EXIF- und GPS-Angaben), PDF bleiben unverändert. `prepareImage(UploadedFile $file, int $maxPx = 2000)` liefert ein WebP-Bild. Beide werfen bei Problemen `ValidationFailed(['file' => …])`. `PreparedFile` hat `stream`, `mimeType`, `cleanName`, `extension` und `size` – passend für `storage()->…->putEncrypted()`.

## Verschlüsselung und Signaturen

| Methode | Zweck |
| --- | --- |
| `encryptSecret(string $plain, string $boundTo)`, `decryptSecret()` | Geheimnisse (z. B. Zugangsdaten) verschlüsselt in eigenen Tabellen ablegen; an `$boundTo` gebunden, Ergebnis base64 |
| `hmac(string $purpose, string $data)`, `hmacEquals()` | Prüfsummen, z. B. für signierte Links |
| `sign(string $purpose, string $message): Signature`, `verify()` | Ed25519-Signatur dieser Installation; `Signature` mit `keyId`, `value` (`v1.<keyId>.<base64>`) und `publicKey` |
| `publicKeys()`, `rotate()` | alle je ausgegebenen öffentlichen Schlüssel; neuer Schlüssel, alte bleiben prüfbar |

`purpose` folgt der Namensregel (bis 40 Zeichen). Eine Signatur belegt „diese Installation“, nicht die Person. Sie schützt vor späteren Änderungen durch Dritte ohne `APP_SECRET` und Datenbank; gegen den Betreiber selbst hilft nur ein externer Zeitstempel. Die signierte Nachricht sollte alle tragenden Angaben enthalten (Zweck, Community, Objekt, letzter Hash, Anzahl, Zeit, Person). Die öffentlichen Schlüssel zeigt der Plattform-Admin auf der Detailseite des Plugins.

## Zeitstempel

`timestamps()->isConfigured()` sagt, ob der Betreiber einen Zeitstempeldienst eingerichtet hat (siehe [Plugins betreiben → Zeitstempeldienst](/plugins/betrieb#zeitstempeldienst)). `stamp(string $sha256Hex): TimestampToken` lässt einen SHA-256-Hash (64 Hex-Zeichen) von der externen Stelle nach RFC 3161 bestätigen und prüft die Antwort vollständig; das Token (base64) gehört neben das Dokument. `verify(string $tokenBase64, string $sha256Hex): TimestampVerification` prüft später – zum Zeitpunkt des Stempels, also auch nach Ablauf des Zertifikats der Stelle. `stamp()` wirft `TimestampUnavailable` mit `reason()`: `not_configured`, `unreachable`, `rejected`, `invalid_response` oder `rate_limited` (höchstens 30 je Stunde und Community).

## PDF, Vorlagen, HTML

- `pdf()->render(string $template, array $vars = [], string $paper = 'A4', string $orientation = 'portrait'): string` rendert eine Vorlage aus `templates/pdf/` des Plugins (Name ohne `pdf/`, z. B. `'liste.html.twig'`) zu PDF-Bytes. Papier `A3`, `A4`, `A5`, `A6`, `letter`, `legal`. Bilder und Schriften nur als `data:`-URI oder aus `templates/pdf/`; Seitenzahlen per CSS `counter(page)`, z. B. in einer festen Fußzeile (eine Gesamtzahl „von N“ über `counter(pages)` unterstützt die PDF-Erzeugung nicht – sie ergäbe 0). Synchron nur für kleinere Dokumente (Richtwert bis 50 Seiten), größere in einer [Aufgabe](/plugins/erweiterungspunkte#aufgaben); höchstens 30 PDF je 10 Minuten und Person. `pdf()->qrDataUri($text)` liefert einen QR-Code als SVG-`data:`-URI.
- `views()->render('email/…' oder 'pdf/…', $vars)` rendert eine Vorlage zu HTML. Vorlagen kommen immer aus dem Plugin, nie aus Datenbank oder Einstellungen.
- `html()->sanitize($html)` säubert Rich-Text wie die Plattform (das Ergebnis darf ins Frontend-Element `RichTextBody`), `html()->toText($html)` macht reinen Text daraus.

## CSV und Excel

| Methode | Zweck |
| --- | --- |
| `csv()->read(UploadedFile\|resource $source, ?string $delimiter = null, int $maxRows = 10_000)` | Zeilen als Arrays mit der Kopfzeile als Schlüssel; BOM entfernt, Trennzeichen (`;`, `,`, Tab, `\|`) erkannt, ungültiges UTF-8 als Windows-1252 gelesen. Prüft die ganze Datei vorab (höchstens 500 Spalten, 1 MiB je Zeile, 20 MB, `maxRows` bis 100 000) und wirft sonst `ValidationFailed(['file' => …])` |
| `csv()->write(array $header, iterable $rows)` | CSV-Bytes wie `Response::csv` – für Aufgaben, die das Ergebnis ablegen |
| `csv()->xlsx(array $sheets)` | Excel-Bytes wie `Response::xlsx` |
| `csv()->readXlsx(UploadedFile\|resource $source, int $maxRows = 10_000)` | Ab Plugin-API **1.3**: das erste Blatt einer Excel-Datei (XLSX) lesen – Ergebnis wie `read()` (erste nicht leere Zeile = Kopfzeile, Spalten ohne Überschrift ausgelassen, leere Zeilen übersprungen). Datumszellen als `Y-m-d` (mit Uhrzeit `Y-m-d H:i:s`), ganze Zahlen ohne Nachkommastellen, Wahrheitswerte `1`/`0`, Formeln mit ihrem gespeicherten Ergebnis. Datei bis 20 MB, höchstens 500 Spalten und `maxRows` Zeilen, vorab geprüft – sonst `ValidationFailed(['file' => …])`. Plugins dürfen `ZipArchive` nicht nutzen, deshalb liest der Kern |
| `csv()->cell(string $value)` | Textzelle gegen Formel-Einschleusung schützen |

## Bestätigung heikler Aktionen

Vor heiklen Schritten (z. B. einem verbindlichen Tagesabschluss) bestätigt die angemeldete Person ihre Identität: `security()->confirmationMethod($request)` sagt, was nötig ist (`password`, `password_totp` bei aktiver Zwei-Faktor-Anmeldung, `fresh_login` bei Konten ohne Passwort), `security()->confirm($request, $password, $totpCode)` prüft und wirft sonst `Conflict` mit der Meldung des Kerns, `hasRecentLogin($request)` prüft eine Anmeldung in den letzten 10 Minuten. Nur in HTTP-Handlern; Fehlversuche werden protokolliert. Bestätigungen für fremde Konten gibt es nicht.

## Protokoll

`audit()->log(?string $communityId, string $action, ?string $targetType = null, ?string $targetId = null, array $payload = [])` schreibt `plugin.<id>.<action>` ins Protokoll der Community (bzw. der Plattform bei `null`). Die Aktion folgt der Namensregel; der ganze Name hat höchstens 64 Zeichen. `targetType` bis 32 Zeichen, `targetId` eine UUID. Die handelnde Person setzt der Kern (im Request die angemeldete Person, in Aufgaben deren Auslöser), dazu die Herkunft (Plugin und Version). Payload höchstens 8 KB, nur einfache Werte und Listen davon – keine Inhalte und keine Geheimnisse.

## Übersetzung, Adressen, Limits, Cache

- `translator()->trans($key, $params = [], ?string $locale = null)` übersetzt mit dem Katalog des Plugins, dann dem der Plattform, sonst bleibt der deutsche Text; `locale()` ist die aktuelle Sprache.
- `urls()`: `absolute($path)` (mit `APP_URL`), `pagePath($slug, $path)`, `globalPagePath($path)`, `apiPath($slug, $path)`, `eventPath($slug, $eventId, $start = null)`, `memberProfilePath()`, `conversationPath()`, `newMessagePath($slug, $userId)`, `accountPath($anchor)` (z. B. `personal`, `phone`, `birthday`) und `localPath($target)` (nur lokale Rücksprungziele).
- `limiter('offers', 10, '1 hour')->consume($key)` wirft `TooManyRequests` mit `retryAfter`, `tryConsume()` liefert `bool`. Grenze und Intervall gelten je Name fest.
- `cache($communityId)->get|set|delete|remember($key, $ttlSeconds, …)`: Schlüssel bis 100 Zeichen (`A–Z`, `a–z`, `0–9`, `_`, `.`, `-`), Lebensdauer 1 Sekunde bis 30 Tage, getrennt je Plugin und Community.

## Modelle

| Modell | Felder |
| --- | --- |
| `CommunityInfo` | `id`, `slug`, `name`, `defaultCountry`, `suspended`, `birthdayMode` (`off`/`optional`/`required`), `personalName`, `personalAddress` (`off`/`postal_code`/`optional`/`required`), `groupChats` (`everyone`/`staff`/`off`), `personalPhone` (`off`/`optional`/`required`, ab 1.4) |
| `Viewer` | `userId`, `membershipId`, `communityId`, `role`, `canRead`, `canWrite`, `isTeam`, `isManager`, `isOwner`, `isPlatformAdmin`, `customRoleIds` (nur für Prüfungen, nie ausgeben), `locale`, `timezone`; `isMember()` = lesendes Mitglied, `hasMembership()` = irgendeine Mitgliedschaft, `hasCustomRole()` |
| `MemberInfo` | siehe [Mitglieder](#mitglieder) |
| `CorrectionScope`, `PersonalDataCorrection`, `AddressInput`, `LoginEmail` | Korrektur persönlicher Angaben und Anmelde-E-Mail (ab 1.4), siehe [Mitglieder](#mitglieder) |
| `AccountSnapshot` | Momentaufnahme der Personendaten eines gelöschten Kontos (ab 1.5), siehe [Mitglieder](#mitglieder) |
| `EventInfo` | `id`, `communityId`, `title`, `startsAt`, `endsAt`, `timezone`, `location`, `postalCode`, `country`, `path`, `recurrence` (`none`/`weekly`/`monthly`/`monthly_weekday`), `recurrenceWeeks`, `recurrenceUntil` (`Y-m-d`), `recurrenceEnd` (UTC), `createdByUserId`, `tags`, `capacity`, `minLevel`, `planIds`, `ageGroupIds`, `courseOnly`, `draft` (Vorschau, ab 1.3: im Kalender sichtbar, noch keine Zusagen); `isSeries()` |
| `EventDraft` | Werte eines Events im Editor (`ExtensionInput`): `title`, Zeitplan wie `EventInfo`, `capacity`, `tags`, `ageGroupIds`, `planIds`, `draft` (Vorschau nach der Änderung, ab 1.3); `scheduleDiffers()` |
| `Occurrence` | `eventId`, `start`, `end`, `key()`, `startString()`; `Occurrence::keyFor()`, `parseKey()` |
| `DutyInfo` | Dienst-Art (ab 1.6): `id`, `communityId`, `name`, `expectedPerYear` (0 = keine Vorgabe), `planIds`, `position`; ab 1.7 `startYear` (das Soll gilt ab diesem Kalenderjahr) |
| `DutyStanding` | Stand zu einer Dienst-Art im Jahr (ab 1.6): `membershipId`, `year`, `dutyId` (`null` = gelöscht), `dutyName`, `expected` (`null` = gilt nicht oder Jahr vor dem Startjahr), `completed`, `planned`, `applies`; `missing()`, `isBehind()` |
| `DutySlotInfo` | Dienst-Slot eines Termins (ab 1.6): `id`, `eventId`, `occurrenceStart`, `dutyId`, `dutyName`, `label`, `capacity`, `taken`, `position`; `displayLabel()`, `isFull()` |
| `DutyCompletion` | geleisteter Dienst (ab 1.6): `id`, `communityId`, `membershipId`, `dutyId`/`eventId` (`null` = gelöscht), `dutyName`, `eventTitle`, `occurrenceStart`, `completedOn` (`Y-m-d`), `year`, `source` (`event`/`slot`), `slotLabel` |
| `GeoPoint`, `Location`, `GeoStatus` | Koordinate mit Ort; Wohnort eines Betrachters; ob Entfernungen möglich sind |
| `PersonalDataView`, `PersonName` | Name und Anschrift im sichtbaren Umfang (`firstNameOnly`: nur der Vorname ist sichtbar, seit 1.2); Name als Momentaufnahme |
| `AgeCheck` | `status`, `passes()` |
| `InviteInfo`, `Branding`, `Notice`, `Sheet`, `DemoSeed` | Einladungslink; Logo und Anschrift; Hinweis; Excel-Blatt; Auftrag für Beispieldaten |
| `Signature`, `TimestampToken`, `TimestampVerification`, `EncryptedFile`, `PreparedFile` | Ergebnisse von Krypto-, Zeitstempel-, Speicher- und Datei-Diensten |
| `ClaimInput`, `Claim`, `ClaimStatus`, `ClaimQuery`, `ClaimPage`, `ClaimRef`, `SubmitResult` | Forderung melden, lesen, abgleichen; Zustände `open`, `collecting`, `paid`, `returned`, `settled`, `cancelled` |
| `DebitSetup`, `DebitMethod`, `MandateInfo`, `MandateStatus`, `PaymentStanding`, `SettlementMethod` | Einstellungen, Mandatsstand und Zahlungsstand ohne Bankdaten |
