Custom Form Handler WP Registry grade A. No security issues foundWP RegistryNo security issues foundOpen the reportA

WordPress-Plugin für Multi-Step-Lead-Formulare mit:

• Fenster-Anfragen
• Energieberatung / BAFA / KfW
• HTML-E-Mail-Versand
• lokale Lead-Speicherung vor E-Mail/Webhook
• n8n-Webhook
• GitHub-basierte Plugin-Updates

Funktionen

• Multi-Step-Formulare ohne jQuery
• Serverseitige Validierung
• Lokales Lead-Backup im WordPress-Admin unter Einstellungen > Gespeicherte Leads
• Nonce-Schutz und nicht-blockierendes Honeypot-Logging
• Rate-Limit pro IP
• Inline-Fehler für Feldvalidierung
• Pop-up-Fehler bei technischen Absendeproblemen
• Schrittwechsel und Absenden werden blockiert, bis alle Pflichtfelder gültig sind
• Zustellfreundliche E-Mail-Header: technische Absenderadresse, Lead-Adresse als Reply-To
• Schlanker Kontaktabschluss: PLZ, Name, E-Mail, optionale Telefonnummer und DSGVO-Zustimmung
• Formulartyp-spezifischer Abschluss-Hinweis und CTA
• Browser-Custom-Events für datensparsame Funnel-Messung
• GitHub-Release-Workflow für Updates

Shortcodes

[fenster_lead_form]
[custom_form_shortcode]
[energiefoerderung_form]

Plugin-Einstellungen

Unter Einstellungen > Form Handler können konfiguriert werden:

• Empfänger-E-Mail
• E-Mail-Betreff
• Absendername
• Danke-Seite
• Fehler-Seite (Fallback)
• n8n Webhook URL
• n8n Webhook Secret
• GitHub Repository

Funnel-Events

Das Plugin löst auf dem jeweiligen Formular-Container das browserseitige Event cfh:form-event aus. Es werden keine personenbezogenen Daten übertragen. Eine Analytics- oder Consent-Lösung kann das Event erst nach erteilter Einwilligung auswerten.

event.detail enthält:

• event: form_view, step_complete, step_back, validation_error oder form_submit
• formType: window oder energy_funding
• step: aktuelle Schrittzahl
• totalSteps: Gesamtzahl der Schritte

Beispiel für eine nachgelagerte Integration:

document.addEventListener('cfh:form-event', (event) => {
    // Nur nach Zustimmung an die eigene Analytics-Lösung weitergeben.
    console.log(event.detail);
});

Automatische Updates

Das Plugin ist auf GitHub-Releases vorbereitet.

• Repository: 6ent/custom-form-handler
• Release-Asset: custom-form-handler.zip

Sobald ein neuer GitHub-Release mit höherer Version existiert, sollte WordPress ein Plugin-Update anzeigen.

Entwicklung

Lokale Syntax-Pruefung:

find . -name '*.php' -exec php -l {} \;

Lokales Deployment nach XAMPP:

./scripts/deploy-to-xampp.sh --dry-run
./scripts/deploy-to-xampp.sh

Automatisches Deployment nach jedem lokalen Commit aktivieren:

./scripts/install-git-hooks.sh

Danach fuehrt Git bei jedem git commit automatisch scripts/deploy-to-xampp.sh aus und synchronisiert das Plugin nach:

/Applications/XAMPP/xamppfiles/htdocs/wordpress/wp-content/plugins/custom-form-handler

Optional kann das Ziel ueber CFH_XAMPP_PLUGIN_DIR oder --target-dir ueberschrieben werden.

Lokaler E2E-Test

Der Browser-Test verwendet standardmäßig die lokale Förderformular-Seite:

https://localhost/wordpress/foerderservice/

Einrichten und nur den Seitenaufruf prüfen:

npm install
npm run test:e2e

Ein echter Test-Lead wird absichtlich nur mit expliziter Freigabe abgesendet. Vorher in WordPress einen lokalen Test-Empfänger und gegebenenfalls einen lokalen Webhook-Receiver konfigurieren, damit keine produktiven Systeme angesprochen werden:

CFH_E2E_ENABLE_SUBMIT=true npm run test:e2e

Der Erfolgs-Redirect enthält cfh_submission_id. Diese ID steht ebenfalls in den gespeicherten Lead-Daten, im E-Mail-Tracking und im Webhook-Payload und dient zur eindeutigen Prüfung eines Testlaufs.

Zustellwiederholung

Jeder gültige Lead wird vor E-Mail und Webhook als privater WordPress-Lead gespeichert. Schlägt die Übergabe an wp_mail() oder ein konfigurierter Webhook fehl, erhält der Lead den Status Fehlgeschlagen. Das Plugin plant dann bis zu fünf Zustellversuche mit wachsendem Abstand.

Ein Webhook gilt nur bei einer HTTP-2xx-Antwort als zugestellt. Die Versuchszähler und der Zeitpunkt des letzten Fehlers sind in der Lead-Detailansicht sichtbar.

Die Wiederholung verwendet WP-Cron. Für produktive Zuverlässigkeit sollte der Hoster daher WordPress-Cron regelmäßig ausführen, etwa im Fünf-Minuten-Takt:

wp cron event run --due-now --path=/pfad/zu/wordpress

Ein positives wp_mail() bestätigt nur die Übergabe an den lokalen Mailtransport. Die tatsächliche Zustellung ins Empfängerpostfach muss weiterhin über SMTP-/Mailprovider-Logs, Bounces und Spam-Quarantäne überwacht werden.

Änderungen pushen:

git add .
git commit -m "Ihre Änderung"
git push origin main

Release-Workflow

Der GitHub-Workflow kann:

• die Patch-Version automatisch erhöhen
• einen Tag erzeugen
• custom-form-handler.zip bauen
• einen GitHub-Release erstellen

Details stehen in RELEASING.md.