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
- Parameter:
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
- Parameter:
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
- Parameter:
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
- Parameter:
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
- Parameter:
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
- Parameter:
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
- Parameter:
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
- Parameter:
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
- Parameter:
charitable_magic_link_form_shortcode– Filtert die Ausgabe des Magic-Link-Formular-Shortcodes- Parameter:
$output(string) - Gibt zurück: Modifizierte Shortcode-Ausgabe
- Parameter:
Authentifizierungsablauf
- Eingeloggte Benutzer: Wenn ein WordPress-Benutzer eingeloggt ist, wird der Magic-Link umgangen und die Standard-Benutzerauthentifizierung verwendet.
- Magic-Link-Benutzer: Wenn nicht eingeloggt, prüft das System auf ein gültiges Magic-Link-Token.
- 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_tokenParameter - Verweist auf die URL der Spender-Dashboard-Seite
- Enthält den Verifizierungsschlüssel als
{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
- Benutzer gibt E-Mail-Adresse ein
- Formular validiert E-Mail-Format
- System prüft, ob ein Spender mit dieser E-Mail existiert
- Ratenbegrenzung wird geprüft
- Wenn erlaubt, wird die E-Mail mit dem magischen Link gesendet
- 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
- Gibt zurück:
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
- Gibt zurück:
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
- Gibt zurück:
Klassenmethoden
Die Klasse Charitable_Magic_Link bietet die folgenden öffentlichen Methoden:
get_instance()– Singleton-Instanz der Klasse abrufenget_token()– Token aus Cookie oder GET-Parameter abrufenis_valid_token($token)– Prüfen, ob ein Token gültig und nicht abgelaufen istis_valid_verify_key($token)– Prüfen, ob ein Verifizierungsschlüssel gültig istget_donor_by_token($token)– Spenderobjekt anhand des Tokens abrufenget_donor_by_verify_key($verify_key)– Spenderobjekt anhand des Verifizierungsschlüssels abrufencan_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 sendengenerate_verify_key()– Neuen Verifizierungsschlüssel generieren (zufälliger 32-Zeichen-String)
Token-Lebenszyklus
Token-Erstellung
- 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
- 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
- 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
- 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_throttleZeitstempel - 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:
- Neuer magischer Link angefordert: Alle vorhandenen Tokens für den Spender werden ungültig, wenn ein neuer magischer Link angefordert wird
- Benutzer-Logout: Alle Tokens für den Spender werden beim Logout ungültig
- Token-Ablauf: Abgelaufene Tokens sind automatisch ungültig
- Sitzungs-Diskrepanz: Wenn Sitzungs- und Token-Spender-IDs nicht übereinstimmen, wird die Sitzung gelöscht
Logout-Prozess
- Logout-Anfrage:
- Benutzer klickt auf Logout-Link (erfordert Nonce)
- Nonce verifiziert
- Spender-ID aus Sitzung abgerufen
- Token-Invalidierung:
- Alle Tokens für den Spender werden aus der Datenbank gelöscht
- Sitzungsdaten gelöscht
- Cookies gelöscht
- Weiterleitung:
- Benutzer wird zur Homepage weitergeleitet (saubere URL, keine Abfrageparameter)
- Die Weiterleitungs-URL kann über
charitable_magic_link_logout_redirectgefiltert 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 wirdmagic_link_used– Wenn ein Magic-Link erfolgreich zum Zugriff auf das Dashboard verwendet wirdmagic_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
