---
title: "Erweiterungspunkte"
description: "Seiten, Menüpunkte, Zusatzfelder an Events, Mitgliedern, Beiträgen, Kursen und Lektionen, Erweiterungen von Kern-Antworten, Filter-Hooks, Einstellungen, Zustand, Jobs, Aufgaben, Hinweise, Session-Daten und Lebenszyklus"
---

Alle Erweiterungspunkte registriert die Einstiegsklasse in `register()` (siehe [PHP-Schnittstelle](/plugins/php-api#registry)). Die Klassen liegen im Namensraum `App\Plugin\Api`.

## Seiten

```php
$registry->page('', 'Fahrgemeinschaften');                                  // /c/<slug>/plugins/<id>
$registry->page('/admin', 'Fahrgemeinschaften verwalten', Access::Manage);    // /c/<slug>/plugins/<id>/admin
$registry->page('/mine', 'Meine Fahrten', Access::User, community: false);    // /plugins/<id>/mine
```

- 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](/plugins/frontend#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](/plugins/php-api#endpunkte), 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

```php
new NavItem(area: NavArea::Community, label: 'Fahrgemeinschaften', path: '', icon: 'car', order: 50);
new NavItem(area: NavArea::User, label: 'Meine Fahrten', path: '/mine');
new NavItem(area: NavArea::Admin, label: 'Fahrgemeinschaften (alle)', path: '/overview');
```

| Bereich | Wo | Ziel | Erlaubter Zugriff (Standard fett) |
| --- | --- | --- | --- |
| `NavArea::Community` | Hauptleiste der Community | `/c/<slug>/plugins/<id><path>` | **`Member`**, `Writer`, `Team`, `Manage`, `Owner`, `PlatformAdmin` |
| `NavArea::User` | Benutzermenü | `/plugins/<id><path>` | **`User`**, `PlatformAdmin` |
| `NavArea::Admin` | Admin-Menü und Seitenleiste von `/admin` | `/plugins/<id><path>` | **`PlatformAdmin`** |

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

```php
$registry->extraField(
    ExtraField::text('member_number', 'Mitgliedsnummer')
        ->on(Target::Member)
        ->maxLength(20)
        ->visibleTo(Visibility::Team)
        ->editableBy(Editor::Manage)
);
$registry->extraField(
    ExtraField::select('difficulty', 'Schwierigkeit')->on(Target::Event)->options(['leicht', 'mittel', 'schwer'])->required()
);
```

| Typ | Prüfung im Kern |
| --- | --- |
| `text`, `textarea` | reiner Text, `maxLength` (Standard 500 bzw. 5000, höchstens 1000 bzw. 10 000) |
| `number` | Ganz- oder Kommazahl, `min`/`max` |
| `boolean` | ja/nein |
| `date` | `Y-m-d` |
| `select` | nur Werte aus `options()` (1–100 Einträge, zugleich Übersetzungsschlüssel der Anzeige) |
| `url` | nur `http(s)://` mit Host, höchstens 2000 Zeichen |
| `email` | gültige E-Mail-Adresse |
| `phone` | Telefonnummer, gespeichert im internationalen Format (E.164) |

| Methode | Wirkung |
| --- | --- |
| `on(Target::…)` | **Pflicht** – Ziel des Felds: `Event`, `Member`, ab 1.2 `Post`, `Course`, `Lesson` |
| `help(string)` | Hilfetext (Übersetzungsschlüssel, höchstens 500 Zeichen) |
| `required()` | Pflichtfeld |
| `visibleTo(Visibility::…)` | wer den Wert sieht: `Members` (Standard, alle lesenden Mitglieder), `Self` (nur Mitgliedsfelder: die Person selbst und das Team), `Team` (Moderator aufwärts), `Manage` (Admin aufwärts) |
| `editableBy(Editor::…)` | wer ihn ändert: `EventCreator` (Standard bei Events: die anlegende Person und das Team), `Self` (Standard bei Mitgliedern: die Person selbst, mit schreibender Mitgliedschaft), `Author` (Standard bei Beiträgen: wer den Beitrag anlegt bzw. bearbeiten darf), `Team`, `Manage` (jeweils nach Rang über der Person; Plattform-Admins immer). Bei Kursen und Lektionen gibt es nur `Manage` (die Kursverwaltung) |

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

```php
final class CarpoolEvents implements ResponseExtension
{
    public function __construct(private readonly PluginContext $ctx)
    {
    }

    public function load(ExtensionQuery $query): array
    {
        $result = [];
        foreach ($query->occurrences() as $occurrence) {
            $result[$occurrence->key()] = ['offers' => $this->countOffers($query->community()->id, $occurrence)];
        }

        return $result;
    }
}

$registry->extension(Target::Event, new CarpoolEvents($this->ctx));
```

| Ziel | Schlüssel im Ergebnis | `context()` | In den Antworten von |
| --- | --- | --- | --- |
| `Target::Event` | Vorkommens-Schlüssel `Occurrence::key()` (`<eventId>\|<Y-m-d\TH:i:s\Z>`); ersatzweise die Event-ID für alle Vorkommen | `list`, `detail` | Event-Liste und Event-Ansicht (`EventOccurrenceResponse.extra`) |
| `Target::Member` | Membership-ID | `directory`, `profile`, `requests` | Mitgliederverzeichnis, Profil, Beitrittsanfragen (`MemberResponse.extra`) |
| `Target::LeaderboardEntry` | Membership-ID | `list` | Leaderboard (`LeaderboardEntryResponse.extra`) |
| `Target::Post` *(ab 1.2)* | Post-ID | `list`, `detail` | Feed, Angepinnt, Entwürfe, Beitragsansicht und Antworten auf Anlegen/Ändern (`PostResponse.extra`) |
| `Target::Course` *(ab 1.2)* | Kurs-ID | `list`, `detail` | Kursliste und Kursseite (`CourseResponse.extra`) – nur freigeschaltete Kurse |
| `Target::Lesson` *(ab 1.2)* | Lektions-ID | `detail` | Lektion (`LessonResponse.extra`) |

- 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](/plugins/frontend#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:

```php
final class DonationPosts implements InputExtension
{
    public function load(ExtensionQuery $query): array { /* … je Post-ID … */ }

    public function validate(TargetInput $input): array
    {
        $goal = $input->data()['goalCents'] ?? null;

        return $goal !== null && (!\is_int($goal) || $goal < 100) ? ['goalCents' => 'Mindestens 1 €.'] : [];
    }

    public function store(TargetInput $input, string $targetId): void { /* eigene Tabelle */ }
}

$registry->extension(Target::Post, new DonationPosts($this->ctx));
```

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

| Filter | Registrierung | Budget | bei Fehler |
| --- | --- | --- | --- |
| `leaderboard.ranking` | `leaderboardRanking(fn (RankingQuery $q): ?RankingChange)` | 200 ms | Änderungen dieses Plugins entfallen |
| `sequence.placeholders` | `placeholders(list<Placeholder>, fn (PlaceholderQuery $q): array)` | 500 ms | Platzhalter dieses Plugins bleiben leer |
| `landing_page.blocks` | `pageBlock(PageBlock)` | 200 ms | Baustein entfällt, die Seite bleibt `200` |
| `form.field_types` | `formField(FormFieldKind)` | 200 ms | Vorlage: Textfeld des Kerns; Prüfung: Feldfehler „Diese Angabe lässt sich gerade nicht prüfen.“ |

### Rangliste

```php
$registry->leaderboardRanking(function (RankingQuery $query): ?RankingChange {
    $bonus = $this->bonusPoints($query->community->id, $query->membershipIds());   // eigene Tabelle

    return new RankingChange(points: $bonus, exclude: $this->hiddenMemberships($query->community->id));
});
```

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

```php
$registry->placeholders([
    Placeholder::define('items', 'Was du mitbringst')->help('Nur in Serien mit Auslöser „Event-Zusage“.')->example('2 × Nudelsalat'),
], function (PlaceholderQuery $query): array {
    $values = [];
    foreach ($query->recipients as $recipient) {
        $values[$recipient->membershipId]['items'] = $this->itemsOf($recipient);   // reiner Text
    }

    return $values;
});
```

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

```php
$registry->pageBlock(
    PageBlock::define('countdown', 'Countdown')
        ->help('Zählt die Tage bis zu einem Datum.')
        ->template('blocks/countdown.html.twig')
        ->fields(ExtraField::text('heading', 'Überschrift')->required()->maxLength(80), ExtraField::date('until', 'Bis')->required())
        ->prepare(fn (BlockContext $c): array => ['days' => $this->daysUntil($c->data['until'])]),
);
```

- 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

```php
$registry->formField(
    FormFieldKind::define('diet', 'Ernährung')
        ->template('forms/diet.html.twig')
        ->validate(fn (FormFieldInput $in): FieldResult => \in_array($in->value, self::DIETS, true)
            ? FieldResult::ok($in->value)
            : FieldResult::error('Bitte wähle eine der vorgegebenen Angaben.')),
);
```

- 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](/plugins/grenzen#regeln)). 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](/plugins/frontend#geltungsbereich-plugin-stile-wirken-nur-im-plugin)).

## Einstellungen

```php
$registry->setting(SettingField::number('maxSeats', 'Höchstplätze')->min(1)->max(8)->default(4));
$registry->setting(SettingField::textarea('disclaimer', 'Haftungshinweis')->maxLength(2000)->exposeToMembers());
$registry->setting(SettingField::secret('apiKey', 'API-Schlüssel des Dienstes')->scope(Scope::Platform));
$registry->settingsValidator(fn (array $values, Scope $scope, ?CommunityInfo $community): array =>
    ($values['maxSeats'] ?? 0) > 6 && ($values['disclaimer'] ?? '') === '' ? ['disclaimer' => 'Ab 7 Plätzen ist ein Hinweis Pflicht.'] : []);
```

| Typ | Wert |
| --- | --- |
| `text`, `textarea`, `email` | Text (Standardlänge 500, 5000 bzw. 254) |
| `number` | Ganzzahl mit `min`/`max` |
| `boolean` | ja/nein (ohne Standard `false`) |
| `select`, `multiselect` | ein Wert bzw. eine Liste aus `options()` |
| `time` | Uhrzeit `HH:MM` |
| `secret` | nur schreibbar, verschlüsselt gespeichert; nach außen nur `{hasValue}` |
| `customRoles`, `plans` | Listen von IDs eigener Rollen bzw. Pläne der Community (nur Community-Einstellungen); gelöschte IDs fallen beim Lesen heraus |

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

```php
$registry->job('reminders', Schedule::everyMinutes(15), $this->sendReminders(...));
$registry->job('cleanup', Schedule::dailyAt('03:30'), $this->cleanup(...));
```

- `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](/plugins/datenbank#verweise-auf-den-kern)) und hält die Löschfristen ein, die der [Absatz für die Datenschutzerklärung](/plugins/datenschutz#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.

```php
public function cleanup(JobContext $job): void
{
    $db = $this->ctx->db();
    $failure = null;
    foreach ($db->fetchAll('SELECT DISTINCT community_id FROM '.$db->table('offers')) as $row) {
        if ($job->shouldStop()) {
            return;                             // beim nächsten Takt weitermachen
        }
        try {
            $this->reconcile($job, (string) $row['community_id']);
        } catch (\Throwable $e) {
            $failure ??= $e;                    // eine Community blockiert die anderen nicht
        }
    }
    if ($failure !== null) {
        throw $failure;                         // Kern vermerkt den Fehler, nächster Takt versucht es erneut
    }
}
```

Je Community prüft `reconcile()` mit den [Kern-Diensten](/plugins/kern-dienste):

- `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](/plugins/beispiel-plugin).

## Aufgaben

Für Arbeit, die nicht in einen Request passt (große Exporte, PDF mit vielen Seiten, Massenaktionen):

```php
$registry->task('export', function (TaskContext $task, array $payload): void {
    $csv = $this->ctx->csv()->write(['Name', 'Plätze'], $this->rows((string) $task->communityId));
    $this->ctx->storage()->forCommunity((string) $task->communityId)->put('exports/'.$task->taskId.'.csv', $csv);
    // … Glocke an $task->actorUserId mit Link auf einen eigenen Download-Endpunkt
});

// in einem POST-Handler:
$taskId = $this->ctx->tasks()->dispatch('export', ['from' => '2026-01-01'], $community->id);
```

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

```php
$registry->notice(fn (Viewer $viewer, CommunityInfo $community): ?Notice =>
    $this->missingFields($community->id, $viewer) > 0
        ? new Notice('Bitte ergänze {count} Angaben für die Fahrgemeinschaften.', 'Jetzt ergänzen', $this->ctx->urls()->pagePath($community->slug, '/profile'), Notice::WARNING, ['count' => 2])
        : null);

$registry->sessionData(fn (Viewer $viewer, CommunityInfo $community): array =>
    ['canDrive' => $this->canDrive($community->id, $viewer)]);
```

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

| Methode | Wann |
| --- | --- |
| `onEnable()` | plattformweit aktiviert – nach den Migrationen |
| `onDisable()` | plattformweit deaktiviert |
| `onCommunityEnabled(CommunityInfo $community)` | in einer Community eingeschaltet |
| `onCommunityDisabled(CommunityInfo $community)` | in einer Community ausgeschaltet, z. B. um offene Angebote abzusagen |

Eine Ausnahme landet im Log; die Umschaltung gilt trotzdem. Steht eine Migration aus, entfällt der Aufruf (mit Warnung) und wird nicht nachgeholt.
