La fonctionnalité de lien magique permet aux donateurs d'accéder à leur tableau de bord de donateur sans avoir besoin d'un compte utilisateur WordPress ou d'une connexion. Les donateurs peuvent demander un lien sécurisé et à durée limitée par e-mail qui leur donne accès à leur historique de dons et aux informations de leur compte.
Table des matières
Accroches et filtres
Les hooks et filtres PHP suivants sont disponibles pour étendre et personnaliser la fonctionnalité de lien magique :
Filtres de lien magique
charitable_magic_link_logout_redirect– Filtrer l'URL de redirection après la déconnexion du lien magique- Paramètres :
$redirect_url(string) - Retourne : Chaîne d'URL de redirection modifiée
- Remarque : Le résultat du filtre est validé pour empêcher la redirection vers le tableau de bord du donateur
- Paramètres :
charitable_is_magic_link_on_page– Déterminer si la fonctionnalité de lien magique doit être active sur la page actuelle- Paramètres :
$is_magic_link_on_page(bool) - Retourne : Booléen
- Par défaut : Vrai si sur la page du tableau de bord du donateur, a l'action donor_dashboard, ou a un jeton magic_link_token
- Paramètres :
charitable_magic_link_verify_throttle– Filtrer la période de limitation des demandes de clé de vérification (en secondes)- Paramètres : Aucun
- Retourne : Entier (par défaut : 300 secondes / 5 minutes)
charitable_magic_link_limit_throttle– Filtrer le nombre maximum de demandes de lien magique autorisées par période de limitation- Paramètres : Aucun
- Retourne : Entier (par défaut : 3 requêtes)
charitable_magic_link_token_expiration– Filtrer le temps d'expiration du jeton (en secondes)- Paramètres : Aucun
- Retourne : Entier (par défaut : 7200 secondes / 2 heures)
charitable_magic_link_token_expired_message– Filtrer le message d'erreur affiché lorsque le jeton expire- Paramètres :
$message(string) - Retourne : Chaîne de message modifiée
- Paramètres :
Filtres d'e-mail
charitable_email_magic_link_name– Filtrer le nom/titre de l'e-mail- Paramètres :
$name(string) - Retourne : Chaîne de nom d'e-mail modifiée
- Paramètres :
charitable_email_magic_link_subject– Filtrer la ligne d'objet par défaut de l'e-mail- Paramètres :
$subject(string),$email(instance de Charitable_Email_Magic_Link) - Retourne : Chaîne d'objet modifiée
- Paramètres :
charitable_email_magic_link_default_headline– Filtrer le titre par défaut de l'e-mail- Paramètres :
$headline(string),$email(instance de Charitable_Email_Magic_Link) - Retourne : Chaîne de titre modifiée
- Paramètres :
charitable_email_magic_link_default_body– Filtrer le contenu du corps de l'e-mail par défaut- Paramètres :
$body(string),$email(instance de Charitable_Email_Magic_Link) - Retourne : Chaîne de corps modifiée
- Paramètres :
Filtres de modèle de tableau de bord
charitable_magic_link_dashboard_access_heading– Filtrer le texte du titre pour le formulaire d'accès au lien magique- Paramètres :
$heading(string) - Retourne : Chaîne de titre modifiée
- Paramètres :
charitable_magic_link_dashboard_access_description– Filtrer le texte de description pour le formulaire d'accès au lien magique- Paramètres :
$description(string) - Retourne : Chaîne de description modifiée
- Paramètres :
charitable_magic_link_form_shortcode– Filtrer la sortie du shortcode du formulaire de lien magique- Paramètres :
$output(string) - Retourne : Sortie de shortcode modifiée
- Paramètres :
Flux d'authentification
- Utilisateurs connectés : Si un utilisateur WordPress est connecté, le lien magique est contourné et l'authentification utilisateur standard est utilisée
- Utilisateurs de lien magique : Si non connecté, le système vérifie la validité du jeton de lien magique
- Aucune authentification : Si aucun des deux n'existe, le formulaire de lien magique est affiché (s'il est activé)
Paramètres et configuration
La fonctionnalité de lien magique peut être configurée dans Charitable → Paramètres → Donateurs → Lien magique.
Paramètres
- Activer le lien magique – Basculer pour activer/désactiver la fonctionnalité de lien magique
- Par défaut : Activé
- Remarque : Nécessite que le tableau de bord des donateurs soit activé et que la mise à niveau de la base de données soit terminée
- Expiration du lien magique (heures) – Durée de validité des liens magiques
- Par défaut : 2 heures
- Plage : Configurable via le filtre
charitable_magic_link_token_expiration - Remarque : L'expiration est calculée à partir de la création du jeton (et non de l'envoi de l'e-mail)
Exigences
- Le tableau de bord du donateur doit être activé
- La mise à niveau de la base de données pour les colonnes de lien magique doit être terminée
- L'e-mail du lien magique ne peut pas être désactivé tant que le lien magique est activé
Fonctionnalités de sécurité
Le système de liens magiques comprend plusieurs mesures de sécurité :
Limitation de débit
- Limitation des requêtes : Maximum 3 requêtes de lien magique par fenêtre de 5 minutes par donateur
- Fenêtre de limitation : 5 minutes (configurable via
charitable_magic_link_verify_throttle) - Limite de requêtes : 3 requêtes (configurable via
charitable_magic_link_limit_throttle) - Implémentation : Utilise le cache d'objets WordPress et les métadonnées du donateur pour suivre le nombre de requêtes
Sécurité des jetons
- Jetons uniques : Un seul jeton actif par donateur à la fois
- Invalidation des jetons : Lorsqu'un nouveau lien magique est demandé, tous les jetons existants pour ce donateur sont invalidés
- Expiration : Les jetons expirent automatiquement après la période configurée
- Cookies sécurisés : Les jetons stockés dans les cookies utilisent les indicateurs HttpOnly et Secure (lorsque le SSL est disponible)
Validation de session
- Correspondance de l'ID du donateur : L'ID du donateur de la session doit correspondre à l'ID du donateur du jeton
- Validation des requêtes : Les requêtes AJAX valident que l'ID du donateur du jeton correspond à l'ID du donateur demandé
- Protection contre les décalages de session : Si les ID de session et de jeton du donateur ne correspondent pas, la session est effacée et une réauthentification est requise
Sécurité de déconnexion
- Protection Nonce : La déconnexion nécessite un nonce valide pour empêcher les attaques CSRF
- Invalidation des jetons : La déconnexion invalide tous les jetons du donateur dans la base de données
- Effacement des cookies : Tous les cookies de lien magique sont effacés lors de la déconnexion
- Effacement de la session : Toutes les données de session de lien magique sont effacées
Structure de la base de données
La fonctionnalité de lien magique utilise les colonnes de base de données suivantes dans la table wp_charitable_donors :
Colonnes
magic_link_token– Stocke le jeton d'accès persistant (chaîne de 32 caractères)- Défini lorsque la clé de vérification est utilisée pour la première fois
- Effacé lorsque le jeton expire ou est invalidé
- Utilisé pour l'authentification en cours
magic_link_verify_key– Stocke la clé de vérification initiale (chaîne de 32 caractères)- Défini lorsque l'e-mail du lien magique est envoyé
- Converti en jeton lors de la première utilisation
- Effacé après conversion ou expiration
magic_link_verify_throttle– Stocke l'horodatage pour la limitation du débit et l'expiration du jeton- Utilisé pour suivre la date de création de la clé de vérification (pour la limitation du débit)
- Utilisé pour suivre la date de création du jeton (pour la vérification de l'expiration)
- Format : date/heure MySQL (Y-m-d H:i:s)
Métadonnées du donateur
_charitable_magic_link_throttle_count– Suivi du nombre de demandes de lien magique dans la fenêtre de limitation actuelle- Incrémenté à chaque demande
- Réinitialisé lorsque la fenêtre de limitation expire
- Utilisé avec le cache d'objets pour appliquer la limitation du débit
Système d'e-mail
L'e-mail du lien magique est un type d'e-mail requis qui ne peut pas être désactivé tant que le lien magique est activé.
Classe d'e-mail
- Classe :
Charitable_Email_Magic_Link - ID d'e-mail :
magic_link - Requis : Oui (ne peut pas être désactivé tant que le lien magique est activé)
Champs d'e-mail
L'e-mail du lien magique inclut les champs personnalisés suivants :
{magic_link}– L'URL sécurisée pour accéder au tableau de bord du donateur- Contient la clé de vérification en tant que paramètre
magic_link_token - Pointe vers l'URL de la page du tableau de bord du donateur
- Contient la clé de vérification en tant que paramètre
{donor_name}– Le prénom du donateur (ou « Donateur apprécié » s'il n'est pas disponible){expiration_time}– Heure d'expiration lisible par l'homme (par exemple, « dans 2 heures »)
Balises de modèle d'e-mail
Les balises standard des e-mails de Charitable sont disponibles, ainsi que les champs personnalisés listés ci-dessus.
Filtres d'e-mail
Tous les filtres d'e-mails standard de Charitable s'appliquent, ainsi que les filtres spécifiques aux liens magiques listés dans la section Hooks et Filtres.
Raccourci
Le formulaire de lien magique peut être affiché à l'aide d'un shortcode.
Raccourci
- Shortcode :
[charitable_magic_link_form] - Attributs : Aucun actuellement pris en charge
- Sortie : Affiche le formulaire de demande de lien magique
Traitement du formulaire
- L'utilisateur saisit l'adresse e-mail
- Le formulaire valide le format de l'e-mail
- Le système vérifie si un donateur existe avec cette adresse e-mail
- La limitation de débit est vérifiée
- Si autorisé, l'e-mail de lien magique est envoyé
- Un message de succès ou d'erreur s'affiche
Validation du formulaire
- E-mail requis : Doit être une adresse e-mail valide
- Le donateur doit exister : L'e-mail doit être associé à au moins un don
- Limitation de débit : Ne doit pas dépasser les limites de requêtes
Fonctions d'aide
Les fonctions d'assistance suivantes sont disponibles pour les développeurs :
Vérifier les fonctions
charitable_is_magic_link_enabled()– Vérifier si le lien magique est activé- Retourne :
bool - Vérifications : Tableau de bord du donateur activé, mise à niveau de la base de données terminée, paramètre activé
- Retourne :
charitable_is_authenticated_via_magic_link()– Vérifier si l'utilisateur actuel est authentifié via un lien magique- Retourne :
bool - Vérifie la session et la validité du jeton
- Retourne :
charitable_get_donor_id_from_magic_link()– Obtenir l'ID du donateur à partir de l'authentification par lien magique- Retourne :
int|false - Retourne l'ID du donateur si un jeton de lien magique valide existe, sinon false
- Retourne :
Méthodes de classe
La classe Charitable_Magic_Link fournit les méthodes publiques suivantes :
get_instance()– Obtenir l'instance singleton de la classeget_token()– Obtenir le jeton à partir d'un cookie ou d'un paramètre GETis_valid_token($token)– Vérifier si un jeton est valide et non expiréis_valid_verify_key($token)– Vérifier si une clé de vérification est valideget_donor_by_token($token)– Obtenir l'objet donateur par jetonget_donor_by_verify_key($verify_key)– Obtenir l'objet donateur par clé de vérificationcan_send_email($donor_id)– Vérifier si l'e-mail de lien magique peut être envoyé (limitation de débit)send_email($donor_id, $email)– Envoyer un e-mail de lien magique au donateurgenerate_verify_key()– Générer une nouvelle clé de vérification (chaîne aléatoire de 32 caractères)
Cycle de vie du jeton
Création de jeton
- L'utilisateur demande un lien magique :
- Le donateur saisit son e-mail dans le formulaire
- Le système génère une clé de vérification
- La clé de vérification est stockée dans
magic_link_verify_key - E-mail envoyé avec la clé de vérification dans l'URL
- L'utilisateur clique sur le lien de l'e-mail :
- La clé de vérification est validée
- La clé de vérification est convertie en jeton
- Le jeton est stocké dans
magic_link_token - La clé de vérification est supprimée de la base de données
- Le cookie est défini avec le jeton
- La session est créée
Utilisation du jeton
- Chargement de la page :
- Le système recherche le jeton dans le cookie ou le paramètre GET
- Jeton validé (non expiré, existe dans la base de données)
- Session validée (l'ID du donateur correspond)
- Accès accordé si toutes les vérifications réussissent
- Requêtes AJAX :
- Jeton validé à chaque requête
- L'ID du donateur du jeton doit correspondre à l'ID du donateur demandé
- L'ID du donateur de la session doit correspondre à l'ID du donateur du jeton
Expiration du jeton
- Heure d'expiration : Configurable (par défaut : 2 heures)
- Vérification d'expiration : Basée sur l'horodatage
magic_link_verify_throttle - Comportement en cas de jeton expiré :
- Le jeton n'est plus valide
- L'utilisateur doit demander un nouveau lien magique
- Message d'erreur affiché
Invalidation du jeton
Les jetons sont invalidés dans les scénarios suivants :
- Nouveau lien magique demandé : Tous les jetons existants pour le donateur sont invalidés lorsqu'un nouveau lien magique est demandé
- Déconnexion de l'utilisateur : Tous les jetons du donateur sont invalidés lors de la déconnexion
- Expiration du jeton : Les jetons expirés sont automatiquement invalides
- Incompatibilité de session : Si les ID du donateur de la session et du jeton ne correspondent pas, la session est effacée
Processus de déconnexion
- Demande de déconnexion :
- L'utilisateur clique sur le lien de déconnexion (nécessite un nonce)
- Nonce vérifié
- ID du donateur récupéré de la session
- Invalidation du jeton :
- Tous les jetons du donateur effacés de la base de données
- Données de session effacées
- Cookies effacés
- Redirection :
- L'utilisateur est redirigé vers la page d'accueil (URL propre, sans paramètres de requête)
- L'URL de redirection peut être filtrée via
charitable_magic_link_logout_redirect
Notes supplémentaires
Compatibilité
- Le lien magique fonctionne parallèlement à l'authentification standard des utilisateurs WordPress
- Si un utilisateur est connecté, le lien magique est contourné
- Le lien magique ne s'active que pour les utilisateurs non connectés
Journalisation
Le journal du système enregistre les activités des liens magiques dans le journal des donateurs :
magic_link_sent– Lorsqu'un e-mail de lien magique est envoyémagic_link_used– Lorsqu'un lien magique est utilisé avec succès pour accéder au tableau de bordmagic_link_failed– Lorsqu'une tentative de lien magique échoue (jeton invalide/expiré)
Mode de débogage
Lorsque WP_DEBUG est activé, une journalisation détaillée est disponible pour :
- Validation du jeton
- Gestion de session
- Limitation du débit
- Traitement de la déconnexion
Ressources supplémentaires
Pour plus d'informations sur l'extension des fonctionnalités du lien magique :
- Documentation du développeur Charitable
- Documentation des Hooks et Filtres WordPress
- Dépôt GitHub Charitable
Version du document : 1.0
Dernière mise à jour : nov. 2025
