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:

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

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

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

Namensregeln

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

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:
frontend/index.ts und frontend/HalloSeite.vue:
Dazu frontend/api-types.ts mit export interface Me { name: string | null }, frontend/plugin.css (siehe Frontend-SDK → Stile) und translations/messages.en.json:
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

npm run build:plugins ohne ID baut alle Plugins mit frontend/index.ts (siehe Frontend-SDK → Bauen). Vor der Auslieferung außerdem die Tests laufen lassen (siehe Prüfen, testen, übersetzen) 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:
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:
Die Rechte setzt der Betreiber ohnehin beim Einspielen (siehe Plugins installieren). Das Archiv darf keine symbolischen Links oder Hardlinks enthalten.