Die Magic-Link-Funktion ermöglicht es Spendern, auf ihr Spender-Dashboard zuzugreifen, ohne ein WordPress-Benutzerkonto oder eine Anmeldung zu benötigen. Spender können per E-Mail einen sicheren, zeitlich begrenzten Link anfordern, der ihnen den Zugriff auf ihre Spendenhistorie und Kontoinformationen ermöglicht.

---

Inhaltsverzeichnis

---

Hooks und Filter

Die folgenden PHP-Hooks und Filter stehen zur Erweiterung und Anpassung der Magic-Link-Funktionalität zur Verfügung:

Magic-Link-Filter

• charitable_magic_link_logout_redirect – Filtert die Weiterleitungs-URL nach der Magic-Link-Abmeldung
  • Parameter: $redirect_url (string)
  • Gibt zurück: Modifizierte Weiterleitungs-URL als String
  • Hinweis: Das Filterergebnis wird validiert, um eine Weiterleitung zurück zum Spender-Dashboard zu verhindern
• charitable_is_magic_link_on_page – Ermittelt, ob die Magic-Link-Funktionalität auf der aktuellen Seite aktiv sein soll
  • Parameter: $is_magic_link_on_page (bool)
  • Gibt zurück: Boolean
  • Standard: True, wenn auf der Spender-Dashboard-Seite, eine Spender-Dashboard-Aktion vorhanden ist oder ein Magic-Link-Token vorhanden ist
• charitable_magic_link_verify_throttle – Filtert die Drosselungsperiode für Verifizierungsschlüssel-Anfragen (in Sekunden)
  • Parameter: Keine
  • Gibt zurück: Integer (Standard: 300 Sekunden / 5 Minuten)
• charitable_magic_link_limit_throttle – Filtert die maximale Anzahl von Magic-Link-Anfragen, die pro Drosselungsperiode zulässig sind
  • Parameter: Keine
  • Gibt zurück: Integer (Standard: 3 Anfragen)
• charitable_magic_link_token_expiration – Filtert die Token-Ablaufzeit (in Sekunden)
  • Parameter: Keine
  • Gibt zurück: Integer (Standard: 7200 Sekunden / 2 Stunden)
• charitable_magic_link_token_expired_message – Filtert die Fehlermeldung, die angezeigt wird, wenn das Token abläuft
  • Parameter: $message (string)
  • Gibt zurück: Modifizierte Nachricht als String

E-Mail-Filter

• charitable_email_magic_link_name – Filtert den Namen/Titel der E-Mail
  • Parameter: $name (string)
  • Gibt zurück: Modifizierter E-Mail-Name-String
• charitable_email_magic_link_default_subject – Filtert die Standard-Betreffzeile der E-Mail
  • Parameter: $subject (string), $email (Charitable_Email_Magic_Link Instanz)
  • Gibt zurück: Modifizierter Betreff-String
• charitable_email_magic_link_default_headline – Filtert die Standard-Überschrift der E-Mail
  • Parameter: $headline (string), $email (Charitable_Email_Magic_Link Instanz)
  • Gibt zurück: Modifizierte Überschriften-Zeichenkette
• charitable_email_magic_link_default_body – Filtert den Standard-E-Mail-Body-Inhalt
  • Parameter: $body (string), $email (Charitable_Email_Magic_Link Instanz)
  • Gibt zurück: Modifizierter Body-String

Dashboard-Vorlagenfilter

• charitable_magic_link_dashboard_access_heading – Filtert den Überschriften-Text für das Magic-Link-Zugriffsformular
  • Parameter: $heading (string)
  • Gibt zurück: Modifizierter Überschriften-Text
• charitable_magic_link_dashboard_access_description – Filtert den Beschreibungs-Text für das Magic-Link-Zugriffsformular
  • Parameter: $description (string)
  • Gibt zurück: Modifizierter Beschreibungs-Text
• charitable_magic_link_form_shortcode – Filtert die Ausgabe des Magic-Link-Formular-Shortcodes
  • Parameter: $output (string)
  • Gibt zurück: Modifizierte Shortcode-Ausgabe

---

Authentifizierungsablauf

1. Eingeloggte Benutzer: Wenn ein WordPress-Benutzer eingeloggt ist, wird der Magic-Link umgangen und die Standard-Benutzerauthentifizierung verwendet.
2. Magic-Link-Benutzer: Wenn nicht eingeloggt, prüft das System auf ein gültiges Magic-Link-Token.
3. Keine Authentifizierung: Wenn beides nicht vorhanden ist, wird das Magic-Link-Formular angezeigt (sofern aktiviert).

---

Einstellungen und Konfiguration

Die Magic-Link-Funktionalität kann unter Charitable → Einstellungen → Spender → Magic Link konfiguriert werden.

Einstellungen

• Magic Link aktivieren – Umschalten, um die Magic-Link-Funktionalität zu aktivieren/deaktivieren
  • Standard: Aktiviert
  • Hinweis: Erfordert, dass das Spender-Dashboard aktiviert und das Datenbank-Upgrade abgeschlossen ist.
• Magic-Link-Ablauf (Stunden) – Wie lange Magic-Links gültig bleiben
  • Standard: 2 Stunden
  • Bereich: Konfigurierbar über den charitable_magic_link_token_expiration -Filter
  • Hinweis: Der Ablauf wird ab dem Zeitpunkt der Token-Erstellung berechnet (nicht ab dem Zeitpunkt des E-Mail-Versands)

Voraussetzungen

• Spenden-Dashboard muss aktiviert sein
• Datenbank-Upgrade für Magic-Link-Spalten muss abgeschlossen sein
• Magic-Link-E-Mail kann nicht deaktiviert werden, während Magic-Link aktiviert ist

---

Sicherheitsfunktionen

Das Magic-Link-System umfasst mehrere Sicherheitsmaßnahmen:

Ratenbegrenzung

• Anforderungsdrosselung: Maximal 3 Magic-Link-Anfragen pro 5-Minuten-Fenster pro Spender
• Drosselungsfenster: 5 Minuten (konfigurierbar über charitable_magic_link_verify_throttle)
• Anforderungslimit: 3 Anfragen (konfigurierbar über charitable_magic_link_limit_throttle)
• Implementierung: Verwendet den WordPress-Objektspeicher und Spender-Metadaten zur Verfolgung der Anforderungsanzahl

Token-Sicherheit

• Eindeutige Tokens: Nur ein aktives Token pro Spender gleichzeitig
• Token-Invalidierung: Wenn ein neuer Magic-Link angefordert wird, werden alle vorhandenen Tokens für diesen Spender ungültig gemacht
• Ablauf: Tokens laufen nach der konfigurierten Zeit automatisch ab
• Sichere Cookies: In Cookies gespeicherte Tokens verwenden HttpOnly- und Secure-Flags (wenn SSL verfügbar ist)

Sitzungsvalidierung

• Spender-ID-Abgleich: Die Sitzungs-Spender-ID muss mit der Token-Spender-ID übereinstimmen
• Anforderungsvalidierung: AJAX-Anfragen validieren, dass die Token-Spender-ID mit der angeforderten Spender-ID übereinstimmt
• Schutz bei Sitzungsabweichung: Wenn die Sitzungs- und Token-Spender-IDs nicht übereinstimmen, wird die Sitzung gelöscht und eine erneute Authentifizierung ist erforderlich

Abmeldesicherheit

• Nonce-Schutz: Die Abmeldung erfordert eine gültige Nonce, um CSRF-Angriffe zu verhindern
• Token-Invalidierung: Die Abmeldung macht alle Tokens für den Spender in der Datenbank ungültig
• Cookie-Löschung: Alle Magic-Link-Cookies werden bei der Abmeldung gelöscht
• Sitzungsbereinigung: Alle Magic-Link-Sitzungsdaten werden gelöscht

---

Datenbankstruktur

Die Magic-Link-Funktionalität verwendet die folgenden Datenbankspalten in der Tabelle wp_charitable_donors:

Spalten

• magic_link_token – Speichert das persistente Zugriffstoken (32-stelliger String)
  • Wird festgelegt, wenn der Verifizierungsschlüssel zum ersten Mal verwendet wird
  • Wird gelöscht, wenn das Token abläuft oder ungültig gemacht wird
  • Für die fortlaufende Authentifizierung verwendet
• magic_link_verify_key – Speichert den anfänglichen Verifizierungsschlüssel (32-stelliger String)
  • Festgelegt, wenn die Magic-Link-E-Mail gesendet wird
  • Wird beim ersten Gebrauch in einen Token umgewandelt
  • Nach Umwandlung oder Ablauf gelöscht
• magic_link_verify_throttle – Speichert Zeitstempel für Ratenbegrenzung und Token-Ablauf
  • Wird verwendet, um zu verfolgen, wann der Verifizierungsschlüssel erstellt wurde (für Ratenbegrenzung)
  • Wird verwendet, um zu verfolgen, wann der Token erstellt wurde (für Ablaufprüfung)
  • Format: MySQL-Datum/Uhrzeit (Y-m-d H:i:s)

Spender-Metadaten

• _charitable_magic_link_throttle_count – Verfolgt die Anzahl der Magic-Link-Anfragen im aktuellen Ratenbegrenzungsfenster
  • Bei jeder Anfrage inkrementiert
  • Zurückgesetzt, wenn das Ratenbegrenzungsfenster abläuft
  • Wird mit dem Objekt-Cache verwendet, um die Ratenbegrenzung durchzusetzen

---

E-Mail-System

Die Magic-Link-E-Mail ist ein erforderlicher E-Mail-Typ, der nicht deaktiviert werden kann, solange Magic Link aktiviert ist.

E-Mail-Klasse

• Klasse: Charitable_Email_Magic_Link
• E-Mail-ID: magic_link
• Erforderlich: Ja (kann nicht deaktiviert werden, solange Magic Link aktiviert ist)

E-Mail-Felder

Die Magic-Link-E-Mail enthält die folgenden benutzerdefinierten Felder:

• {magic_link} – Die sichere URL für den Zugriff auf das Spender-Dashboard
  • Enthält den Verifizierungsschlüssel als magic_link_token Parameter
  • Verweist auf die URL der Spender-Dashboard-Seite
• {donor_name} – Der Vorname des Spenders (oder „Geschätzter Spender“, falls nicht verfügbar)
• {expiration_time} – Menschenlesbare Ablaufzeit (z. B. „in 2 Stunden“)

E-Mail-Vorlagen-Tags

Standard-Charitable-E-Mail-Vorlagen-Tags sind verfügbar, plus die oben aufgeführten benutzerdefinierten Felder.

E-Mail-Filter

Alle Standard-E-Mail-Filter für Spenden gelten, zuzüglich der spezifischen Filter für magische Links, die im Abschnitt „Hooks und Filter“ aufgeführt sind.

---

Shortcode

Das Formular für magische Links kann mit einem Shortcode angezeigt werden.

Shortcode

• Kurzcode: [charitable_magic_link_form]
• Attribute: Derzeit werden keine unterstützt
• Ausgabe: Zeigt das Formular zur Anforderung eines magischen Links an

Formularverarbeitung

1. Benutzer gibt E-Mail-Adresse ein
2. Formular validiert E-Mail-Format
3. System prüft, ob ein Spender mit dieser E-Mail existiert
4. Ratenbegrenzung wird geprüft
5. Wenn erlaubt, wird die E-Mail mit dem magischen Link gesendet
6. Erfolgs- oder Fehlermeldung wird angezeigt

Formularvalidierung

• E-Mail erforderlich: Muss eine gültige E-Mail-Adresse sein
• Spender muss existieren: E-Mail muss mit mindestens einer Spende verknüpft sein
• Ratenbegrenzung: Anfragelimits dürfen nicht überschritten werden

---

Hilfsfunktionen

Die folgenden Hilfsfunktionen stehen für Entwickler zur Verfügung:

Prüffunktionen

• charitable_is_magic_link_enabled() – Prüfen, ob der magische Link aktiviert ist
  • Gibt zurück: bool
  • Prüft: Spender-Dashboard aktiviert, Datenbank-Upgrade abgeschlossen, Einstellung aktiviert
• charitable_is_authenticated_via_magic_link() – Prüfen, ob der aktuelle Benutzer über einen magischen Link authentifiziert ist
  • Gibt zurück: bool
  • Prüft Sitzung und Token-Gültigkeit
• charitable_get_donor_id_from_magic_link() – Spender-ID aus der magischen Link-Authentifizierung abrufen
  • Gibt zurück: int|false
  • Gibt die Spender-ID zurück, wenn ein gültiges magisches Link-Token vorhanden ist, andernfalls false

Klassenmethoden

Die Klasse Charitable_Magic_Link bietet die folgenden öffentlichen Methoden:

• get_instance() – Singleton-Instanz der Klasse abrufen
• get_token() – Token aus Cookie oder GET-Parameter abrufen
• is_valid_token($token) – Prüfen, ob ein Token gültig und nicht abgelaufen ist
• is_valid_verify_key($token) – Prüfen, ob ein Verifizierungsschlüssel gültig ist
• get_donor_by_token($token) – Spenderobjekt anhand des Tokens abrufen
• get_donor_by_verify_key($verify_key) – Spenderobjekt anhand des Verifizierungsschlüssels abrufen
• can_send_email($donor_id) – Prüfen, ob eine Magic-Link-E-Mail gesendet werden kann (Ratenbegrenzung)
• send_email($donor_id, $email) – Magic-Link-E-Mail an Spender senden
• generate_verify_key() – Neuen Verifizierungsschlüssel generieren (zufälliger 32-Zeichen-String)

---

Token-Lebenszyklus

Token-Erstellung

1. Benutzer fordert Magic Link an:
   • Spender gibt E-Mail im Formular ein
   • System generiert Verifizierungsschlüssel
   • Verifizierungsschlüssel gespeichert in magic_link_verify_key
   • E-Mail mit Verifizierungsschlüssel in der URL gesendet
2. Benutzer klickt auf E-Mail-Link:
   • Verifizierungsschlüssel validiert
   • Verifizierungsschlüssel in Token umgewandelt
   • Token gespeichert in magic_link_token
   • Verifizierungsschlüssel aus Datenbank gelöscht
   • Cookie mit Token gesetzt
   • Sitzung erstellt

Token-Nutzung

1. Seitenaufruf:
   • System prüft auf Token im Cookie oder GET-Parameter
   • Token validiert (nicht abgelaufen, existiert in Datenbank)
   • Sitzung validiert (Spender-ID stimmt überein)
   • Zugriff gewährt, wenn alle Prüfungen erfolgreich sind
2. AJAX-Anfragen:
   • Token bei jeder Anfrage validiert
   • Spender-ID aus Token muss mit angeforderter Spender-ID übereinstimmen
   • Sitzungs-Spender-ID muss mit Token-Spender-ID übereinstimmen

Token-Ablauf

• Ablaufzeit: Konfigurierbar (Standard: 2 Stunden)
• Ablaufprüfung: Basierend auf magic_link_verify_throttle Zeitstempel
• Verhalten bei abgelaufenem Token:
  • Token ist nicht mehr gültig
  • Benutzer muss einen neuen magischen Link anfordern
  • Fehlermeldung angezeigt

Token-Invalidierung

Tokens werden in folgenden Szenarien invalidiert:

1. Neuer magischer Link angefordert: Alle vorhandenen Tokens für den Spender werden ungültig, wenn ein neuer magischer Link angefordert wird
2. Benutzer-Logout: Alle Tokens für den Spender werden beim Logout ungültig
3. Token-Ablauf: Abgelaufene Tokens sind automatisch ungültig
4. Sitzungs-Diskrepanz: Wenn Sitzungs- und Token-Spender-IDs nicht übereinstimmen, wird die Sitzung gelöscht

Logout-Prozess

1. Logout-Anfrage:
   • Benutzer klickt auf Logout-Link (erfordert Nonce)
   • Nonce verifiziert
   • Spender-ID aus Sitzung abgerufen
2. Token-Invalidierung:
   • Alle Tokens für den Spender werden aus der Datenbank gelöscht
   • Sitzungsdaten gelöscht
   • Cookies gelöscht
3. Weiterleitung:
   • Benutzer wird zur Homepage weitergeleitet (saubere URL, keine Abfrageparameter)
   • Die Weiterleitungs-URL kann über charitable_magic_link_logout_redirect gefiltert werden

---

Zusätzliche Hinweise

Kompatibilität

• Magischer Link funktioniert neben der Standard-WordPress-Benutzerauthentifizierung
• Wenn ein Benutzer angemeldet ist, wird der magische Link umgangen
• Magischer Link wird nur für nicht angemeldete Benutzer aktiviert

Protokollierung

Das System protokolliert Aktivitäten des magischen Links im Spenderprotokoll:

• magic_link_sent – Wenn eine Magic-Link-E-Mail gesendet wird
• magic_link_used – Wenn ein Magic-Link erfolgreich zum Zugriff auf das Dashboard verwendet wird
• magic_link_failed – Wenn ein Magic-Link-Versuch fehlschlägt (ungültiger/abgelaufener Token)

Debug-Modus

Wenn WP_DEBUG aktiviert ist, sind detaillierte Protokolle verfügbar für:

• Token-Validierung
• Sitzungsverwaltung
• Ratenbegrenzung
• Abmeldeverarbeitung

---

Zusätzliche Ressourcen

Weitere Informationen zur Erweiterung der Magic-Link-Funktionalität finden Sie hier:

• Charitable Entwicklerdokumentation
• WordPress Hooks und Filter Dokumentation
• Charitable GitHub Repository

---

Dokumentversion: 1.0
Zuletzt aktualisiert: Nov 2025