ldc-ovoteam/docs/recaptcha/RECAPTCHAPROVIDER.md

Documentation du RecaptchaProvider

Le RecaptchaProvider est un composant React qui encapsule la logique d’intégration de Google reCAPTCHA avec gestion des cookies et état du formulaire. Il fonctionne avec Inertia.js et React, et simplifie l’activation du reCAPTCHA dans n’importe quel formulaire.

---

1. Installation et import

import { RecaptchaProvider, useRecaptcha } from "@/front/providers/RecaptchaProvider";
// Ensuite, enveloppe ton formulaire avec le provider :
<RecaptchaProvider>
  <MonFormulaire />
</RecaptchaProvider>

// Tu peux être plus propre et entourer tout ton Applayout, ce qui évite d'encapsuler chaque formulaire
<RecaptchaProvider>
    {children}
</RecaptchaProvider>

2. Fonctionnement général

Le provider expose :

• enabled : boolean indiquant si le reCAPTCHA est activé (cookie accepté).
• getToken() : fonction pour récupérer le token généré par Google reCAPTCHA.
• formRef : référence vers le <form> HTML, utilisée pour injecter le conteneur reCAPTCHA et désactiver le formulaire si nécessaire.

2.1 Gestion automatique des cookies

Le provider utilise le hook useCookieNotice pour vérifier si l’utilisateur a accepté le service RECAPTCHA.

• Si accepté → le reCAPTCHA est initialisé sur le formulaire.
• Si non accepté → le formulaire reste inert, empêchant toute interaction jusqu’à ce que l’utilisateur donne son consentement.

2.2 Injection du formulaire

Le provider utilise InitRecaptcha([formRef.current]) pour :

• Créer un <div class="g-recaptcha"> dans le formulaire.
• Charger le script Google reCAPTCHA de manière asynchrone.
• Gérer le reset du reCAPTCHA si nécessaire.

2.3 Désactivation du formulaire

Le formulaire est automatiquement rendu inert tant que le reCAPTCHA n’est pas actif. Cela empêche les utilisateurs d’envoyer le formulaire avant d’avoir accepté les cookies.

3. Utilisation du hook useRecaptcha

Dans un composant enfant du provider, tu peux accéder au contexte avec :

const { enabled, getToken, formRef } = useRecaptcha();

Exemples :

• Vérifier si le reCAPTCHA est activé :

if (!enabled) {
  console.log("Le reCAPTCHA n'est pas actif");
}

• Récupérer le token au moment du submit :

const token = getToken();
data["g-recaptcha-response"] = token;
post(route('contact.submit'), { data });

• Associer formRef à un <form> :

<form ref={formRef} data-recaptcha-key={recaptchaKey}>
  ...
</form>

4. Exemple complet avec Inertia

<RecaptchaProvider>
  <RecaptchaForm
    data={formData}
    onSubmit={(e) => post(route("contact.submit"), { data: formData })}
  >
    <input name="email" value={formData.email} onChange={e => setFormData("email", e.target.value)} />
    <textarea name="message" value={formData.message} onChange={e => setFormData("message", e.target.value)} />
    <button type="submit">Envoyer</button>
  </RecaptchaForm>
</RecaptchaProvider>

• Le formulaire est désactivé automatiquement si l’utilisateur n’a pas accepté le reCAPTCHA.
• Le token reCAPTCHA est injecté automatiquement au moment du submit.
• La logique de cookie consent est gérée sans code supplémentaire.

5. RecaptchaForm : comment ça fonctionne

Le composant RecaptchaForm est un wrapper de formulaire qui gère le reCAPTCHA et l’état inert.

• onSubmit : callback déclenché lorsque le formulaire est soumis et que le reCAPTCHA est actif.
• data : objet contenant les données du formulaire, incluant g-recaptcha-response.
• children : champs du formulaire.
• banner : optionnel, permet d’afficher un message si le reCAPTCHA n’est pas encore activé.

Fonctionnalités clés

• Inert automatiquement : le formulaire est bloqué tant que le consentement n’est pas donné.
• Token automatique : le token reCAPTCHA est récupéré et injecté dans data["g-recaptcha-response"].
• Notification de cookie : un banner s’affiche pour informer l’utilisateur et lui permettre d’accepter le service.

6. Avantages du RecaptchaProvider

• Séparation claire des responsabilités : le provider gère uniquement l’état du reCAPTCHA et des cookies.
• Réutilisable : peut encapsuler plusieurs formulaires ou pages sans dupliquer le code.
• Sécurité : empêche toute soumission tant que le consentement n’est pas donné.
• Intégration simple avec Inertia.js : compatible avec useForm() et usePage().
• Flexible : expose formRef pour un contrôle direct du <form>.

7. Bonnes pratiques

• Toujours placer les formulaires à l’intérieur du RecaptchaProvider.
• Ne pas appeler getToken() en dehors du submit pour éviter des tokens invalides.
• Utiliser le champ data-recaptcha-key sur le <form> pour que InitRecaptcha puisse initialiser correctement le reCAPTCHA.