deskhub/wordpress-plugin/README.md

# DeskHub Tickets für WordPress

Mit diesem Plugin legen Besucher Ihrer WordPress-Seite Support-Tickets direkt in **DeskHub** an und können den Stand ihres Tickets abfragen. Das Plugin spricht die öffentliche API von DeskHub an. Die Standardfunktionen (Formular, Statusabfrage) laufen mit jedem DeskHub. Für **eigene Felder und Texte eines Hilfethemas** braucht DeskHub mindestens **Version 1.0.64**.

Das Formular liegt auf Ihrer WordPress-Seite und passt sich dem Theme an. DeskHub selbst lässt sich nicht in einen Rahmen (iframe) einbetten und das Plugin braucht das auch nicht.

## Funktionen

- **`[deskhub_ticket]`** zeigt das Formular. Das Plugin holt es aus DeskHub: Hast du bei einem **Hilfethema** oder in der **Abteilung** ein eigenes Formular eingerichtet (eigene Felder, Pflichtfelder, Auswahllisten, Texte, Reihenfolge, Breiten), erscheint es genauso auf deiner WordPress-Seite. Änderungen in DeskHub gelten nach spätestens 5 Minuten (oder sofort mit „Formulare neu laden“ in den Einstellungen). Nach dem Absenden sieht der Besucher seine Ticketnummer.
- **`[deskhub_status]`** zeigt die Statusabfrage: Ticketnummer und E-Mail-Adresse eingeben, dann erscheinen Status und öffentlicher Verlauf (interne Notizen bleiben unsichtbar).
- **Einstellungen** unter *Einstellungen → DeskHub Tickets*: Server-Adresse, API-Schlüssel, Abteilung, Hilfethema und Priorität, Einwilligungstext, Text nach dem Absenden, **Verbindung testen**.
- **Spamschutz** (funktioniert auch mit Seiten-Cache): unsichtbares Falle-Feld, Mindestzeit bis zum Absenden, Mengenbegrenzung je Besucher und Stunde, optional **Cloudflare Turnstile**.
- **Datenschutz:** optionales Einwilligungs-Kästchen. In der Datenbank stehen keine IP-Adressen (nur nicht umkehrbare Schlüssel für die Mengenbegrenzung).
- **Farben vom Theme:** Schrift, Rahmen und Feldhintergrund passen sich dem Theme an (auch dunkle Seiten). Die Akzentfarbe (Knopf) liest das Plugin aus Knöpfen und Links der Seite; in den Einstellungen lässt sie sich fest vorgeben.
- Deutsch und Englisch (die englische Oberfläche folgt der Sprache der WordPress-Seite).

## Einrichten

1. Ordner `deskhub-tickets` (aus dem ZIP) nach `wp-content/plugins/` kopieren oder das ZIP unter *Plugins → Installieren → Plugin hochladen* hochladen, dann aktivieren.
2. In **DeskHub** unter *Verwalten → API-Schlüssel* einen Schlüssel erstellen: Recht **„Tickets anlegen“**, für die Statusabfrage zusätzlich **„Tickets lesen“**.
3. In WordPress unter *Einstellungen → DeskHub Tickets* Server-Adresse (zum Beispiel `https://support.example.de`) und Schlüssel eintragen, speichern und **„Verbindung testen“** klicken.
4. Auf einer Seite den Shortcode `[deskhub_ticket]` einfügen (im Block-Editor mit dem Block „Shortcode“). Für die Statusabfrage eine zweite Seite mit `[deskhub_status]` anlegen und ihre Adresse in den Einstellungen eintragen, dann erscheint nach dem Absenden ein Link dorthin.

### Mehr Möglichkeiten im Shortcode

```text
[deskhub_ticket department="2" topic="5" priority="1"]
[deskhub_ticket topics="Rechnung:3,Technik:4" title="Support anfragen"]
```

- `department`, `topic`, `priority`: Nummern in DeskHub; überschreiben die Einstellungen für dieses Formular. Besucher können sie nicht ändern (sie reisen unterschrieben im Formular).
- `topics="Bezeichnung:Nummer,…"`: Besucher wählen ein Thema aus (Nummer des Hilfethemas in DeskHub). Je nach Thema erscheinen die passenden Felder und Texte (ohne Seitenneuladen).
- `topic="5"`: festes Hilfethema; sein Formular wird angezeigt. In den Einstellungen lässt sich das Standardthema aus einer Liste wählen.
- `title`: Überschrift über dem Formular.

### Sicherer: Schlüssel in der wp-config.php

```php
define('DESKHUB_TICKETS_API_KEY', 'dh_…');
define('DESKHUB_TICKETS_SERVER', 'https://support.example.de'); // optional
```

Dann steht der Schlüssel nicht in der Datenbank und das Feld in den Einstellungen ist gesperrt.

## Wenn die Verbindung nicht klappt

Unter *Einstellungen → DeskHub Tickets* gibt es **„Speichern und Verbindung testen“**. Der Test prüft die Werte, die du gerade eingegeben hast, und sagt, woran es liegt:

- **„Bitte Server-Adresse und API-Schlüssel eintragen“:** Das Schlüsselfeld war leer. Der Schlüssel wird nach dem Speichern nie wieder angezeigt (das Feld bleibt leer, daneben steht „gespeichert“). Zum Testen den Schlüssel neu eintragen oder in der `wp-config.php` festlegen.
- **„DeskHub lässt diese Adresse nicht zu“:** Der Schlüssel ist richtig, aber bei **„Erlaubte IPs“** des Schlüssels in DeskHub steht eine andere Adresse. Die Meldung nennt die Adresse, die DeskHub sieht: genau diese eintragen oder das Feld leer lassen. **Laufen WordPress und DeskHub auf demselben Server, ist `127.0.0.1` meist falsch:** Das Plugin ruft DeskHub über dessen Internet-Adresse auf, DeskHub sieht dann die öffentliche Adresse des Servers (hinter Cloudflare oder einem Proxy nur dann die richtige, wenn der Proxy in DeskHub unter den vertrauten Proxys eingetragen ist).
- **„DeskHub-Server ist nicht erreichbar“ mit Ursache in Klammern:** Zum Beispiel „Could not resolve host“ (Adresse falsch oder der Server findet seine eigene Domain nicht) oder „Connection timed out“ (manche Hoster erlauben dem Server nicht, sich über seine eigene öffentliche Adresse aufzurufen).
- **„Der Server hat den API-Schlüssel abgelehnt“:** Schlüssel falsch eingetragen, in DeskHub abgeschaltet, oder die erlaubten IPs passen nicht.

## Sicherheit

- Der API-Schlüssel wird **nur auf dem Server** gesendet, nie an den Browser. Die Einstellungsseite schreibt ihn nicht wieder in die Seite.
- Verbindung nur über **https** (http nur für `localhost`). Weiterleitungen werden nicht verfolgt.
- Alle Ausgaben werden maskiert. Eingaben werden bereinigt (HTML wird aus Nachrichten entfernt).
- Abteilung, Thema und Priorität sind im Formular **unterschrieben**: Ein Besucher kann nicht selbst eine andere Abteilung oder „dringend“ einsetzen.
- Die Statusabfrage braucht Ticketnummer **und** E-Mail-Adresse und ist auf 10 Abfragen je 10 Minuten begrenzt (bremst das Durchprobieren).
- Ein Schlüssel nur mit dem Recht „Tickets anlegen“ genügt für das Formular. Gibt es keine Statusseite, braucht er das Lesen-Recht nicht.

## Grenzen

- **Keine Dateianhänge:** Die öffentliche API von DeskHub nimmt nur Text. Der Anhang-Upload des Kundenformulars fehlt deshalb im WordPress-Formular.
- **Ältere DeskHub-Version:** Ohne die Formular-Schnittstelle (vor 1.0.64) zeigt das Plugin das einfache Formular ohne eigene Felder; Administratoren sehen einen Hinweis.
- **IP-Adresse im Ticket:** DeskHub sieht die IP-Adresse Ihres WordPress-Servers, nicht die des Besuchers.
- **Mengenbegrenzung der API:** DeskHub nimmt über die API höchstens 60 Tickets pro Minute an (für alle Aufrufer zusammen).
- Hinter einem Proxy zählt die Mengenbegrenzung die Adresse des Proxys. Der Filter `deskhub_tickets_client_ip` liefert die richtige Besucher-Adresse.

## Für Entwickler

- Filter `deskhub_tickets_form_cache_seconds` (Zwischenspeicher der Formulare, Standard 300), Filter `deskhub_tickets_payload` (Daten vor dem Senden anpassen, z. B. Bestelldaten ergänzen), Aktion `deskhub_tickets_created` (nach dem Anlegen: Ticketnummer und Daten), Filter `deskhub_tickets_allow_insecure` (http für interne Hosts erlauben).
- Tests: `php wordpress-plugin/tests/run.php` (mit Nachbau der WordPress-Funktionen). Mit `DESKHUB_URL` und `DESKHUB_KEY` läuft zusätzlich der ganze Weg gegen einen echten DeskHub-Testserver.
- Übersetzungen: `php wordpress-plugin/tools/extract-strings.php` listet die Texte, `php wordpress-plugin/tools/build-mo.php wordpress-plugin/tools/en.json` baut die `.po`/`.mo`-Dateien.
- ZIP packen: `php wordpress-plugin/tools/pack.php`.

## Was nicht geprüft ist

Das Plugin wurde mit einem Nachbau der WordPress-Funktionen und gegen einen echten DeskHub-Server getestet, **nicht in einer echten WordPress-Installation** (und nur mit PHP 8.2). Bitte vor dem Einsatz auf einer Testseite ausprobieren: Formular senden, Statusabfrage, Einstellungsseite, Seiten-Cache.