OW Forms — Documentazione

Un costruttore di form moderno e GDPR-nativo per WordPress. Autore: OptionWeb — Julien Daniel Pagina del plugin: https://optionweb.dev/it/addons/ow-forms/ Licenza: GPL-2.0-or-later Versione coperta da questo documento: 1.0.2

---

Indice

1. Panoramica
2. Installazione
3. Avvio rapido — il tuo primo form
4. Tipi di campo
5. Stack anti-spam
6. Funzionalità GDPR
7. Notifiche email
8. Webhook
9. Caricamento file
10. Rendering: shortcode, Gutenberg, REST
11. Importatore Contact Form 7
12. Riferimento impostazioni
13. REST API
14. Hook per sviluppatori (filters & actions)
15. Integrazione con OW Consent / OW Shield
16. Internazionalizzazione
17. Risoluzione problemi
18. FAQ

---

Panoramica

OW Forms è un costruttore di form guidato da schema. Ogni form è un documento JSON che descrive i suoi campi, la validazione e il comportamento di invio. Il plugin renderizza quello schema come HTML accessibile, valida gli invii lato server, li fa passare attraverso uno stack anti-spam a quattro livelli, persiste ciò che gli permetti di persistere, e attiva notifiche email + webhook.

Cosa è incluso (tutto gratis, GPL-2):

• Motore di schema JSON con 17 tipi di campo
• Anti-spam a 4 livelli: honeypot, time-trap, CAPTCHA multi-fornitore, reputazione IP
• Consenso GDPR nativo + retention + DSAR
• REST API (namespace owf/v1) — submit pubblico + CRUD admin
• Blocco Gutenberg + shortcode + API di rendering PHP
• Webhook in uscita firmati con HMAC
• Importatore Contact Form 7 a un clic
• Rileva automaticamente i token del tema OW Canvas per coerenza visiva

Cosa NON fa, deliberatamente:

• Elaborazione pagamenti (usa WooCommerce + un checkout dedicato)
• Wizard multi-pagina oltre il semplice avanti/indietro (usa un plugin wizard dedicato)
• Costruttore visuale drag-and-drop in v1 (solo editor JSON; costruttore visuale in roadmap)

---

Installazione

Da WordPress.org (consigliato)

1. Admin WordPress → Plugin → Aggiungi nuovo
2. Cerca OW Forms
3. Clicca Installa ora, poi Attiva

Da upload .zip

1. Scarica ow-forms-1.0.2.zip da https://optionweb.dev/it/addons/ow-forms/
2. Plugin → Aggiungi nuovo → Carica plugin
3. Scegli il file, clicca Installa ora, poi Attiva

Requisiti

• WordPress 6.0 o successivo
• PHP 7.4 o successivo (8.1+ consigliato)
• MySQL/MariaDB con supporto colonna JSON (5.7+ / 10.2+)

Cosa viene installato

All'attivazione, OW Forms crea tre tabelle personalizzate:

• {prefix}_owf_submissions — payload degli invii + metadati spam
• {prefix}_owf_files — registro dei file caricati
• {prefix}_owf_log — audit trail degli invii

Più un Custom Post Type owf_form (non interrogabile pubblicamente) usato per archiviare gli schemi dei form.

---

Avvio rapido

Dopo l'attivazione viene creato automaticamente un form "Contatto" predefinito.

1. Vai su OW Forms → Form nell'admin
2. Annota l'ID del form predefinito (es. 1)
3. In qualsiasi pagina o articolo, inserisci lo shortcode:

[owf_form id="1"]

…o inserisci il blocco Gutenberg OW Forms e scegli il form dal menu a tendina.

Tutto qui. Il form viene renderizzato, accetta invii, invia un'email admin a admin_email e memorizza l'invio nel database.

Per personalizzarlo, apri il form in OW Forms → Form → [Modifica] e modifica direttamente lo schema JSON. Un costruttore visuale è in roadmap per la v1.1.

---

Tipi di campo

OW Forms supporta 17 tipi di campo. Ogni campo nello schema è un oggetto con almeno type e name; la maggior parte accetta anche label, help, required, placeholder e opzioni specifiche per tipo.

Esempio di schema

{
  "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": ""
  }
}

I valori name dei campi diventano chiavi nel payload memorizzato e token utilizzabili nei template email ({{name}}, {{email}}, ecc.).

---

Stack anti-spam

OW Forms esegue quattro livelli indipendenti in parallelo. Ogni livello assegna un contributo allo score; un invio con score ≥ 80 viene scartato silenziosamente — nessun messaggio d'errore viene restituito, in modo che i bot non possano iterare contro la protezione.

1. Honeypot

Un campo di testo nascosto visivamente che i bot riempiono e gli umani no. Impostazione:

• spam_honeypot_enabled (predefinito: true)

2. Time-trap

Rifiuta gli invii completati più velocemente di una soglia configurabile (i bot tipici fanno il POST istantaneamente).

• spam_timetrap_enabled (predefinito: true)
• spam_timetrap_min_seconds (predefinito: 2)

3. CAPTCHA (multi-fornitore)

Validazione server-to-server del token contro l'API del fornitore. Scegline uno tra:

• turnstile — Cloudflare Turnstile (consigliato, privacy-first, senza UX di challenge)
• recaptcha_v3 — Google reCAPTCHA v3 (invisibile)
• hcaptcha — hCaptcha (widget visibile)
• friendly_captcha — Friendly Captcha (widget self-hosted, licenza MIT, EU-friendly)

Imposta spam_captcha_provider, spam_captcha_site_key e spam_captcha_secret_key nel tab impostazioni Anti-spam. Il predefinito è none.

Nota: il JS dei widget Turnstile / reCAPTCHA / hCaptcha viene caricato dall'origine del fornitore (il loro JS esegue un controllo di firma di origine lato server). Friendly Captcha è self-hosted sotto assets/js/vendor/.

4. Reputazione IP (opzionale)

Quando OW Shield è installato e attivo, OW Forms usa il suo feed di reputazione IP per assegnare uno score agli invii:

• spam_owshield_iprep (predefinito: true)
• spam_block_disposable_emails (predefinito: true) — rifiuta @mailinator, @tempmail e circa 120 altri domini usa-e-getta

Euristiche aggiuntive

• spam_min_words_per_text_area — richiede almeno N parole nelle textarea
• spam_max_links_per_submission — rifiuta se ci sono più di N URL nel payload
• spam_blocklist_emails, spam_blocklist_words, spam_blocklist_ips — le tue liste

Logging

Ogni decisione di spam viene loggata con la sua motivazione. Controlla OW Forms → Invii → filtro "spam" per regolare le soglie senza navigare alla cieca.

---

Funzionalità GDPR

La conformità GDPR è nativa. I valori predefiniti sono conservativi; allentali solo se hai una consulenza legale in tal senso.

Casella di consenso

Una casella di consenso viene auto-iniettata in fondo a ogni form quando gdpr_consent_required è true (predefinito). Il testo è configurabile:

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

Se gdpr_auto_link_privacy è attivo (predefinito), le parole "privacy policy" / "informativa sulla privacy" vengono auto-collegate all'URL dell'informativa di OW Consent quando quel plugin è attivo, o alla tua Pagina Privacy configurata in WP altrimenti.

Modalità di memorizzazione IP

Impostazione store_ip:

Memorizzazione user agent

Impostazione store_user_agent:

Retention & purge

Un cron giornaliero purga gli invii più vecchi di gdpr_retention_days (predefinito: 1095 giorni — lo standard CNIL per i dati dei prospect). Imposta a 0 per disabilitare la purga automatica.

Se gdpr_auto_delete_after_response è true, contrassegnare un invio come "gestito" lo elimina immediatamente insieme a tutti i file caricati.

DSAR — Accesso / cancellazione dell'interessato

Le email dei form vengono hashate con wp_salt() al momento della memorizzazione. Quando OW Consent è attivo e una cancellazione DSAR viene elaborata per un indirizzo email, OW Forms elimina automaticamente gli invii corrispondenti per email_hash e attiva:

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

Senza OW Consent, puoi invocare la cancellazione manualmente:

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

---

Notifiche email

Template

Sia la notifica admin sia la risposta automatica utente supportano la sostituzione {{token}}:

Impostazioni

Override per form

Lo schema del form può sovrascrivere i globali:

{
  "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."
  }
}

---

Webhook

Quando webhook_url è impostato, ogni invio riuscito attiva 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"
}

Firma HMAC

Se webhook_secret è impostato, la richiesta include:

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

Verifica lato ricevente (esempio 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');
}

Retry

Se il ricevente restituisce 5xx o va in timeout, OW Forms ritenta con backoff esponenziale (60 s → 5 min → 30 min). Dopo 3 fallimenti il webhook viene loggato come definitivamente fallito ma non blocca l'invio.

---

Caricamento file

Quando allow_file_uploads è attivo (predefinito true), qualsiasi campo di tipo file viene accettato. La pipeline:

1. Validazione lato server — dimensione file (max_file_size_mb, predefinito 8 MB), allowlist di estensioni (allowed_file_types) e un controllo MIME finfo incrociato con wp_get_mime_types().
2. Memorizzazione — wp-content/uploads/owf-uploads/YYYY/MM/<sha256>.<ext> con un .htaccess deny-all (Apache) e index.php vuoto (Nginx/IIS).
3. Registro DB — metadati del file + hash SHA-256 in {prefix}_owf_files, collegato all'ID dell'invio padre.
4. Pulizia — quando un invio viene eliminato (manualmente, per retention o per DSAR), tutti i file collegati vengono rimossi.

Importante: OW Forms usa un percorso di upload isolato personalizzato, non la libreria media di WordPress, quindi i file caricati non sono individuabili tramite l'endpoint standard /wp-json/wp/v2/media e non vengono generate miniature. È deliberato — gli allegati dei form sono privati al proprietario del form.

Tipi di file consentiti (predefinito)

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

Per estendere:

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

---

Rendering

Shortcode

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

id (ID numerico del post) o slug (slug del post) — uno è obbligatorio.

Blocco Gutenberg

Nell'editor a blocchi, cerca "OW Forms" nell'inseritore e scegli il tuo form dal menu a tendina.

PHP

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

REST

Il form può anche essere inviato programmaticamente — vedi REST API.

---

Importatore CF7

Se Contact Form 7 è o era installato, OW Forms include un importatore a un clic.

OW Forms → Strumenti → Importa da Contact Form 7

L'importatore:

1. Scansiona ogni post wpcf7_contact_form nel tuo database
2. Analizza ogni form CF7 basato su shortcode e costruisce lo schema OW Forms equivalente
3. Conserva destinatario, oggetto, messaggi di successo/errore e tipi di campo
4. Riscrive ogni shortcode [contact-form-7 id="..."] in tutto il tuo post_content (pagine, articoli, custom post type) in [owf_form id="..."]
5. Logga i risultati: form trovati, importati, saltati (già importati)

Il plugin CF7 può quindi essere disattivato e rimosso.

L'importatore è idempotente: eseguirlo due volte non crea duplicati. I form CF7 già importati sono contrassegnati tramite una meta key _owf_imported_from_cf7 e saltati nelle esecuzioni successive.

---

Riferimento impostazioni

Tutte le impostazioni sono memorizzate in una singola chiave di opzione, owf_settings. Puoi leggerle o sovrascriverle programmaticamente:

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

Valori predefiniti completi

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',
);

---

REST API

Tutti gli endpoint vivono sotto il namespace owf/v1.

Endpoint pubblico

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": ""
}

Risposta (200):

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

Risposta (422) quando la validazione fallisce:

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

Endpoint admin (richiedono manage_options)

Tutti gli endpoint admin richiedono sia la capability manage_options sia un nonce REST WP valido.

---

Hook (filters & actions)

Action

/**
 * 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 );

Filter

/**
 * 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 consigliato — estendere la lista dei domini usa-e-getta

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

Pattern consigliato — inviare gli invii a 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 );

---

Integrazioni

OW Canvas (tema)

Quando il tema OW Canvas è attivo, OW Forms eredita le sue proprietà CSS personalizzate (--owc-ink, --owc-paper, --owc-accent, ecc.) per coerenza visiva. Disabilita con inherit_theme_tokens = false.

OW Consent

Quando OW Consent è attivo:

• Il link della casella di consenso GDPR punta automaticamente all'URL dell'informativa privacy di OW Consent
• Gli invii sono collegati ai record OW Consent (quando il visitatore ha un cookie di ID consenso)
• I flussi di cancellazione DSAR da OW Consent purgano automaticamente gli invii OW Forms per lo stesso hash email

OW Shield

Quando OW Shield è attivo e spam_owshield_iprep è attivo, l'IP di ogni invio viene valutato contro il feed di reputazione di OW Shield prima di essere accettato.

---

Internazionalizzazione

La lingua sorgente è l'inglese. Una traduzione francese è inclusa sotto languages/ow-forms-fr_FR.po.

Per i traduttori

Il template .pot si trova in languages/ow-forms.pot. Invia le traduzioni tramite translate.wordpress.org/projects/wp-plugins/ow-forms una volta che il plugin è approvato su WP.org. Per la distribuzione locale, posiziona ow-forms-<locale>.mo nella cartella languages/.

Compilare il .mo localmente

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

---

Risoluzione problemi

Il form viene inviato ma non arriva nessuna email

1. Verifica che il tuo sito possa inviare email in generale — prova un test dal form di contatto di un altro plugin o con Mail Tester
2. Controlla OW Forms → Invii per confermare che l'invio è arrivato (se sì, il problema è la consegna, non OW Forms)
3. Imposta mail_failed_alert_email sul tuo indirizzo — OW Forms ti invierà un'email quando wp_mail() restituirà false
4. Installa un plugin SMTP (Fluent SMTP, WP Mail SMTP, ecc.) — il mail() PHP predefinito viene rifiutato dal 95 % dei server di ricezione

Il CAPTCHA non appare

• Verifica che spam_captcha_site_key e spam_captcha_secret_key siano entrambi impostati
• Apri la pagina nei DevTools — l'URL dello script del fornitore dovrebbe caricarsi con 200
• Per reCAPTCHA, il dominio del tuo sito deve essere registrato nell'admin Google
• Per Turnstile, la modalità widget nell'admin Cloudflare deve essere "Managed" o "Non-interactive"

I file vengono caricati ma l'admin non può scaricarli

È voluto — i file caricati vengono serviti da un handler PHP autenticato, non direttamente. Verifica di essere loggato come utente con manage_options.

L'importatore CF7 dice "0 form trovati"

L'importatore scansiona il post type wpcf7_contact_form. Se CF7 è già disattivato e i post sono stati eliminati, non c'è più nulla da importare. Riattiva CF7 solo per l'importazione, poi disattivalo di nuovo.

La tabella invii è enorme

• Riduci gdpr_retention_days (predefinito 1095 / 3 anni)
• Disabilita store_submissions se ti serve solo la consegna email, non un audit trail in database
• Imposta gdpr_auto_delete_after_response = true per eliminare al "gestito"

---

FAQ

OW Forms è gratuito? Sì. GPL-2.0-or-later. Non c'è versione Pro, né chiave di licenza, né funzionalità bloccate dietro pagamento.

Funziona su WordPress Multisite? Sì — ogni sito ha le proprie tabelle e la propria libreria di form, isolati come previsto.

Supporta form multi-step? La navigazione base avanti/indietro funziona tramite raggruppamento dei campi nello schema. Una UX wizard di prima classe è in roadmap per la v1.1.

Come esporto gli invii? OW Forms → Invii → Esporta CSV. L'esportazione rispetta i filtri correnti (form, intervallo di date, stato).

Posso ospitare i miei form dietro un paywall o login? Sì — incapsula lo shortcode nella logica di gating di un plugin di membership, o renderizza via PHP all'interno di un controllo is_user_logged_in().

Si integra con strumenti di email marketing / CRM? Out of the box: webhook (POST firmato HMAC verso qualsiasi endpoint), e destinatari email per form. Per Brevo / Mailchimp / HubSpot / Pipedrive, aggancia owf_submission_received e chiama l'API REST del fornitore — vedi la sezione Hook.

Il plugin è certificato GDPR? I valori predefiniti del plugin sono allineati alle best practice CNIL / GDPR, ma la certificazione è un processo legale specifico alla configurazione del tuo titolare del trattamento. Forniamo gli strumenti tecnici; il tuo DPO conferma la policy.

Dove trovo il supporto?

• Portale di supporto: https://optionweb.dev/it/addons/support/
• Email: support@optionweb.dev
• Documentazione: https://optionweb.dev/it/addons/ow-forms/

---

Realizzato da OptionWeb — Julien Daniel, Châtelet, Belgio.