---
title: "Beispiel-Plugin"
description: "Das Beispiel-Plugin „Mitbringliste“ (example-plugin) herunterladen, ausprobieren und als Vorlage für eigene Plugins verwenden"
---

Das **Beispiel-Plugin „Mitbringliste“** ist ein kleines, kommentiertes Plugin zum Ausprobieren und Kopieren: Mitglieder tragen zu jedem Termin im Kalender ein, was sie mitbringen – Kuchen, Getränke, Salat. Wer den Termin verwaltet, lädt die Liste als CSV oder PDF und erinnert Zusagende, die noch nichts eingetragen haben. Die wichtigsten Erweiterungspunkte kommen dabei je einmal vor.

**[quicktribe-example-plugin.zip herunterladen](/downloads/quicktribe-example-plugin.zip)** (Plugin-ID `example-plugin`, Namespace `QuickTribePlugin\ExamplePlugin`) – mit Quellen, Tests, Übersetzungen und der gebauten Oberfläche (`dist/`).

Dasselbe Plugin liegt dem Auslieferungspaket unter `plugins/example-plugin/` bei – inaktiv und sofort aktivierbar (Variante Docker Compose, siehe [Plugins installieren](/plugins/installieren#docker-compose-auslieferungspaket)). Wer es nicht braucht, löscht den Ordner.

## Was es tut

- **Menüpunkt „Mitbringen“** in der Community: führt auf die Seite „Mitbringliste“ mit den eigenen Einträgen für kommende Termine, einer Einleitung des Teams und dem Hinweis, wie viele Sachen je Termin erlaubt sind.
- **Termin-Ansicht im Kalender:** Neben den Angaben zum Termin steht seine Mitbringliste. Mitglieder tragen ein, was sie mitbringen (mit Menge), und entfernen eigene Einträge; wer zugesagt hat, sieht zusätzlich einen Zugangscode des Teams (etwa für Tür oder WLAN). Wer den Termin verwaltet, lädt die Liste als **CSV** oder **PDF** und erinnert mit **Ohne Eintrag erinnern** alle Zusagenden ohne Eintrag. Nach dem Ende des Termins ist die Liste geschlossen.
- **Kalenderliste:** Jede Karte zeigt, wie viele Einträge die Liste des Termins hat.
- **Abgesagte Termine:** Sagt das Team einen Termin ab (oder wird er abgesagt, weil die Mindestteilnehmerzahl nicht erreicht ist), ruht seine Mitbringliste: Die Einträge bleiben stehen, Neues und „Ohne Eintrag erinnern“ gibt es so lange nicht, im Termin steht ein Hinweis. Findet der Termin doch statt, gilt alles wieder.
- **Benachrichtigungen:** Nach einer Zusage kommt die Glocke „Was bringst du mit?“; über jeder Seite der Community erinnert ein Hinweis an eigene Einträge für die nächsten zwei Tage.
- **Zusatzangaben:** Im Event-Editor gibt es ein Feld „Hinweis zur Mitbringliste“, im Profil die freiwillige Angabe „Ernährung“, die nur die Person selbst und das Team sehen.
- **Datenschutz:** Einträge werden 30 Tage nach dem Ende des Termins gelöscht; der Datenexport enthält sie, eine Kontolöschung entfernt sie.
- **Kursseite:** Hat ein Kurs Live-Termine, zeigt seine Seite zu jedem die Zahl der Einträge auf der Mitbringliste.
- **E-Mail-Serien:** Der Platzhalter `{example-plugin.items}` nennt in Serien mit Auslöser „Event-Zusage“, was die Person zum Termin eingetragen hat.
- **Formulare:** Der Feldtyp „Ernährung“ fragt in Anmeldeformularen vegetarisch, vegan oder ohne Einschränkung ab.

## Was es zeigt

| Erweiterungspunkt | Im Beispiel | Siehe |
| --- | --- | --- |
| Menüpunkt und eigene Seite | `navItem` „Mitbringen“ (Symbol `clipboard-list`), `page('')`, Vue-Seite `frontend/BringListPage.vue` | [Seiten](/plugins/erweiterungspunkte#seiten), [Menüpunkte](/plugins/erweiterungspunkte#menüpunkte), [Frontend-SDK → Seiten](/plugins/frontend#seiten) |
| Deklarative Zusatzfelder | `bring_hint` am Event (Text), `diet` am Mitglied (Auswahl, `visibleTo(Visibility::Self)`) – ganz ohne eigenen Code | [Zusatzfelder](/plugins/erweiterungspunkte#zusatzfelder) |
| Erweiterung der Event-Antworten | `ItemExtension`: Zahl der Einträge je Termin unter dem Vorkommens-Schlüssel, ein `load()` je Liste | [Erweiterungen von Kern-Antworten](/plugins/erweiterungspunkte#erweiterungen-von-kern-antworten) |
| Slots | `calendar.event.detail.aside` (`BringListAside.vue`), `calendar.list.card.footer` (`CardFooter.vue`, liest nur `event.extra`), `settings.plugin.example-plugin` (`SettingsInfo.vue`, Zahlen unter dem Formular) | [Slots](/plugins/frontend#slots) |
| Hooks | `event.rsvp` → Glocke mit `collapse`; `event.updated` → Einträge eines verschobenen Einzeltermins umziehen, entfallene Termine einer Serie löschen; Aufräum-Hook `event.deleted` | [Hook-Katalog](/plugins/hooks) |
| Abgesagte Termine *(ab 1.9)* | `event.cancelled` → eigene offene Glocken zurückziehen (`forget()`), nichts löschen; `event.reinstated` → nichts zu reparieren; der Zustand kommt bei jedem Zugriff aus `events()->isCancelled()` bzw. `cancelledKeys()` (`409` beim Eintragen und Erinnern, Hinweis im Slot) | [Hook-Katalog](/plugins/hooks), [Kern-Dienste](/plugins/kern-dienste) |
| Job | `cleanup` täglich um 03:30: Abgleich über alle Communities mit Einträgen, Frist ab dem Ende des Termins | [Abgleich und Löschfristen](/plugins/erweiterungspunkte#abgleich-und-löschfristen) |
| Aufgabe | `remind` im Worker: Glocke und E-Mail an Zusagende ohne Eintrag, die den Termin sehen und eintragen dürfen; Bestätigung an die auslösende Person, Protokoll | [Aufgaben](/plugins/erweiterungspunkte#aufgaben), [Benachrichtigungen](/plugins/kern-dienste#benachrichtigungen) |
| Einstellungen | plattformweit „Einträge je Person und Termin“ (`maxItems`) und „Fußzeile im PDF“; je Community ein Schalter, eine Einleitung (`exposeToMembers()` → `sdk.settings`) und ein geheimer Zugangscode (`secret`) | [Einstellungen](/plugins/erweiterungspunkte#einstellungen) |
| Hinweis und Session-Daten | Hinweis auf eigene Einträge der nächsten 48 Stunden; `sessionData` mit `maxItems` → `sdk.data` | [Hinweise und Session-Daten](/plugins/erweiterungspunkte#hinweise-und-session-daten) |
| Eigene JSON-API | acht Endpunkte mit `Access::Writer` bzw. `Access::Manage`, `ApiOptions` mit `maxJsonBytes` und `RateLimit`; fremde und gesperrte Events → `404` | [Endpunkte](/plugins/php-api#endpunkte), [Fehler](/plugins/php-api#fehler) |
| CSV und PDF | `Response::csv()`; `pdf()->render()` mit `templates/pdf/items.html.twig` (Texte über `ptrans`, Seitenzahlen über `counter(page)`) | [Response](/plugins/php-api#response), [PDF, Vorlagen, HTML](/plugins/kern-dienste#pdf-vorlagen-html) |
| Eigene Tabelle | `migrations/0001_items.sql` → `plg_example_plugin__items`, Zugriff über `db()` in `src/Items.php` | [Datenbank und Migrationen](/plugins/datenbank) |
| Datenschutz und Beispieldaten | `PrivacyAware` (Export samt CSV-Datei im ZIP, Konto- und Community-Löschung), Absatz für die Datenschutzerklärung, `DemoAware` für `app:demo:seed` | [Datenschutz und Beispieldaten](/plugins/datenschutz) |
| Slot der Kursseite *(ab 1.2)* | `classroom.course.detail` (`CourseLiveBring.vue`): Zahl der Einträge zu den Live-Terminen über die eigene API | [Slots](/plugins/frontend#slots) |
| Platzhalter *(ab 1.2)* | `{example-plugin.items}` über `placeholders()` – ein Aufruf für alle Empfänger eines Schritts, eine Abfrage je Termin | [Platzhalter in E-Mail-Serien](/plugins/erweiterungspunkte#platzhalter-in-e-mail-serien) |
| Formular-Feldtyp *(ab 1.2)* | `formField(FormFieldKind::define('diet', …))` mit `templates/forms/diet.html.twig` und Prüfung in `validateDiet()` | [Feldtypen für Formulare](/plugins/erweiterungspunkte#feldtypen-für-formulare) |
| Tests | PHPUnit mit `PluginTestCase` (sieben Testklassen, Filter-Hooks über `sequencePlaceholders()`), Playwright-Szenarien `tests/e2e/bring-list.spec.ts`, `tests/e2e/areas.spec.ts` und `tests/e2e/cancelled.spec.ts` | [Prüfen, testen, übersetzen](/plugins/testen) |

**Nicht im Beispiel** – beschrieben in den übrigen Kapiteln:

- Eingaben im Event-Editor (`EventInputExtension`, Slot `calendar.event.editor.fields`), siehe [Erweiterungen von Kern-Antworten](/plugins/erweiterungspunkte#erweiterungen-von-kern-antworten);
- E-Mails mit eigener Vorlage (`mailer()`, `templates/email/`), siehe [E-Mails](/plugins/kern-dienste#e-mails);
- Dateien: `storage()`, Uploads, `Response::stream` und XLSX, siehe [Speicher](/plugins/kern-dienste#speicher) und [Response](/plugins/php-api#response);
- `Lifecycle` und die Prüfung von Einstellungen über Felder hinweg (`settingsValidator`), siehe [Lebenszyklus](/plugins/erweiterungspunkte#lebenszyklus) und [Einstellungen](/plugins/erweiterungspunkte#einstellungen);
- Menüpunkte im Benutzermenü und im Plattform-Admin sowie Seiten und Endpunkte ohne Community, siehe [Menüpunkte](/plugins/erweiterungspunkte#menüpunkte);
- Erweiterungen und Slots für Mitglieder, Leaderboard, Beiträge und Lektionen, siehe [Slots](/plugins/frontend#slots);
- Eingaben an Beitrag, Kurs und Lektion (`InputExtension`), der Filter der Rangliste und Landingpage-Bausteine, siehe [Filter-Hooks](/plugins/erweiterungspunkte#filter-hooks);
- `state()`, `cache()` und `limiter()`, siehe [Einstellungen](/plugins/erweiterungspunkte#einstellungen) und [Übersetzung, Adressen, Limits, Cache](/plugins/kern-dienste#übersetzung-adressen-limits-cache).

## Dateien

```text
plugins/example-plugin/
  plugin.json                    Manifest: perCommunity, privacy.personalData, assets (dist/plugin.js, dist/plugin.css)
  README.md                      Überblick, Befehle, „Als Vorlage für ein eigenes Plugin“
  migrations/0001_items.sql      eigene Tabelle plg_example_plugin__items (IDs als CHAR(36), community_id mit Index,
                                 keine Fremdschlüssel auf den Kern, IF NOT EXISTS)
  src/ExamplePlugin.php          Einstieg (Plugin, PrivacyAware, DemoAware): register() mit allen Registrierungen,
                                 Hooks, Job cleanup, Aufgabe remind, Hinweis, Export und Löschung, Beispieldaten
  src/Items.php                  Datenzugriff über db() – community_id in jeder Abfrage
  src/ItemsApi.php               Handler der eigenen JSON-API, CSV- und PDF-Export, Aufgabe auslösen
  src/ItemExtension.php          Ausgabe-Erweiterung für Events (Zähler je Termin)
  src/View/*.php                 readonly-Klassen der Antworten (JsonSerializable)
  templates/pdf/items.html.twig  PDF-Vorlage
  templates/forms/diet.html.twig Eingabefeld des Formular-Feldtyps „Ernährung“ (ab Plugin-API 1.2)
  translations/messages.en.json  Englisch für PHP, Twig und Oberfläche (Deutsch ist Quelltext und Schlüssel)
  frontend/index.ts              install(sdk): Übersetzungen, vier Slots, Route der Seite
  frontend/*.vue                 BringListPage (Seite), BringListAside, CardFooter, CourseLiveBring, SettingsInfo (Slots)
  frontend/api-types.ts          Typen der eigenen Endpunkte (Spiegel von src/View) und von sdk.data
  frontend/extra.ts              PLUGIN_ID und Zugriff auf extra["example-plugin"]
  frontend/plugin.css            Tailwind gegen das Theme der Plattform (wirkt nur im Plugin, data-plugin)
  dist/                          gebaute Oberfläche (npm run build:plugins example-plugin)
  tests/*Test.php                PHPUnit: ItemsApiTest, HooksJobsTasksTest, PrivacyAndDemoTest, PagesAndSettingsTest,
                                 AreasTest (Platzhalter, Formular-Feldtyp), ReviewDraftTest (Vorschau-Events),
                                 CancelledOccurrenceTest (abgesagte Termine, ab Plugin-API 1.9)
  tests/e2e/bring-list.spec.ts   Playwright: Menüpunkt, Seite, Kalender-Slots, Einstellungen
  tests/e2e/areas.spec.ts        Playwright: Slot der Kursseite, Formular-Feldtyp
  tests/e2e/cancelled.spec.ts    Playwright: Termin absagen, Hinweis in der Liste, Absage zurücknehmen
```

Auszug aus `src/ExamplePlugin.php` – alle Erweiterungspunkte stehen in `register()`, die Arbeit machen kleine Klassen:

```php
public function register(Registry $registry): void
{
    // Menüpunkt in der Hauptleiste der Community und die Seite dahinter: /c/<slug>/plugins/example-plugin
    $registry->navItem(new NavItem(NavArea::Community, 'Mitbringen', '', icon: 'clipboard-list', order: 60));
    $registry->page('', 'Mitbringliste');

    // Deklaratives Zusatzfeld: Angaben zur Ernährung sehen nur die Person selbst und das Team
    $registry->extraField(ExtraField::select(self::FIELD_DIET, 'Ernährung')->on(Target::Member)->options(self::DIETS)
        ->visibleTo(Visibility::Self)->help('Hilft beim Planen der Mitbringliste. Sehen nur du und das Team.'));

    $registry->extension(Target::Event, new ItemExtension($this->items));
    $registry->on(Hook::EventRsvp->value, $this->onRsvp(...));
    $registry->on(Hook::EventUpdated->value, $this->onEventUpdated(...));
    $registry->on(Hook::EventDeleted->value, $this->onEventDeleted(...));
    // ab Plugin-API 1.9: ein einzelner Termin wird abgesagt bzw. die Absage zurückgenommen
    $registry->on(Hook::EventCancelled->value, $this->onEventCancelled(...));
    $registry->on(Hook::EventReinstated->value, $this->onEventReinstated(...));
    $registry->job(self::JOB_CLEANUP, Schedule::dailyAt('03:30'), $this->cleanup(...));
    $registry->task(self::TASK_REMIND, $this->remind(...));

    $api = new ItemsApi($this->ctx, $this->items);
    $registry->api('POST', '/events/{eventId}/items', $api->add(...), Access::Writer,
        options: new ApiOptions(maxJsonBytes: 4096, rateLimit: RateLimit::perUser(60, '10 minutes')));
    // … Einstellungen, Hinweis, Session-Daten, Datenschutz-Absatz und die übrigen Endpunkte
}
```

## Muster zum Übernehmen

- **Sichtbarkeit in jedem Handler:** Vor jeder Antwort prüft der Handler, ob der Betrachter das Event sehen darf (`events()->viewable()`); fremde, gesperrte und unbekannte Events ergeben gleichermaßen `404`. CSV, PDF und Erinnerung gibt es nur für Personen, die den Termin verwalten (`events()->canManage()`).
- **Obergrenze auch bei gleichzeitigen Anfragen:** Zählen und Einfügen laufen in `db()->transactional()`, gezählt wird sperrend (`SELECT … FOR UPDATE`); bricht die Datenbank eine von zwei gleichzeitigen Transaktionen ab (`RetryableException`), versucht es der Handler erneut.
- **Oberfläche und Server einig:** Ob jemand eintragen, entfernen oder erinnern darf, liefert der Server mit (`canAdd`, `canRemove`, `canRemind`); die Oberfläche zeigt Knöpfe nur danach. Gegen Wettläufe verwerfen Seite und Slot veraltete Antworten über einen Zähler je Ladevorgang.
- **Vorschau-Events (ab Plugin-API 1.3):** An einer Vorschau (`draft`, aus `events()->occurrence()`) nimmt die Liste keine Einträge an (`409`, `canAdd`/`canRemind` falsch) – zusagen kann dort noch niemand. Die Hooks kommen trotzdem wie bei jedem Event, Einträge eines zurückgestellten Events ziehen mit und verschwinden mit `event.deleted`.
- **Abgesagte Termine (ab Plugin-API 1.9):** „Abgesagt“ ist ein Zustand des einzelnen Termins, den der Kern zurücknehmen kann – Zusagen bleiben bestehen. Das Plugin löscht deshalb nichts und speichert den Zustand nicht selbst: `ItemsApi` fragt bei jedem Zugriff `events()->isCancelled()` (Listen: einmal `cancelledKeys()`), lehnt Eintragen und Erinnern mit `409` ab und liefert `cancelled` für den Hinweis im Slot; Entfernen bleibt möglich. `event.cancelled` zieht nur die eigenen offenen Glocken zurück (`forget()`), `event.reinstated` hat nichts zu reparieren. Eigene Glocken zu Absage und Rücknahme verschickt das Plugin nicht – der Kern benachrichtigt alle Zusagenden und Wartenden schon per Glocke, Push und E-Mail:

  ```php
  // Schreibstelle: der Zustand kommt frisch aus dem Kern – canAdd aus der Liste kann veraltet sein
  if ($this->ctx->events()->isCancelled($communityId, $occurrence->eventId, $occurrence->start)) {
      throw new Conflict('Der Termin ist abgesagt – die Liste ruht, bis die Absage zurückgenommen wird.');
  }
  ```

- **Verschobene Termine:** Der Kern verschiebt keine Daten der Plugins. `event.updated` mit `scheduleChanged` zieht die Einträge eines Einzeltermins auf den neuen Beginn um und löscht bei Serien die Einträge entfallener Termine (`occurrenceExists()`).
- **Erinnerungen nur an Berechtigte, und so, dass sie ankommen:** Die Aufgabe prüft je Person einen Viewer (`members()->viewerFor()`, `canWrite`, `events()->lockReason()`) und ersetzt die ungelesene Glocke „Was bringst du mit?“ mit `forget()`, bevor sie ohne `collapse` erinnert:

  ```php
  $viewer = $this->ctx->members()->viewerFor($communityId, $member->userId);
  if ($viewer === null || !$viewer->canWrite || $this->ctx->events()->lockReason($communityId, $event->id, $viewer) !== null) {
      continue;   // sieht den Termin nicht mehr oder darf nicht schreiben
  }
  $this->ctx->notifications()->forget($communityId, $path, $member->userId);
  $this->ctx->notifications()->notify($communityId, $member->userId, 'Was bringst du zu „{title}“ mit?',
      'Trag auf der Mitbringliste ein, was du mitbringst.', $path, ['title' => $event->title],
      email: true, actorUserId: $task->actorUserId);
  ```

- **Einzahl und Mehrzahl als eigene Texte** statt ICU-Plural, in PHP mit `match`, in Vue mit einer Bedingung (siehe [Übersetzungen](/plugins/testen#übersetzungen)).
- **Kurze Beschriftungen im Menü:** Menüpunkte stehen neben denen von QuickTribe; „Mitbringen“ ist kurz und verwechselt sich mit keinem Punkt der Plattform.

## Ausprobieren

**Auf einer Installation** (Betreiber und Plattform-Admins):

1. Im Auslieferungspaket für Docker Compose liegt das Plugin schon unter `plugins/example-plugin/`. Bei Portainer, Coolify und ohne Docker die ZIP-Datei entpacken und den Ordner `example-plugin` wie unter [Plugins installieren](/plugins/installieren) ablegen – mit den Rechten von dort. Fehlt im Ordner das gebaute `dist/`, nehmen Sie die Fassung aus dem Auslieferungspaket.
2. Unter **Plattform-Admin → Plugins** die **Mitbringliste (Beispiel-Plugin)** aktivieren – oder auf der [Konsole](/betrieb#konsole) `php bin/console app:plugin:enable example-plugin`.
3. In einer Community unter **Einstellungen → Plugins** einschalten – oder `php bin/console app:plugin:enable example-plugin --community=<slug>`.
4. Einen kommenden Termin im Kalender öffnen und etwas eintragen. Die Einstellungen der Community öffnet unter **Einstellungen → Plugins** der Link **Einstellungen** beim Plugin; die plattformweiten stehen auf seiner Detailseite unter **Plattform-Admin → Plugins**.

**In der Entwicklungsumgebung** liegt das Plugin bereits im Quellcode unter `plugins/example-plugin/`. Die Demo-Daten (`php bin/console app:fixtures:load`) schalten es plattformweit und in der Community `demo` ein; die Oberfläche lädt dort ohne Build direkt aus `frontend/`. Bauen und testen:

```bash
docker compose exec app npm run build:plugins example-plugin                              # dist/ bauen und prüfen
docker compose exec -e APP_ENV=test app vendor/bin/phpunit plugins/example-plugin/tests   # PHPUnit
docker compose exec app npx playwright test plugins/example-plugin/tests/e2e              # Playwright, laufende App mit Demo-Daten
```

## Als Vorlage verwenden

1. Ordner kopieren und umbenennen – der Ordnername ist die neue Plugin-ID (siehe [Namensregeln](/plugins/entwickeln#namensregeln)).
2. In `plugin.json` `id`, `name`, `namespace` (`QuickTribePlugin\<Name>`) und `entry` anpassen, `version` auf `0.1.0` setzen; in allen PHP-Dateien – auch unter `tests/` – den Namespace `QuickTribePlugin\ExamplePlugin` ersetzen.
3. In `migrations/` die Tabelle umbenennen: `plg_<id>__…`, dabei wird `-` in der ID zu `_`. Den Tabellennamen in den Indexnamen ebenfalls ersetzen.
4. Im Frontend `PLUGIN_ID` in `frontend/extra.ts` setzen und das Literal `'settings.plugin.example-plugin'` in `SettingsInfo.vue` an die neue ID anpassen; in den Tests die Konstanten `ID` und `TABLE` und im Playwright-Szenario `PLUGIN`.
5. `dist/` löschen, nicht benötigte Teile entfernen, neu bauen (`npm run build:plugins <id>`), `php bin/console app:plugin:validate plugins/<id>` und die Tests laufen lassen.
