Filtres et Hooks

Le plugin Procaptcha introduit de nouveaux filtres et hooks WordPress, vous permettant de personnaliser son comportement.

1. Visibilité du Captcha

Par défaut, Procaptcha n’est affiché qu’aux utilisateurs non autorisés.

Pour contrôler ce comportement, en plus des paramètres du plugin, vous pouvez utiliser le hook is_captcha_present. Par exemple, pour rendre Procaptcha obligatoire pour tout le monde, ajoutez le code suivant au fichier functions.php de votre thème :

add_filter('prosopo/procaptcha/is_captcha_present', '__return_true');`

2. Message d’erreur personnalisé

Vous pouvez personnaliser le message d’erreur par défaut en ajoutant ce code au fichier functions.php de votre thème :

add_filter('prosopo/procaptcha/validation_error_message', function (string $message): string {
    return __('Message d’erreur personnalisé', 'my-theme');
});

3. Personnalisation des attributs Procaptcha

Au-delà des préférences de style dans les paramètres du plugin, vous pouvez personnaliser tous les attributs de données Procaptcha pris en charge en utilisant le filtre prosopo/procaptcha/captcha_attributes.

add_filter('prosopo/procaptcha/captcha_attributes', function (array $attributes): array {
    $attributes['language'] = 'de';
    return $attributes;
});

4. Correspondance de l’IP du visiteur

Lorsque la correspondance d’IP est activée, le plugin envoie l’adresse IP du visiteur avec chaque requête de vérification, et Procaptcha rejette un jeton résolu depuis une autre IP. Elle est désactivée par défaut : la plupart des sites sont derrière Cloudflare ou un autre proxy, et envoyer l’adresse du proxy au lieu de celle du visiteur rejetterait de vrais visiteurs.

Pour l’activer, allez dans Réglages > Prosopo Procaptcha > General et choisissez d’où vient l’IP du visiteur sous Correspondance de l’IP du visiteur :

Activé – le site est derrière Cloudflare : l’en-tête CF-Connecting-IP.
Activé – le site est derrière un autre proxy : la première adresse de l’en-tête X-Forwarded-For.
Activé – les visiteurs se connectent directement : REMOTE_ADDR.

Ne choisissez qu’un en-tête défini par votre proxy, car les visiteurs peuvent envoyer ces en-têtes eux-mêmes. Si l’en-tête est absent ou n’est pas une adresse IP valide, rien n’est envoyé et le jeton est vérifié sans correspondance d’IP.

Pour d’autres configurations, le filtre prosopo/procaptcha/visitor_ip reçoit l’IP issue du réglage (vide s’il est désactivé) et REMOTE_ADDR. Renvoyez l’IP à envoyer, ou une chaîne vide pour n’en envoyer aucune :

add_filter('prosopo/procaptcha/visitor_ip', function (string $ip, string $remote_addr): string {
    return $_SERVER['HTTP_TRUE_CLIENT_IP'] ?? $ip;
}, 10, 2);

La version 1.23.0 envoyait REMOTE_ADDR par défaut. Passez à la 1.24.0 ou plus récente si votre site est derrière un proxy.

5. Résultat de la vérification

Depuis la version 1.24.0, l’action prosopo/procaptcha/verification_result s’exécute après chaque requête de vérification avec le résultat et la réponse de l’API, pour enregistrer le score ou la raison du rejet d’une soumission. Lorsque WP_DEBUG est activé, les vérifications échouées sont aussi écrites dans le journal de débogage.

add_action('prosopo/procaptcha/verification_result', function (bool $verified, array $response): void {
    // $response: verified, status, score, reason, error, sessionId
    if (! $verified) {
        error_log('Procaptcha rejected a submission: ' . ($response['reason'] ?? 'unknown'));
    }
}, 10, 2);

6. Événements JavaScript

Depuis la version 1.24.0, le widget déclenche ces événements, qui remontent jusqu’au formulaire et au document :

prosopo-procaptcha:filled : le visiteur a résolu le captcha. event.detail.token contient le jeton.
prosopo-procaptcha:cleared : le jeton a expiré, le widget a rencontré une erreur ou a été réinitialisé.

Un jeton ne peut être vérifié qu’une seule fois. Le plugin réinitialise le captcha après les soumissions AJAX des plugins de formulaires pris en charge. Pour vos propres formulaires AJAX, déclenchez prosopo-procaptcha:reset sur le formulaire (ou sur tout élément contenant le captcha, ou sur document pour tous les réinitialiser) :

document.addEventListener('prosopo-procaptcha:filled', (event) => {
    console.log('Token received', event.detail.token);
});

document.addEventListener('prosopo-procaptcha:cleared', (event) => {
    console.log('Token expired or the widget was reset', event.target);
});

// Reset the captcha in a form, e.g. after your own AJAX submission.
form.dispatchEvent(new Event('prosopo-procaptcha:reset'));

7. Formulaires avec Procaptcha dans les tests

Si vos tests impliquent des formulaires avec Procaptcha, vous pouvez contourner le Procaptcha en ajoutant la constante suivante à votre fichier wp-config.php :

define('PROSOPO_PROCAPTCHA_ALLOW_BYPASS', true);

Dans vos tests, ajoutez un élément input[name=procaptcha-response] avec la valeur bypass à n’importe quel formulaire pour simuler l’achèvement de Procaptcha.

Important : Cette constante de contournement ne doit être utilisée que dans les environnements de développement.