deskhub/DeskHub-Webseite/plugins

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:

{
  "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/.