57 lines
3.3 KiB
Markdown
57 lines
3.3 KiB
Markdown
# DeskHub-Plugins
|
||
|
||
Jedes Plugin liegt in einem eigenen Ordner `plugins/<slug>/`. Installation, Aktivierung und Entfernung erfolgen im Adminportal unter **Plugins**.
|
||
Dieser Ordner wird bei System-Updates nie überschrieben.
|
||
|
||
> **Sicherheit:** Plugins sind PHP-Code und laufen mit allen Rechten des Systems (auch Datenbankzugriff). Es gibt keine Sandbox.
|
||
> Nur Plugins aus vertrauenswürdiger Quelle installieren. Bei Problemen: Datei `plugins/.disabled` anlegen – dann wird kein Plugin geladen.
|
||
> nginx: PHP-Dateien unter `/plugins/` per `location ~ ^/plugins/.*\.php$ { deny all; }` sperren (die mitgelieferte `.htaccess` gilt nur für Apache).
|
||
|
||
## Aufbau
|
||
|
||
```
|
||
plugins/mein-plugin/
|
||
plugin.json Pflicht
|
||
plugin.php Startdatei (Standard), registriert Hooks/Menüs/API
|
||
pages/*.php Seiten (als Menüpunkt registriert)
|
||
migrations/*.sql Datenbank-Änderungen (beim Aktivieren einmalig). Dialekt: name.sqlite.sql / name.mysql.sql laufen nur auf der jeweiligen Datenbank, name.sql auf beiden
|
||
assets/ js/css/Bilder
|
||
```
|
||
|
||
`plugin.json`:
|
||
|
||
```json
|
||
{
|
||
"slug": "mein-plugin",
|
||
"name": "Mein Plugin",
|
||
"version": "1.0.0",
|
||
"description": "Kurze Beschreibung",
|
||
"author": "Name",
|
||
"requires": "1.0.6",
|
||
"permissions": ["hooks.tickets", "ui.menu"]
|
||
}
|
||
```
|
||
|
||
`permissions` nennt die Erweiterungspunkte, die das Plugin nutzt (`hooks.tickets`, `hooks.cron`, `ui.menu`, `ui.sidebar`, `api.endpoints`, `api.public`, `db.migrations`). Der Admin bestätigt sie bei der Aktivierung; nicht deklarierte Erweiterungspunkte werden abgelehnt. Das ist keine Sandbox. Die Hooks `cron.minute` (etwa jede Minute, für kurze Prüfabstände) und `cron.run` (höchstens alle 5 Minuten), beide mit der Berechtigung `hooks.cron`, werden ausgelöst vom echten Server-Cronjob (`cron/run_plugins.php`, wird unter Einstellungen → Cron-Jobs eingetragen) und vom eingebauten Hintergrund-Betrieb, nie doppelt. Der Filter `staff.page.top` (Berechtigung `ui.sidebar`) ergänzt einen Hinweis oben auf jeder Seite des Mitarbeiterbereichs (fertiges HTML; Kontext: `staff`, `activePage`). Vollständige Dokumentation inklusive Signieren: README.md im Hauptverzeichnis.
|
||
|
||
## Erweiterungspunkte
|
||
|
||
| Funktion | Zweck |
|
||
|---|---|
|
||
| `plugin_add_hook($hook, $fn)` | auf Ereignisse reagieren |
|
||
| `plugin_add_filter($hook, $fn)` | Inhalte/Werte ergänzen oder verändern |
|
||
| `plugin_register_menu($label, $seite, $recht = null)` | Menüpunkt → `pages/<seite>.php` (Variablen `$staff`, `$pdo`) |
|
||
| `plugin_register_api($name, $fn, $recht = null)` | Endpunkt `/api/staff/v1/plugin.php?p=<slug>&endpoint=<name>` |
|
||
| `plugin_setting($slug, $key)` / `plugin_set_setting(...)` | eigene Einstellungen |
|
||
|
||
Ereignisse (Hooks): `ticket.created`, `ticket.replied`, `ticket.status_changed`, `ticket.assigned` (Daten: `event`, `ticketId`, …),
|
||
`cron.run` (alle ~5 Minuten), `plugin.uninstall.<slug>` (beim Entfernen mit „Daten löschen“).
|
||
Filter: `ticket.view.sidebar` (HTML-Block in der Ticketansicht; Plugin ist für das Escapen von Ausgaben selbst verantwortlich).
|
||
|
||
## Fehlerverhalten
|
||
|
||
Wirft ein Plugin einen Fehler, wird er protokolliert und das Ticket/die Seite läuft normal weiter. Nach 3 Fehlern wird das Plugin automatisch
|
||
deaktiviert (Fehlertext im Adminportal sichtbar). Schwere Fehler (Fatal Error) deaktivieren das gerade ausgeführte Plugin beim nächsten Start.
|
||
|
||
Ein Beispiel liegt unter `docs/plugin-beispiel/`.
|