Campi personalizzati nel checkout di WooCommerce: dall’acquisto al backoffice

Aggiungere un campo al checkout non basta perché sia visibile sullo schermo. Per essere utile, deve rispondere a un’esigenza concreta, essere convalidato sul server, salvato insieme all’ordine e reso disponibile alle persone o ai processi che ne hanno bisogno. Ognuno di questi passaggi può non funzionare indipendentemente dagli altri.

L’implementazione dipende anche dal flusso di checkout attivo. Gli hook del checkout classico non aggiungono automaticamente campi al Checkout Block. Prima di programmare, identifica quale flusso usa il negozio e progetta l’intero percorso del dato.

Decidere se il dato appartiene al checkout

Individua quale attività richiede il dato e quando deve essere disponibile. Se è indispensabile per calcolare l’ordine, determinarne l’idoneità o preparare la consegna, potrebbe essere necessario chiederlo prima di confermare l’acquisto. Se invece serve solo a facilitare una gestione successiva, valuta di raccoglierlo in un secondo momento, per evitare attriti inutili.

Documenta la finalità, chi utilizza il campo, se è obbligatorio e per quanto tempo deve essere conservato. Verifica se WooCommerce dispone già di un campo standard per quell’informazione: duplicare un indirizzo o un numero di telefono senza stabilire quale valore prevale crea discrepanze. Per i dati sensibili o ad alto impatto, limita la raccolta e l’accesso e verifica gli obblighi di privacy applicabili.

Identificare il flusso e aggiungere il campo

Controlla nella pagina di pagamento se viene usato lo shortcode classico [woocommerce_checkout] oppure il Checkout Block. Verifica anche i template e le estensioni che modificano quella pagina. Riconoscere il design non è sufficiente: un’estensione può modificare il flusso o l’elaborazione. Implementa e testa il meccanismo appropriato e non dare per scontato che un campo creato per un flusso funzioni anche nell’altro.

Checkout classico: hook per i campi e l’ordine

Il checkout classico consente di modificare i campi con woocommerce_checkout_fields, convalidarli con woocommerce_after_checkout_validation e salvarli durante la creazione dell’ordine con woocommerce_checkout_create_order. Questo esempio registra un campo facoltativo, rifiuta gli input non scalari e limita il testo a 120 caratteri Unicode:

add_filter('woocommerce_checkout_fields', function ($fields) {
    $fields['order']['delivery_instructions'] = [
        'type'      => 'text',
        'label'     => 'Istruzioni per la consegna',
        'required'  => false,
        'priority'  => 25,
        'maxlength' => 120,
        'class'     => ['form-row-wide'],
    ];
    return $fields;
});

add_action('woocommerce_after_checkout_validation', function ($data, $errors) {
    $raw = $data['delivery_instructions'] ?? '';
    if (! is_scalar($raw)) {
        $errors->add('delivery_instructions', 'Il valore deve essere testo.');
        return;
    }

    $value = trim(sanitize_text_field((string) $raw));
    if (preg_match_all('/./us', $value, $matches) === false) {
        $errors->add('delivery_instructions', 'Il testo non ha un formato valido.');
        return;
    }
    if (count($matches[0]) > 120) {
        $errors->add('delivery_instructions', 'Il testo non può superare 120 caratteri.');
    }
}, 10, 2);

add_action('woocommerce_checkout_create_order', function ($order, $data) {
    $raw = $data['delivery_instructions'] ?? '';
    if (! is_scalar($raw)) {
        return;
    }
    $value = trim(sanitize_text_field((string) $raw));
    if ($value !== '') {
        $order->update_meta_data('_delivery_instructions', $value);
    }
}, 10, 2);

L’attributo maxlength impone un limite nel browser, ma non sostituisce la convalida sul server. L’esempio conta i code point Unicode con un’espressione compatibile con UTF-8; alcuni caratteri, come determinati emoji, occupano più di un’unità UTF-16 nel browser. Se devono essere ammessi, definisci e testa esplicitamente la regola di lunghezza, in modo che l’esperienza del cliente e il server non diano risultati diversi.

L’esempio salva solo un valore valido e non vuoto. Se il campo diventa obbligatorio, convalida anche la sua assenza e restituisci un errore prima di creare l’ordine. Usa un nome interno stabile e non modificarlo senza pianificare la migrazione dei dati esistenti.

Checkout Block: API per i campi aggiuntivi

Per il Checkout Block, usa l’API dei campi aggiuntivi di WooCommerce invece di inserire HTML nel modulo. Registra il campo da un plugin o un tema compatibile, ad esempio durante woocommerce_init:

add_action('woocommerce_init', function () {
    if (! function_exists('woocommerce_register_additional_checkout_field')) {
        return;
    }

    woocommerce_register_additional_checkout_field([
        'id'       => 'mi-plugin/delivery-instructions',
        'label'    => 'Istruzioni per la consegna',
        'location' => 'order',
        'type'     => 'text',
        'required' => false,
    ]);
});

L’API integra il campo con il flusso a blocchi e con il relativo salvataggio associato all’ordine. Se ti servono regole specifiche, consulta le opzioni di sanitizzazione e convalida supportate dall’API nell’installazione in uso e testa l’errore dall’inizio alla fine. Non salvare lo stesso valore in parallelo con un altro meccanismo senza aver stabilito quale sia la fonte attendibile.

Prima del deployment, verifica che la funzione di registrazione esista e consulta la documentazione relativa alla versione installata. Se non è disponibile, non simulare la compatibilità con JavaScript: aggiorna oppure scegli un’alternativa compatibile con il checkout utilizzato e testa in un ambiente di staging.

Convalidare, normalizzare e salvare sul server

La convalida nel browser migliora l’esperienza, ma non è un controllo di sicurezza. Sul server verifica la presenza quando il campo è obbligatorio, il tipo, la lunghezza, il formato e l’appartenenza ai valori consentiti. Per gli elenchi chiusi, convalida identificativi noti, non testo arbitrario inviato dal client. Se il dato è facoltativo, stabilisci se assente e vuoto hanno lo stesso significato. In caso di valore non valido, mostra un errore comprensibile e non confermare l’ordine omettendo silenziosamente un dato necessario.

Nel flusso classico, $order->update_meta_data() usa l’API CRUD dell’ordine ed evita di scrivere direttamente nelle tabelle o di dipendere da una specifica struttura di archiviazione. Nel Checkout Block, lascia che l’API dei campi aggiuntivi gestisca l’associazione del campo e recupera il valore tramite l’API dell’ordine o il meccanismo documentato per quell’integrazione; non dare per scontata una chiave interna dei metadati.

Per verificare la compatibilità, controlla nelle impostazioni di WooCommerce se è attiva l’archiviazione degli ordini ad alte prestazioni (HPOS) o quella basata sulle tabelle dei post. In un ambiente di test con la stessa configurazione, crea un ordine per ciascun flusso, leggilo come oggetto WC_Order con wc_get_order($order_id) e verifica il dato tramite l’API CRUD, ad esempio $order->get_meta('_delivery_instructions') per il campo classico. Aggiorna l’ordine e rileggilo; non usare query SQL dirette alle tabelle interne. Ripeti le verifiche dopo aver modificato l’archiviazione o aggiornato le estensioni che intervengono nel checkout.

Consultare il dato nel backoffice

La procedura di verifica operativa consiste nel creare un ordine di prova, aprire WooCommerce > Ordini, accedere alla schermata di modifica e confrontare il valore visualizzato con quello inviato. Per il checkout classico, se il metadato non appare nella schermata utilizzata dal team, è possibile aggiungere una visualizzazione amministrativa con il seguente hook dei dati dell’ordine:

add_action('woocommerce_admin_order_data_after_billing_address', function ($order) {
    $value = $order->get_meta('_delivery_instructions');
    if ($value !== '') {
        echo '<p><strong>Istruzioni per la consegna:</strong> '
            . esc_html($value) . '</p>';
    }
});

Questo hook e il metadato dell’esempio si riferiscono al checkout classico; verifica che siano visualizzati nella schermata amministrativa attiva nel negozio. Con HPOS e nella schermata di modifica degli ordini basata su blocchi, controlla il risultato effettivo: non presumere che un’estensione del pannello classico sia automaticamente compatibile con la nuova interfaccia. Per leggere o modificare i dati, usa sempre l’oggetto dell’ordine e l’API CRUD.

I campi registrati tramite l’API del Checkout Block possono essere integrati nei dettagli dell’ordine. Verificalo in WooCommerce > Ordini con un ordine di prova. Se altro codice deve consultare il valore, individua nella documentazione dell’API la posizione e il meccanismo di lettura previsti per la versione installata; non indovinare la chiave dei metadati. Se il campo non viene mostrato, aggiungi una visualizzazione amministrativa compatibile con quella schermata e testa sia con il sistema di archiviazione configurato sia con le estensioni amministrative installate.

Se è necessaria la modifica, definisci i ruoli autorizzati e salva le modifiche tramite l’API CRUD dell’ordine. Non mostrare automaticamente il dato in e-mail, documenti, esportazioni o schermate pubbliche: aggiungi ogni destinazione solo in presenza di un’esigenza operativa, limita l’accesso e applica sempre l’escaping all’output.

Testare l’intero ciclo ed evitare regressioni

Un test che verifica soltanto il rendering del campo non è sufficiente. Controlla il percorso dal modulo all’utilizzo successivo e includi almeno i seguenti casi:

• Ordine valido con dato inserito: convalida, salvataggio nell’ordine corretto e consultazione nel backoffice.
• Campo facoltativo vuoto e campo obbligatorio assente: verifica il comportamento definito per ciascun caso.
• Input alterato, non scalare, troppo lungo o non compreso tra i valori consentiti: verifica che venga rifiutato sul server.
• Testo con accenti e caratteri multibyte, compreso il limite esatto; verifica anche l’interazione con maxlength.
• Aggiornamento dell’ordine: verifica che cosa cambia, chi può modificarlo e come viene propagato.
• Checkout classico e Checkout Block: testa il flusso attivo e qualsiasi cambio di modalità previsto.
• Autorizzazioni ed esposizione: verifica che solo gli utenti e i processi autorizzati ricevano il valore.

Includi test di regressione per totali, convalide e creazione dell’ordine. Se un’automazione utilizza il campo, verifica anche cosa accade quando il dato manca o il suo invio non riesce. Un chiaro segnale diagnostico è che il dato appaia nel browser ma non nell’ordine o nel processo che dovrebbe utilizzarlo.

Lista di controllo prima del deployment

• La finalità del dato e il momento della raccolta sono documentati.
• Il meccanismo corrisponde al checkout attivo: hook del flusso classico o API dei campi aggiuntivi per il Block.
• Il server convalida tipo, formato e lunghezza; gli input non scalari vengono rifiutati e il trattamento dei valori assenti, vuoti e non validi è definito.
• L’installazione e il sistema di archiviazione degli ordini sono stati identificati; la lettura e l’aggiornamento sono testati tramite l’API CRUD.
• Un ordine di prova conferma la lettura nella schermata di backoffice utilizzata e l’accesso è limitato.
• I test includono caratteri Unicode, aggiornamenti, errori, integrazioni e regressioni del checkout.