WooCommerce 11.0: meta chiavi riservate non più salvate

Che cosa sono le chiavi meta riservate in WooCommerce?

In WooCommerce ogni riga di un ordine è rappresentata da un order item che può contenere metadati (meta). Alcune di queste chiavi sono considerate riservate perché sono gestite internamente dal core o da estensioni: ad esempio _product_id, _qty, _line_total o qualsiasi chiave registrata tramite il filtro woocommerce_hidden_order_itemmeta.

Le chiavi riservate non sono pensate per essere modificate manualmente dall’interfaccia di amministrazione: il loro valore viene impostato da funzioni specifiche (setter) o da logiche di calcolo dell’estensione.

---

Perché WooCommerce 11.0 ha interrotto il salvataggio di queste chiavi?

Fino alla versione 10.x il form dell’editor ordini accettava comunque l’inserimento di chiavi riservate tramite il pulsante Aggiungi meta. Il risultato era imprevedibile:

• Se la chiave aveva un setter (es. _product_id), il valore veniva passato al metodo corrispondente. Un valore non valido poteva bloccare la schermata dell’ordine, mentre un valore valido poteva sovrascrivere parzialmente dati critici.
• Per le chiavi senza setter, WooCommerce aggiungeva una nuova riga meta anche se la chiave era già presente, creando duplicati che confondevano il codice che si aspettava un unico valore.
• In ogni caso l’utente non poteva più visualizzare o modificare il valore inserito, perché il form non lo mostrava dopo il salvataggio.

Per evitare questi comportamenti instabili e garantire coerenza dei dati, a partire da WooCommerce 11.0.0 il salvataggio delle chiavi riservate è stato completamente rimosso dal form admin.

---

Cosa cambia nella pratica?

In sintesi, per l’amministratore non cambia nulla visivamente: le chiavi riservate non erano mai visibili. La differenza è che ora non c’è più il rischio di corrompere dati interni.

---

Implicazioni per gli sviluppatori

1. Filtri woocommerce_hidden_order_itemmeta – Se la tua estensione registra una chiave come hidden, WooCommerce la salta non solo nella visualizzazione ma anche nel salvataggio. Il valore inserito dall’amministratore verrà semplicemente scartato.
2. Gestione di meta personalizzate – Se vuoi che gli admin possano modificare una meta che attualmente è nascosta, devi rimuovere il filtro o fornire un’interfaccia dedicata.
3. Workaround tramite hook – È possibile reinserire il valore prima del salvataggio usando l’hook woocommerce_before_save_order_items. Un esempio di codice (da inserire in un plugin o nel file functions.php del tema):

add_action( 'woocommerce_before_save_order_items', function ( $order_id, $items ) {
    if ( ! is_admin() || ! current_user_can( 'edit_shop_orders' ) ) {
        return;
    }
    foreach ( $items['meta_key'] ?? [] as $item_id => $keys ) {
        foreach ( $keys as $row => $key ) {
            if ( '_your_meta_key' === $key ) {
                wc_update_order_item_meta(
                    $item_id,
                    $key,
                    wc_clean( wp_unslash( $items['meta_value'][ $item_id ][ $row ] ) )
                );
            }
        }
    }
}, 10, 2 );

Questo hook legge i dati inviati dal form e li scrive manualmente, aggirando il filtro di “skip”.

---

Cosa fare se sei un negoziante

• Meta richieste da estensioni – Se la documentazione di un plugin ti chiede di inserire una chiave tramite Aggiungi meta e il valore non rimane, è probabile che il plugin abbia registrato quella chiave come nascosta. Fino a quando il plugin non sarà aggiornato, puoi renderla visibile con un piccolo snippet:

add_filter( 'woocommerce_hidden_order_itemmeta', function( $keys ) {
    return array_diff( $keys, [ '_your_meta_key' ] );
}, 9999 );

Rimuovendo la chiave dall’elenco dei meta nascosti, il form la mostrerà e il valore verrà salvato normalmente.

• Controlli di sicurezza – Ricorda che le chiavi riservate sono spesso legate a calcoli di prezzo, quantità o ID prodotto. Modificarle manualmente può compromettere l’integrità dell’ordine. Usa le soluzioni sopra solo se sei certo di quello che fai.

---

Buone pratiche per la gestione dei meta

1. Separare meta amministrative da meta di business – Usa prefissi diversi (es. admin_ per dati di amministrazione) e non registrare queste chiavi come nascoste se devono essere editabili.
2. Fornire UI dedicate – Se un’estensione ha bisogno di un valore modificabile, crea una pagina di impostazioni o un metabox specifico invece di affidarti al generico “Aggiungi meta”.
3. Documentare le chiavi riservate – Mantieni un elenco interno delle chiavi che il tuo codice gestisce, così da evitare registrazioni accidentali come nascoste.
4. Testare gli aggiornamenti – Dopo aver aggiornato a WooCommerce 11.0, verifica che le estensioni non tentino più di salvare meta riservate tramite il form; altrimenti, implementa i work‑around mostrati.

---

Conclusioni pratiche

WooCommerce 11.0 ha chiuso una porta che, in pratica, non portava benefici ma poteva generare errori difficili da diagnosticare. Per gli sviluppatori significa dover rivedere eventuali dipendenze dal salvataggio manuale di meta riservate e, se necessario, implementare hook o UI dedicate. Per i negozianti, la buona notizia è che l’interfaccia admin è più stabile; la cattiva notizia è che, se un’estensione richiede ancora l’inserimento di meta nascoste, occorre intervenire con snippet o attendere un aggiornamento del plugin.

Se hai dubbi o vuoi condividere un caso d’uso, apri una issue su GitHub o chiedi supporto nel canale Slack della community WooCommerce.

Fonti

• WooCommerce Developer Blog