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 unterplugins/<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:
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.
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
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 Pluginhallo-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:
frontend/api-types.ts mit export interface Me { name: string | null }, frontend/plugin.css (siehe Frontend-SDK → Stile) und translations/messages.en.json:
- Unter
/admin/pluginserscheint Hallo Welt als inaktiv – Aktivieren (oderphp bin/console app:plugin:enable hallo-welt). - In einer Community unter Einstellungen → Plugins einschalten (oder
php bin/console app:plugin:enable hallo-welt --community=<slug>) und die Seite neu laden. - 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:
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: