OW Forms — Documentation

Un constructeur de formulaires moderne et RGPD-natif pour WordPress. Auteur : OptionWeb — Julien Daniel Page du plugin : https://optionweb.dev/fr/addons/ow-forms/ Licence : GPL-2.0-or-later Version couverte par ce document : 1.0.2

---

Table des matières

1. Vue d'ensemble
2. Installation
3. Démarrage rapide — votre premier formulaire
4. Types de champs
5. Pile anti-spam
6. Fonctionnalités RGPD
7. Notifications email
8. Webhooks
9. Téléversement de fichiers
10. Rendu : shortcode, Gutenberg, REST
11. Importateur Contact Form 7
12. Référence des réglages
13. API REST
14. Hooks développeur (filters & actions)
15. Intégration avec OW Consent / OW Shield
16. Internationalisation
17. Dépannage
18. FAQ

---

Vue d'ensemble

OW Forms est un constructeur de formulaires piloté par schéma. Chaque formulaire est un document JSON qui décrit ses champs, sa validation et son comportement à la soumission. Le plugin rend ce schéma sous forme de HTML accessible, valide les soumissions côté serveur, les fait passer par une pile anti-spam à quatre couches, persiste ce que vous l'autorisez à persister, et déclenche les notifications email + webhook.

Ce qui est livré (tout est gratuit, GPL-2) :

• Moteur de schéma JSON avec 17 types de champs
• Pile anti-spam à 4 couches : honeypot, time-trap, CAPTCHA multi-fournisseur, réputation IP
• Consentement RGPD natif + rétention + DSAR
• API REST (namespace owf/v1) — submit public + CRUD admin
• Bloc Gutenberg + shortcode + API de rendu PHP
• Webhooks sortants signés HMAC
• Importateur Contact Form 7 en un clic
• Détecte automatiquement les tokens du thème OW Canvas pour une cohérence visuelle

Ce qu'il ne fait PAS, délibérément :

• Traitement des paiements (utilisez WooCommerce + un checkout dédié)
• Assistants multi-pages au-delà du simple suivant/précédent (utilisez un plugin d'assistant dédié)
• Constructeur visuel drag-and-drop en v1 (éditeur JSON uniquement ; constructeur visuel prévu sur la roadmap)

---

Installation

Depuis WordPress.org (recommandé)

1. Admin WordPress → Extensions → Ajouter
2. Recherchez OW Forms
3. Cliquez sur Installer, puis sur Activer

Depuis un .zip

1. Téléchargez ow-forms-1.0.2.zip depuis https://optionweb.dev/fr/addons/ow-forms/
2. Extensions → Ajouter → Téléverser une extension
3. Choisissez le fichier, cliquez sur Installer, puis sur Activer

Prérequis

• WordPress 6.0 ou plus récent
• PHP 7.4 ou plus récent (8.1+ recommandé)
• MySQL/MariaDB avec support de la colonne JSON (5.7+ / 10.2+)

Ce qui est installé

À l'activation, OW Forms crée trois tables personnalisées :

• {prefix}_owf_submissions — payloads de soumissions + métadonnées spam
• {prefix}_owf_files — registre des fichiers téléversés
• {prefix}_owf_log — journal d'audit des soumissions

Plus un Custom Post Type owf_form (non interrogeable publiquement) utilisé pour stocker les schémas de formulaires.

---

Démarrage rapide

Après activation, un formulaire « Contact » par défaut est créé automatiquement.

1. Allez dans OW Forms → Formulaires dans l'admin
2. Notez l'ID du formulaire par défaut (ex. 1)
3. Dans n'importe quelle page ou article, insérez le shortcode :

[owf_form id="1"]

…ou insérez le bloc Gutenberg OW Forms et choisissez le formulaire dans la liste déroulante.

C'est tout. Le formulaire s'affiche, accepte les soumissions, envoie un email admin à admin_email, et enregistre la soumission en base de données.

Pour le personnaliser, ouvrez le formulaire dans OW Forms → Formulaires → [Éditer] et modifiez directement le schéma JSON. Un constructeur visuel est prévu sur la roadmap v1.1.

---

Types de champs

OW Forms prend en charge 17 types de champs. Chaque champ du schéma est un objet avec au minimum type et name ; la plupart acceptent aussi label, help, required, placeholder, et des options spécifiques au type.

Exemple de schéma

{
  "title": "Contact us",
  "fields": [
    {
      "type": "text",
      "name": "name",
      "label": "Your name",
      "required": true,
      "placeholder": "Jane Doe"
    },
    {
      "type": "email",
      "name": "email",
      "label": "Email",
      "required": true
    },
    {
      "type": "select",
      "name": "subject",
      "label": "How can we help?",
      "required": true,
      "options": [
        {"value": "quote",   "label": "Request a quote"},
        {"value": "support", "label": "Technical support"},
        {"value": "other",   "label": "Other"}
      ]
    },
    {
      "type": "textarea",
      "name": "message",
      "label": "Message",
      "required": true,
      "rows": 6
    }
  ],
  "submit": {
    "label": "Send",
    "success_message": "Thanks — we will reply within 24 hours.",
    "redirect_url": ""
  }
}

Les valeurs name des champs deviennent les clés du payload stocké et les tokens utilisables dans les templates d'email ({{name}}, {{email}}, etc.).

---

Pile anti-spam

OW Forms exécute quatre couches indépendantes en parallèle. Chaque couche attribue une contribution au score ; une soumission obtenant ≥ 80 est silencieusement rejetée — aucun message d'erreur n'est retourné, afin que les bots ne puissent pas itérer contre la protection.

1. Honeypot

Un champ texte caché visuellement que les bots remplissent et que les humains ne voient pas. Réglage :

• spam_honeypot_enabled (défaut : true)

2. Time-trap

Rejette les soumissions effectuées plus vite qu'un seuil configurable (les bots typiques font le POST instantanément).

• spam_timetrap_enabled (défaut : true)
• spam_timetrap_min_seconds (défaut : 2)

3. CAPTCHA (multi-fournisseur)

Validation server-to-server du token contre l'API du fournisseur. Choisissez parmi :

• turnstile — Cloudflare Turnstile (recommandé, respectueux de la vie privée, sans UX de challenge)
• recaptcha_v3 — Google reCAPTCHA v3 (invisible)
• hcaptcha — hCaptcha (widget visible)
• friendly_captcha — Friendly Captcha (widget self-hosted, licence MIT, EU-friendly)

Réglez spam_captcha_provider, spam_captcha_site_key, et spam_captcha_secret_key dans l'onglet Anti-spam des réglages. Le défaut est none.

Note : Le JS des widgets Turnstile / reCAPTCHA / hCaptcha est chargé depuis l'origine du fournisseur (leur JS effectue une vérification de signature d'origine côté serveur). Friendly Captcha est self-hosted sous assets/js/vendor/.

4. Réputation IP (optionnel)

Quand OW Shield est installé et actif, OW Forms utilise son flux de réputation IP pour scorer les soumissions :

• spam_owshield_iprep (défaut : true)
• spam_block_disposable_emails (défaut : true) — rejette @mailinator, @tempmail, et environ 120 autres domaines jetables

Heuristiques supplémentaires

• spam_min_words_per_text_area — exige au moins N mots dans les textareas
• spam_max_links_per_submission — rejette si plus de N URLs dans le payload
• spam_blocklist_emails, spam_blocklist_words, spam_blocklist_ips — vos propres listes

Journalisation

Chaque décision spam est journalisée avec sa raison. Consultez OW Forms → Soumissions → filtre « spam » pour ajuster les seuils sans naviguer à l'aveugle.

---

Fonctionnalités RGPD

La conformité RGPD est native. Les défauts sont conservateurs ; ne les assouplissez que si vous avez un conseil juridique en ce sens.

Case de consentement

Une case de consentement est auto-injectée en bas de chaque formulaire quand gdpr_consent_required vaut true (défaut). Le texte est configurable :

'gdpr_consent_text' => __(
    'I agree that my data will be processed to respond to my inquiry, in accordance with the privacy policy.',
    'ow-forms'
)

Si gdpr_auto_link_privacy est actif (défaut), les mots « privacy policy » / « politique de confidentialité » sont auto-liés à l'URL de politique de confidentialité OW Consent quand ce plugin est actif, ou à votre Page de Confidentialité WP configurée sinon.

Modes de stockage IP

Réglage store_ip :

Stockage de l'user agent

Réglage store_user_agent :

Rétention & purge

Un cron quotidien purge les soumissions plus anciennes que gdpr_retention_days (défaut : 1095 jours — le standard CNIL pour les données prospects). Mettez à 0 pour désactiver la purge automatique.

Si gdpr_auto_delete_after_response vaut true, marquer une soumission comme « traitée » la supprime immédiatement avec tous les fichiers téléversés associés.

DSAR — Accès / Effacement des données

Les emails de formulaire sont hashés avec wp_salt() au moment du stockage. Quand OW Consent est actif et qu'un effacement DSAR est traité pour une adresse email, OW Forms supprime automatiquement les soumissions correspondantes par email_hash et déclenche :

do_action( 'owf_gdpr_erased_for_email', $hash, $count );

Sans OW Consent, vous pouvez appeler l'effacement manuellement :

OWF_GDPR::erase_by_email( 'user@example.com' );  // returns int count

---

Notifications email

Templates

La notification admin et l'auto-réponse utilisateur supportent toutes deux la substitution {{token}} :

Réglages

Surcharge par formulaire

Le schéma de formulaire peut surcharger les globaux :

{
  "mail": {
    "recipient": "sales@example.com",
    "subject": "New lead — {{name}}",
    "body": "Lead: {{name}}\\nEmail: {{email}}\\nMessage: {{message}}",
    "autoreply": true,
    "autoreply_subject": "Thanks, {{name}}!",
    "autoreply_body": "Hi {{name}},\\n\\nWe got your message."
  }
}

---

Webhooks

Quand webhook_url est défini, chaque soumission réussie déclenche un POST HTTP.

Payload (JSON)

{
  "form_id": 1,
  "form_title": "Contact",
  "submission_id": 42,
  "received_at": "2026-05-13T14:32:18+00:00",
  "fields": { "name": "Jane", "email": "jane@example.com", "message": "Hi" },
  "site": "https://example.com"
}

Signature HMAC

Si webhook_secret est défini, la requête inclut :

X-OWF-Signature: sha256=<hex digest of HMAC-SHA256(body, secret)>

Vérification côté récepteur (exemple Node) :

const expected = crypto
  .createHmac('sha256', SECRET)
  .update(rawBody)
  .digest('hex');
const provided = req.headers['x-owf-signature'].replace(/^sha256=/, '');
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(provided))) {
  return res.status(401).end('bad sig');
}

Retries

Si le récepteur retourne 5xx ou time-out, OW Forms ré-essaie avec un backoff exponentiel (60 s → 5 min → 30 min). Après 3 échecs, le webhook est journalisé comme définitivement échoué mais ne bloque pas la soumission.

---

Téléversement de fichiers

Quand allow_file_uploads est actif (défaut true), tout champ de type file est accepté. Le pipeline :

1. Validation côté serveur — taille de fichier (max_file_size_mb, défaut 8 MB), liste blanche d'extensions (allowed_file_types), et un contrôle MIME finfo recoupé avec wp_get_mime_types().
2. Stockage — wp-content/uploads/owf-uploads/YYYY/MM/<sha256>.<ext> avec un .htaccess deny-all (Apache) et index.php vide (Nginx/IIS).
3. Registre en base — métadonnées du fichier + hash SHA-256 dans {prefix}_owf_files, lié à l'ID de la soumission parente.
4. Nettoyage — quand une soumission est supprimée (manuellement, par rétention, ou par DSAR), tous les fichiers liés sont effacés.

Important : OW Forms utilise un chemin d'upload isolé personnalisé, pas la médiathèque WordPress. Les fichiers téléversés ne sont donc pas découvrables via l'endpoint standard /wp-json/wp/v2/media et aucune miniature n'est générée. C'est délibéré — les pièces jointes de formulaire sont privées au propriétaire du formulaire.

Types de fichiers autorisés (défaut)

pdf, jpg, jpeg, png, webp, doc, docx, xls, xlsx, csv, txt

Pour étendre :

add_filter( 'owf_settings', function( $s ) {
    $s['allowed_file_types'] = array_merge(
        (array) $s['allowed_file_types'],
        array( 'odt', 'ods', 'zip' )
    );
    return $s;
} );

---

Rendu

Shortcode

[owf_form id="42"]
[owf_form slug="contact"]

id (ID numérique du post) ou slug (slug du post) — un des deux est requis.

Bloc Gutenberg

Dans l'éditeur de blocs, cherchez « OW Forms » dans l'inserteur et choisissez votre formulaire dans la liste déroulante.

PHP

echo OWF_Form::render( 42 );
// or
echo do_shortcode( '[owf_form id="42"]' );

REST

Le formulaire peut aussi être soumis par programmation — voir API REST.

---

Importateur CF7

Si Contact Form 7 est ou était installé, OW Forms est livré avec un importateur en un clic.

OW Forms → Outils → Importer depuis Contact Form 7

L'importateur :

1. Scanne chaque post wpcf7_contact_form de votre base
2. Analyse chaque formulaire CF7 basé sur shortcode et construit le schéma OW Forms équivalent
3. Préserve destinataire, sujet, messages de succès/erreur, et types de champs
4. Réécrit chaque shortcode [contact-form-7 id="..."] dans tout votre post_content (pages, articles, custom post types) en [owf_form id="..."]
5. Journalise les résultats : formulaires trouvés, importés, ignorés (déjà importés)

Le plugin CF7 peut alors être désactivé et supprimé.

L'importateur est idempotent : l'exécuter deux fois ne crée pas de doublons. Les formulaires CF7 déjà importés sont marqués via une meta key _owf_imported_from_cf7 et ignorés lors des exécutions suivantes.

---

Référence des réglages

Tous les réglages sont stockés dans une seule clé d'option, owf_settings. Vous pouvez les lire ou les surcharger par programmation :

$value = OWF_Core::setting( 'spam_timetrap_min_seconds' );
OWF_Core::update_settings( array( 'spam_timetrap_min_seconds' => 3 ) );

Défauts complets

array(
    // General
    'default_recipient_email'        => '',     // empty = admin_email
    'from_name'                      => '',
    'from_email'                     => '',
    'sender_uses_dpo'                => true,

    // Anti-spam
    'spam_honeypot_enabled'          => true,
    'spam_timetrap_enabled'          => true,
    'spam_timetrap_min_seconds'      => 2,
    'spam_captcha_provider'          => 'none',
    'spam_captcha_site_key'          => '',
    'spam_captcha_secret_key'        => '',
    'spam_owshield_iprep'            => true,
    'spam_block_disposable_emails'   => true,
    'spam_min_words_per_text_area'   => 0,
    'spam_max_links_per_submission'  => 3,
    'spam_blocklist_emails'          => array(),
    'spam_blocklist_words'           => array(),
    'spam_blocklist_ips'             => array(),

    // GDPR
    'gdpr_consent_required'          => true,
    'gdpr_consent_text'              => '...',
    'gdpr_auto_link_privacy'         => true,
    'gdpr_retention_days'            => 1095,
    'gdpr_auto_delete_after_response' => false,

    // Storage
    'store_submissions'              => true,
    'store_ip'                       => 'pseudonymized',
    'store_user_agent'               => 'hashed',
    'allow_file_uploads'             => true,
    'max_file_size_mb'               => 8,
    'allowed_file_types'             => array( 'pdf', 'jpg', 'jpeg', 'png',
                                                'webp', 'doc', 'docx', 'xls',
                                                'xlsx', 'csv', 'txt' ),

    // Notifications
    'mail_html'                      => true,
    'mail_admin_subject'             => '[{{site_name}}] New message via {{form_title}}',
    'mail_admin_body'                => '',
    'mail_user_autoreply_enabled'    => true,
    'mail_user_subject'              => 'We have received your message',
    'mail_user_body'                 => '',
    'mail_failed_alert_email'        => '',
    'webhook_url'                    => '',
    'webhook_secret'                 => '',

    // Rendering
    'style_preset'                   => 'auto',
    'button_label_default'           => 'Send',
    'success_message_default'        => 'Your message has been sent. We will reply within 24 hours.',
    'error_message_default'          => 'An error occurred. Please try again or contact us directly.',
    'inherit_theme_tokens'           => true,

    // Analytics (opt-in)
    'track_conversions'              => false,
    'conversion_event_name'          => 'generate_lead',
    'conversion_value'               => 0,
    'conversion_currency'            => 'EUR',
);

---

API REST

Tous les endpoints vivent sous le namespace owf/v1.

Endpoint public

Body :

{
  "form_id": 1,
  "fields": { "name": "Jane", "email": "jane@example.com", "message": "Hi" },
  "_owf_nonce": "<from wp_create_nonce('owf_submit_form')>",
  "_owf_time": 1736780000,
  "_owf_hp": ""
}

Réponse (200) :

{ "ok": true, "id": 42, "message": "Your message has been sent." }

Réponse (422) quand la validation échoue :

{
  "ok": false,
  "errors": { "email": "Please enter a valid email" },
  "message": "Please review the fields in error."
}

Endpoints admin (requièrent manage_options)

Tous les endpoints admin requièrent à la fois la capability manage_options et un nonce REST WP valide.

---

Hooks (filters & actions)

Actions

/**
 * Fires after a submission has been processed and stored.
 *
 * @param int   $submission_id  Database ID (0 if not stored)
 * @param int   $form_id        Form ID
 * @param array $cleaned        Sanitized field payload
 * @param array $schema         Full form schema
 */
do_action( 'owf_submission_received', $submission_id, $form_id, $cleaned, $schema );

/**
 * Fires after a DSAR erasure has deleted matching submissions by email hash.
 *
 * @param string $email_hash   SHA-256(email + wp_salt())
 * @param int    $deleted_count
 */
do_action( 'owf_gdpr_erased_for_email', $email_hash, $deleted_count );

Filters

/**
 * Filter the resolved settings array (merged defaults + saved + per-request).
 */
apply_filters( 'owf_settings', array $settings );

/**
 * Whitelist of trusted reverse proxy IPs that may set X-Forwarded-For.
 * Without this OW Forms ignores proxy headers (to prevent IP spoofing).
 */
apply_filters( 'owf_trusted_proxies', array $proxies );

/**
 * List of disposable email domains rejected when `spam_block_disposable_emails`
 * is on.
 */
apply_filters( 'owf_disposable_domains', array $domains );

Pattern recommandé — étendre la liste des domaines jetables

add_filter( 'owf_disposable_domains', function( $list ) {
    return array_merge( $list, array(
        'example-throwaway.com',
        'company-blocked-domain.net',
    ) );
} );

Pattern recommandé — pousser les soumissions vers un CRM

add_action( 'owf_submission_received', function( $sid, $form_id, $cleaned ) {
    if ( $form_id !== 7 ) return;  // only the "Sales" form
    wp_remote_post( 'https://crm.example.com/leads', array(
        'headers' => array( 'Authorization' => 'Bearer ' . CRM_TOKEN ),
        'body'    => wp_json_encode( array(
            'email'   => $cleaned['email'],
            'name'    => $cleaned['name'],
            'message' => $cleaned['message'],
            'source'  => 'website-form',
        ) ),
        'headers' => array( 'Content-Type' => 'application/json' ),
    ) );
}, 10, 3 );

---

Intégrations

OW Canvas (thème)

Quand le thème OW Canvas est actif, OW Forms hérite de ses propriétés CSS personnalisées (--owc-ink, --owc-paper, --owc-accent, etc.) pour une cohérence visuelle. Désactivez avec inherit_theme_tokens = false.

OW Consent

Quand OW Consent est actif :

• Le lien de la case de consentement RGPD pointe automatiquement sur l'URL de politique de confidentialité d'OW Consent
• Les soumissions sont liées aux enregistrements OW Consent (quand le visiteur a un cookie d'ID de consentement)
• Les flux d'effacement DSAR depuis OW Consent purgent automatiquement les soumissions OW Forms pour le même hash d'email

OW Shield

Quand OW Shield est actif et spam_owshield_iprep activé, l'IP de chaque soumission est scorée contre le flux de réputation d'OW Shield avant d'être acceptée.

---

Internationalisation

La langue source est l'anglais. Une traduction française est livrée sous languages/ow-forms-fr_FR.po.

Pour les traducteurs

Le template .pot est dans languages/ow-forms.pot. Soumettez vos traductions via translate.wordpress.org/projects/wp-plugins/ow-forms une fois le plugin approuvé sur WP.org. Pour une distribution locale, déposez ow-forms-<locale>.mo dans le dossier languages/.

Compiler le .mo localement

msgfmt languages/ow-forms-fr_FR.po -o languages/ow-forms-fr_FR.mo

---

Dépannage

Le formulaire est soumis mais aucun email n'arrive

1. Vérifiez que votre site peut envoyer du mail tout court — essayez un test depuis le formulaire de contact d'un autre plugin ou avec Mail Tester
2. Vérifiez OW Forms → Soumissions pour confirmer que la soumission est bien arrivée (si oui, le problème est la délivrabilité, pas OW Forms)
3. Configurez mail_failed_alert_email avec votre propre adresse — OW Forms vous enverra un email quand wp_mail() retournera false
4. Installez un plugin SMTP (Fluent SMTP, WP Mail SMTP, etc.) — la fonction mail() PHP par défaut est rejetée par 95 % des serveurs de réception

Le CAPTCHA ne s'affiche pas

• Vérifiez que spam_captcha_site_key et spam_captcha_secret_key sont bien tous deux définis
• Ouvrez la page dans les DevTools — l'URL du script du fournisseur doit charger avec un 200
• Pour reCAPTCHA, le domaine de votre site doit être enregistré dans l'admin Google
• Pour Turnstile, le mode widget dans l'admin Cloudflare doit être « Managed » ou « Non-interactive »

Les fichiers sont uploadés mais l'admin ne peut pas les télécharger

C'est voulu — les fichiers téléversés sont servis par un handler PHP authentifié, pas directement. Vérifiez que vous êtes connecté en tant qu'utilisateur avec manage_options.

L'importateur CF7 dit « 0 formulaire trouvé »

L'importateur scanne le post type wpcf7_contact_form. Si CF7 est déjà désactivé et les posts supprimés, il n'y a plus rien à importer. Réactivez CF7 juste pour l'import, puis désactivez à nouveau.

La table des soumissions est énorme

• Réduisez gdpr_retention_days (défaut 1095 / 3 ans)
• Désactivez store_submissions si vous n'avez besoin que de la délivrance email, pas d'un journal d'audit en base
• Mettez gdpr_auto_delete_after_response = true pour supprimer sur « traitée »

---

FAQ

OW Forms est-il gratuit ? Oui. GPL-2.0-or-later. Il n'y a pas de version Pro, pas de clé de licence, aucune fonctionnalité verrouillée derrière un paiement.

Fonctionne-t-il sur WordPress Multisite ? Oui — chaque site a ses propres tables et sa propre bibliothèque de formulaires, isolée comme attendu.

Supporte-t-il les formulaires multi-étapes ? Une navigation suivant/précédent basique fonctionne via le regroupement de champs dans le schéma. Une UX d'assistant de première classe est prévue sur la roadmap v1.1.

Comment exporter les soumissions ? OW Forms → Soumissions → Exporter CSV. L'export respecte les filtres courants (formulaire, plage de dates, statut).

Puis-je héberger mes formulaires derrière un paywall ou un login ? Oui — encapsulez le shortcode dans la logique de gating d'un plugin de membership, ou rendez via PHP à l'intérieur d'un test is_user_logged_in().

S'intègre-t-il avec les outils d'email marketing / CRM ? Out of the box : webhooks (POST signé HMAC vers n'importe quel endpoint), et destinataires email par formulaire. Pour Brevo / Mailchimp / HubSpot / Pipedrive, branchez-vous sur owf_submission_received et appelez l'API REST du fournisseur — voir la section Hooks.

Le plugin est-il certifié RGPD ? Les défauts du plugin sont alignés sur les bonnes pratiques CNIL / RGPD, mais la certification est un processus juridique spécifique à votre configuration de responsable de traitement. Nous fournissons l'outillage technique ; votre DPO valide la politique.

Où trouver le support ?

• Portail de support : https://optionweb.dev/fr/addons/support/
• Email : support@optionweb.dev
• Documentation : https://optionweb.dev/fr/addons/ow-forms/

---

Conçu par OptionWeb — Julien Daniel, Châtelet, Belgique.