---
title: "Plugins entwickeln"
description: "Einstieg für Entwickler: Entwicklungsumgebung, Aufbau eines Plugins, plugin.json, Namensregeln, ein erstes Plugin, Bauen, Prüfen und Ausliefern"
---

Ein Plugin besteht aus PHP-Code gegen die **Plugin-Schnittstelle** `App\Plugin\Api`, optional einer Oberfläche mit Vue 3 und TypeScript gegen das **Frontend-SDK** `@quicktribe/sdk` und eigenen Datenbanktabellen mit SQL-Migrationen. Diese Seite führt durch Aufbau und Ablauf; die Einzelheiten stehen auf den folgenden Seiten:

| Seite | Inhalt |
| --- | --- |
| [PHP-Schnittstelle](/plugins/php-api) | Einstiegsklasse, Registry, Endpunkte, Request und Response, Prüfreihenfolge, Fehlerformat |
| [Erweiterungspunkte](/plugins/erweiterungspunkte) | Seiten, Menüpunkte, Zusatzfelder, Erweiterungen von Kern-Antworten, Einstellungen, Jobs, Aufgaben, Hinweise, Lebenszyklus |
| [Kern-Dienste](/plugins/kern-dienste) | `PluginContext` und alle Fassaden (Mitglieder, Events, Nachrichten, Mail, Datenbank, Speicher, PDF …) |
| [Hook-Katalog](/plugins/hooks) | alle Ereignisse mit ihren Daten |
| [Frontend-SDK](/plugins/frontend) | Import-Map, Slots, Seiten, UI-Bausteine, Stores, Bauen |
| [Datenbank und Migrationen](/plugins/datenbank) | Tabellen, Migrationsdateien, erlaubtes SQL |
| [Prüfen, testen, übersetzen](/plugins/testen) | `app:plugin:validate`, Testkit, Übersetzungen |
| [Grenzen und Regeln](/plugins/grenzen) | Limits, Zeitgrenzen, verbotene Funktionen |
| [Datenschutz und Beispieldaten](/plugins/datenschutz) | Datenexport, Löschung, Datenschutz-Absatz, Demo |
| [Beispiel-Plugin](/plugins/beispiel-plugin) | „Mitbringliste“: Vorlage mit den wichtigsten Erweiterungspunkten zum Herunterladen |

## Entwicklungsumgebung

Plugins entstehen in einer Entwicklungsumgebung mit dem **Quellcode von QuickTribe** (Docker Compose, PHP 8.5, Node). Das Plugin liegt dort unter `plugins/<id>/` im Projektverzeichnis; Build-Skript, Prüfwerkzeuge (PHPStan-Regeln, ESLint), Typen des SDK und das Testkit kommen aus dem Quellcode, und die Werkzeuge des Projekts (PHPStan, php-cs-fixer, ESLint, Prettier, vue-tsc, PHPUnit, Playwright) prüfen die Plugins mit.

Eingerichtet wird sie im Verzeichnis des Quellcodes:

```bash
make up          # Container bauen und starten (App, Worker, Datenbank, Redis, Mailpit …)
make install     # Composer- und npm-Abhängigkeiten
make migrate     # Datenbank: Migrationen der Plattform, danach die der aktiven Plugins
make fixtures    # Demo-Community laden, alle ladbaren Plugins einschalten (Logins in der Ausgabe)
```

Danach läuft QuickTribe unter `http://localhost:8080`. `make fixtures` schaltet die Plugins unter `plugins/` plattformweit und in der Community `demo` ein; fehlerhafte überspringt es mit einem Hinweis, bei einer offenen oder gescheiterten Migration bricht es ab (dann zuerst `php bin/console app:plugin:migrate --all`). Ein neues Plugin beginnt am einfachsten als Kopie des [Beispiel-Plugins](/plugins/beispiel-plugin#als-vorlage-verwenden).

In der Entwicklungsumgebung

- ist die Prüfung der Dateirechte aus (`APP_PLUGINS_ALLOW_WRITABLE=1`), Plugins dürfen also dem eigenen Konto gehören;
- lädt die Seite die Oberfläche direkt aus `frontend/index.ts` über den Vite-Dev-Server – mit Hot-Reload, ohne Build;
- sieht der Plattform-Admin die Plugins sofort unter `/admin/plugins`.

Befehle laufen im App-Container der Entwicklungsumgebung, z. B. `docker compose exec app php bin/console app:plugin:list` oder `docker compose exec app npm run build:plugins`; in den Beispielen steht nur der Teil ab `php` bzw. `npm`.

## Aufbau eines Plugins

```text
plugins/<id>/
  plugin.json        Manifest (Pflicht)
  src/               PHP-Klassen, PSR-4 unter dem Namespace aus plugin.json
  migrations/        SQL-Migrationen NNNN_name.sql
  templates/         Twig-Vorlagen nur für E-Mails (email/) und PDF (pdf/)
  translations/      messages.en.json – englische Texte (Deutsch ist Quelltext und Schlüssel)
  frontend/          Quellen der Oberfläche: index.ts, plugin.css, api-types.ts, *.vue, *.ts
  dist/              gebaute Oberfläche (npm run build:plugins) – nicht von Hand ändern
  tests/             PHPUnit-Tests (Namespace <Namespace>\Tests\), e2e/*.spec.ts für Playwright
  README.md
```

Ordner, deren Name mit einem Punkt beginnt, ignoriert QuickTribe. Seiten von Plugins sind immer Vue-Seiten; Twig-Vorlagen gibt es nur für E-Mails und PDF-Dokumente.

## plugin.json

```json
{
  "id": "hallo-welt",
  "name": "Hallo Welt",
  "version": "1.0.0",
  "description": "Begrüßt Mitglieder auf einer eigenen Seite.",
  "author": "Beispiel GmbH",
  "homepage": "https://example.org/hallo-welt",
  "requires": { "quicktribe": ">=2.23", "pluginApi": "^1.0" },
  "namespace": "QuickTribePlugin\\HalloWelt",
  "entry": "QuickTribePlugin\\HalloWelt\\HalloWeltPlugin",
  "assets": { "script": "dist/plugin.js", "style": "dist/plugin.css" },
  "perCommunity": true,
  "privacy": { "personalData": false }
}
```

| Feld | Regel |
| --- | --- |
| `id` | **Pflicht.** Plugin-ID, gleich dem Ordnernamen (siehe [Namensregeln](#namensregeln)) |
| `name` | **Pflicht.** Anzeigename, höchstens 80 Zeichen |
| `version` | **Pflicht.** Version nach [SemVer](https://semver.org), z. B. `1.2.0` |
| `namespace` | **Pflicht.** Genau `QuickTribePlugin\<Name>`, z. B. `QuickTribePlugin\HalloWelt` |
| `entry` | **Pflicht.** Einstiegsklasse unterhalb des Namespace; sie implementiert `App\Plugin\Api\Plugin` |
| `description`, `author`, `homepage` | Anzeige im Plattform-Admin (höchstens 1000 bzw. 120 Zeichen) |
| `requires.quicktribe` | Versionsbereich der Plattform: `>=`, `>`, `<=`, `<`, `=`, `^`; mehrere durch Leerzeichen = alle müssen gelten, z. B. `>=2.23 <3.0`. Passt die laufende Version nicht, ist das Plugin fehlerhaft und wird nicht geladen |
| `requires.pluginApi` | Version der Plugin-Schnittstelle, derzeit `1.9` – `^1.0` genügt; wer Forderungen und Lastschrift (`debits()`) nutzt, verlangt `^1.1`, wer Beiträge, Kurse, Lektionen, die [Filter-Hooks](/plugins/erweiterungspunkte#filter-hooks) oder das volle Geburtsdatum (`members()->birthDates()`) nutzt, `^1.2` (mit `"quicktribe": ">=2.24"`), wer Excel liest (`csv()->readXlsx()`), E-Mail-Adressen abgleicht (`members()->verifiedEmail()`/`matchEmails()`) Einladungen verschickt (`invites()->send()`) oder Vorschau-Events (`draft`) auswertet, `^1.3` (mit `"quicktribe": ">=2.25"`), wer Dienste nutzt (`duties()`, Hooks `duty.*`), `^1.6` (mit `"quicktribe": ">=2.33"`), wer das Startjahr einer Dienst-Art liest (`DutyInfo::$startYear`), `^1.7` (mit `"quicktribe": ">=2.34"`), wer Adressen ohne Konto anschreibt (`mailer()->sendToAddress()`), das freie Mail-Kontingent abfragt (`mailer()->remaining()`) oder ZIP-Archive schreibt (`storage()->…->putZip()`), `^1.8` (mit `"quicktribe": ">=2.35"`), wer auf die Absage einzelner Termine reagiert (Hooks `event.cancelled`, `event.reinstated`) oder sie abfragt (`events()->isCancelled()`, `cancelledKeys()`) oder wartende Dienste auswertet (`DutyStanding::$pending`, `duties()->pendingCount()`, `DutyInfo::$needsConfirmation`), `^1.9` (mit `"quicktribe": ">=2.37"`; fehlt die Angabe, gibt es eine Warnung) |
| `assets.script`, `assets.style` | gebaute Dateien unter `dist/` (`dist/plugin.js`, `dist/plugin.css`). Nur nötig, wenn das Plugin eine Oberfläche hat; in Produktion müssen die Dateien existieren |
| `perCommunity` | `true`: Owner und Admins schalten das Plugin je Community ein (nach der Aktivierung überall aus). Fehlt die Angabe, wirkt das Plugin nach der Aktivierung in allen Communities; Einstellungen gibt es dann nur plattformweit (`->scope(Scope::Platform)`, sonst `InvalidRegistration`) |
| `privacy.personalData` | `true`, wenn das Plugin personenbezogene Daten speichert – dann muss die Einstiegsklasse `PrivacyAware` implementieren (siehe [Datenschutz](/plugins/datenschutz)) |
| `privacy.birthDates` | `true`, wenn das Plugin volle Geburtsdaten liest (`members()->birthDates()`, ab Plugin-API 1.2) – nur zusammen mit `personalData`; ohne die Angabe wirft die Methode eine `LogicException`. Die Datenschutz-Vorlage der Community nennt das Plugin dann im Absatz „Geburtstag“ |
| `privacy.memberEmails` | `true`, wenn das Plugin E-Mail-Adressen mit bestätigten Konten abgleicht (`members()->verifiedEmail()`, `matchEmails()`, ab Plugin-API 1.3) oder Adressen ohne Konto anschreibt (`mailer()->sendToAddress()`, ab 1.8) – nur zusammen mit `personalData`; ohne die Angabe werfen die Methoden eine `LogicException`. Jeder Abgleich steht im Protokoll der Community |
| `privacy.accountSnapshot` | `true`, wenn das Plugin bei einer Kontolöschung Name, Anschrift, Geburtsdatum und Handynummer in eigene Unterlagen übernimmt (`members()->accountSnapshot()`, ab Plugin-API 1.5, nur in `deleteUserData()`) – nur zusammen mit `personalData`; ohne die Angabe wirft die Methode eine `LogicException`. Die Datenschutz-Vorlage der Community nennt das Plugin dann |
| `license` | `{ "required": …, "product": "…" }` wird nur angezeigt („Lizenzprüfung folgt“) |

Unbekannte Felder ergeben eine Warnung. Fehler im Manifest machen das Plugin ungültig; sie stehen im Plattform-Admin und in `app:plugin:validate`.

## Namensregeln

| Name | Regel | Beispiel |
| --- | --- | --- |
| Plugin-ID | 3–24 Zeichen, Kleinbuchstaben und Ziffern, einzelne Bindestriche innen; beginnt mit einem Buchstaben | `hallo-welt`, `members-plus` |
| Namespace | `QuickTribePlugin\` + ein Name in PascalCase, ohne weitere Ebenen | `QuickTribePlugin\HalloWelt` |
| Tabellen | `plg_<id>__<kurzname>`, dabei wird `-` in der ID zu `_`; Kurzname `[a-z][a-z0-9_]` bis 31 Zeichen, ganzer Name höchstens 64 Zeichen | `plg_hallo_welt__greetings` |
| Jobs, Aufgaben, Limiter, Krypto-Zwecke | Kleinbuchstaben, Ziffern, `_`, `.`, `-`, höchstens 40 Zeichen | `daily-cleanup` |
| Protokoll-Aktionen | wie oben; gespeichert als `plugin.<id>.<aktion>` mit höchstens 64 Zeichen insgesamt | `plugin.hallo-welt.greeted` |
| Pinia-Stores | `plugin.<id>.<name>` | `plugin.hallo-welt.greetings` |
| Zusatzfelder | `[a-z][a-z0-9_]`, höchstens 41 Zeichen | `member_number` |
| Einstellungen | beginnt mit einem Kleinbuchstaben, dann Buchstaben, Ziffern, `_` (camelCase erlaubt) | `maxSeats` |

Plugins dürfen nur ihre eigenen Klassen und die Plugin-Schnittstelle verwenden – nie Klassen anderer Plugins oder interne Klassen von QuickTribe (siehe [Grenzen und Regeln](/plugins/grenzen)).

## Ein erstes Plugin

Das Plugin `hallo-welt` bringt eine Seite in jeder Community, in der es eingeschaltet ist, einen Menüpunkt dorthin und einen Endpunkt, der den Namen des Betrachters liefert.

`src/HalloWeltPlugin.php`:

```php
<?php

declare(strict_types=1);

namespace QuickTribePlugin\HalloWelt;

use App\Plugin\Api\Exception\NotFound;
use App\Plugin\Api\NavArea;
use App\Plugin\Api\NavItem;
use App\Plugin\Api\Plugin;
use App\Plugin\Api\PluginContext;
use App\Plugin\Api\Registry;
use App\Plugin\Api\Request;

final class HalloWeltPlugin implements Plugin
{
    public function __construct(private readonly PluginContext $ctx)
    {
    }

    public function register(Registry $registry): void
    {
        // Seite /c/<slug>/plugins/hallo-welt (Titel ist ein Übersetzungsschlüssel)
        $registry->page('', 'Hallo Welt');
        $registry->navItem(new NavItem(area: NavArea::Community, label: 'Hallo Welt', path: '', icon: 'star'));
        // GET /api/plugins/hallo-welt/c/<slug>/me – Standard: Access::Member, mit Community
        $registry->api('GET', '/me', function (Request $request): array {
            $community = $request->community();
            $viewer = $request->viewer();
            if ($community === null || $viewer === null) {
                throw new NotFound();
            }
            $member = $this->ctx->members()->get($community->id, $viewer->userId);

            return ['name' => $member?->displayName];
        });
    }
}
```

`frontend/index.ts` und `frontend/HalloSeite.vue`:

```ts
import './plugin.css';
import { definePlugin } from '@quicktribe/sdk';
import en from '../translations/messages.en.json';

export default definePlugin((sdk) => {
  sdk.addMessages('en', en);
  // Routen relativ zur Seite /c/<slug>/plugins/hallo-welt
  sdk.registerRoutes([{ path: '/', component: () => import('./HalloSeite.vue') }]);
});
```

```vue
<script setup lang="ts">
import { onMounted, ref } from 'vue';
import { usePluginSdk } from '@quicktribe/sdk';
import type { Me } from './api-types';

const sdk = usePluginSdk();
const me = ref<Me | null>(null);
onMounted(async () => {
  me.value = await sdk.api.get<Me>('/me');
});
</script>

<template>
  <h1 data-ui="page-title" class="text-2xl font-semibold">{{ sdk.t('Hallo {name}!', { name: me?.name ?? '' }) }}</h1>
</template>
```

Dazu `frontend/api-types.ts` mit `export interface Me { name: string | null }`, `frontend/plugin.css` (siehe [Frontend-SDK → Stile](/plugins/frontend#stile-mit-tailwind)) und `translations/messages.en.json`:

```json
{
  "Hallo Welt": "Hello world",
  "Hallo {name}!": "Hello {name}!"
}
```

Ausprobieren:

1. Unter `/admin/plugins` erscheint **Hallo Welt** als *inaktiv* – **Aktivieren** (oder `php bin/console app:plugin:enable hallo-welt`).
2. In einer Community unter **Einstellungen → Plugins** einschalten (oder `php bin/console app:plugin:enable hallo-welt --community=<slug>`) und die Seite neu laden.
3. Der Menüpunkt **Hallo Welt** führt auf `/c/<slug>/plugins/hallo-welt`.

## Bauen, prüfen, ausliefern

```bash
npm run build:plugins hallo-welt                       # Oberfläche nach plugins/hallo-welt/dist/ bauen
php bin/console app:plugin:validate plugins/hallo-welt # Manifest, Code, Migrationen, dist/ prüfen
```

`npm run build:plugins` ohne ID baut alle Plugins mit `frontend/index.ts` (siehe [Frontend-SDK → Bauen](/plugins/frontend#bauen)). Vor der Auslieferung außerdem die Tests laufen lassen (siehe [Prüfen, testen, übersetzen](/plugins/testen)) und die Version in `plugin.json` erhöhen.

Ausgeliefert wird der Plugin-Ordner **mit `dist/`**, ohne `node_modules/`, ohne Source-Maps (`*.map`) und ohne `tests/` und `frontend/` (die braucht der Betrieb nicht). Damit die Dateien beim Betreiber gleich `root` gehören und nicht schreibbar sind, packen Sie das Archiv z. B. so:

```bash
cd plugins
tar --owner=0 --group=0 --numeric-owner --mode=go-w \
    --exclude=node_modules --exclude='*.map' --exclude=tests --exclude=frontend \
    -czf hallo-welt-1.0.0.tar.gz hallo-welt
```

Unter macOS kennt `tar` (bsdtar) weder `--owner`/`--group` noch `--mode`: dort `--uid 0 --gid 0` angeben und die Rechte vorher mit `chmod` setzen; `COPYFILE_DISABLE=1` verhindert zusätzliche `._*`-Dateien im Archiv:

```bash
cd plugins
chmod -R u+rwX,go+rX,go-w hallo-welt
COPYFILE_DISABLE=1 tar --uid 0 --gid 0 \
    --exclude=node_modules --exclude='*.map' --exclude=tests --exclude=frontend \
    -czf hallo-welt-1.0.0.tar.gz hallo-welt
```

Die Rechte setzt der Betreiber ohnehin beim Einspielen (siehe [Plugins installieren](/plugins/installieren)). Das Archiv darf keine symbolischen Links oder Hardlinks enthalten.
