WooCommerce Hooks e Filtri: Personalizzare il Negozio Senza Modificare il Core
Uno dei punti di forza di WooCommerce risiede nella sua estrema flessibilità. Grazie al sistema di hooks (ganci) ereditato da WordPress, è possibile modificare praticamente ogni aspetto del negozio online senza toccare i file originali del plugin. Questo approccio garantisce che gli aggiornamenti futuri non cancellino le personalizzazioni e che il codice resti ordinato, manutenibile e sicuro.
In questa guida approfondita vedremo cosa sono gli hooks, la differenza tra action et filter, quali sono i più utili in WooCommerce e come utilizzarli con esempi pratici pronti da copiare nel proprio progetto. Che tu sia uno sviluppatore alle prime armi o un professionista che desidera un ripasso completo, troverai indicazioni concrete per portare il tuo e-commerce al livello successivo.
Cosa Sono gli Hooks di WordPress
Un hook è un punto predefinito nel codice di WordPress (e di WooCommerce) in cui è possibile agganciare le proprie funzioni personalizzate. Quando il sistema raggiunge quel punto durante il caricamento della pagina, esegue automaticamente tutte le funzioni registrate su quel particolare hook.
Esistono due tipologie fondamentali:
- Action hooks — permettono di eseguire codice aggiuntivo in un determinato momento. Non restituiscono valori: si limitano a compiere operazioni (inserire HTML, inviare email, salvare dati).
- Filter hooks — permettono di intercettare e modificare un valore prima che venga utilizzato. Ricevono un dato in ingresso, lo trasformano e lo restituiscono modificato.
Perché usare gli hooks invece di modificare i file del plugin
Modificare direttamente i file di WooCommerce (o di qualsiasi plugin) è una pratica fortemente sconsigliata per diverse ragioni:
- Aggiornamenti distruttivi — ogni aggiornamento del plugin sovrascrive i file modificati, cancellando le personalizzazioni.
- Difficoltà di debug — quando qualcosa smette di funzionare, è molto più complicato individuare il problema se il codice è stato alterato in più punti sparsi.
- Sicurezza compromessa — saltare gli aggiornamenti per paura di perdere le modifiche espone il sito a vulnerabilità note.
- Portabilità zero — le modifiche dirette non possono essere trasferite facilmente a un altro sito o condivise con altri sviluppatori.
Gli hooks risolvono tutti questi problemi: il codice personalizzato vive in un file separato, resta attivo anche dopo gli aggiornamenti e può essere attivato o disattivato in modo indipendente.
Gli Action Hooks Più Utili di WooCommerce
WooCommerce mette a disposizione centinaia di action hooks. Di seguito analizziamo quelli che ogni sviluppatore dovrebbe conoscere, con esempi pratici per ciascuno.
woocommerce_before_main_content
Questo hook si attiva subito prima del contenuto principale delle pagine di archivio (negozio, categorie, tag). È ideale per inserire banner promozionali, messaggi informativi o breadcrumb personalizzati che devono apparire in cima alla pagina del catalogo.
Esempio di utilizzo:
add_action( woocommerce_before_main_content, gtg_banner_spedizione_gratuita );
function gtg_banner_spedizione_gratuita() {
echo <div class="promo-banner">Spedizione gratuita per ordini superiori a 50 €</div>;
}
woocommerce_after_shop_loop_item
Si attiva dopo ogni prodotto nel loop del catalogo, subito dopo il pulsante «Aggiungi al carrello». Questo hook è perfetto per aggiungere badge, etichette personalizzate o informazioni aggiuntive sotto ciascun prodotto nella griglia.
Un utilizzo frequente consiste nel mostrare la disponibilità residua quando le scorte sono basse, creando un senso di urgenza che incentiva il completamento degli acquisti.
woocommerce_single_product_summary
Questo hook è legato alla pagina del singolo prodotto e si attiva nella sezione del riepilogo (titolo, prezzo, descrizione breve, pulsante di acquisto). Accetta una priorità che determina la posizione esatta: con priorità 5 il contenuto appare prima del titolo, con priorità 25 dopo il prezzo, con 35 dopo la descrizione breve.
Gestire le priorità è fondamentale per posizionare correttamente gli elementi nella pagina prodotto senza dover intervenire sui template.
woocommerce_before_cart
Si attiva prima della tabella del carrello. È il punto ideale per inserire messaggi che motivino il cliente ad aggiungere altri articoli, come ad esempio «Aggiungi ancora 15 € al carrello per ottenere la spedizione gratuita» — una tecnica di upselling molto efficace.
woocommerce_checkout_before_customer_details
Questo hook si attiva nella pagina di checkout, prima dei campi per i dati del cliente. Viene comunemente utilizzato per mostrare garanzie di sicurezza, badge di pagamento sicuro, informazioni sulla politica di reso o qualsiasi elemento che riduca le esitazioni del cliente nel momento critico della conversione.
woocommerce_thankyou
Si attiva nella pagina di conferma ordine, dopo che il pagamento è stato elaborato con successo. Riceve come parametro il numero di ordine, il che consente di personalizzare il messaggio in base al tipo di prodotto acquistato, al metodo di pagamento scelto o al valore totale.
Molti negozi utilizzano questo hook per inserire il codice di conversione di Google Ads, script di tracciamento per Facebook Pixel o per mostrare coupon di sconto validi per il prossimo acquisto.
I Filter Hooks Più Utili di WooCommerce
I filtri sono ancora più potenti delle azioni perché permettono di trasformare i dati prima che raggiungano il browser del visitatore. Ecco i cinque filtri indispensabili.
woocommerce_product_tabs
Questo filtro controlla le schede (tab) visualizzate nella pagina del singolo prodotto. Di default WooCommerce mostra «Descrizione», «Informazioni aggiuntive» e «Recensioni». Con questo filtro è possibile rimuovere schede, riordinarle o aggiungerne di completamente nuove.
Esempio pratico — aggiungere una scheda «Guida alle taglie»:
add_filter( woocommerce_product_tabs, gtg_tab_guida_taglie );
function gtg_tab_guida_taglie( $tabs ) {
$tabs[guida_taglie] = array(
title => Guida alle Taglie,
priority => 50,
callback => gtg_contenuto_guida_taglie,
);
return $tabs;
}
function gtg_contenuto_guida_taglie() {
echo <h2>Guida alle Taglie</h2>;
echo <p>Consulta la tabella seguente per individuare la taglia corretta.</p>;
}
woocommerce_checkout_fields
Controlla tutti i campi del modulo di checkout. Permette di aggiungere campi personalizzati (codice fiscale, partita IVA, note di consegna), rimuovere quelli non necessari, modificare le etichette o cambiare la posizione dei campi esistenti.
Per un e-commerce italiano, ad esempio, è spesso necessario aggiungere il campo «Codice Fiscale» o «PEC» per la fatturazione elettronica. Il filtro woocommerce_checkout_fields rende questa operazione semplice e pulita.
woocommerce_package_rates
Intercetta le tariffe di spedizione calcolate e permette di modificarle, rimuoverle o aggiungerne di nuove in modo condizionale. Questo filtro è estremamente utile per implementare logiche di spedizione avanzate.
Un caso comune: nascondere la spedizione a pagamento quando il carrello supera una certa soglia, lasciando visibile solo la spedizione gratuita. Oppure applicare un supplemento per le isole o per determinate zone postali.
woocommerce_get_price_html
Modifica il codice HTML del prezzo visualizzato nella pagina prodotto e nel catalogo. Permette di aggiungere testo prima o dopo il prezzo, formattarlo in modo diverso o sostituirlo completamente con un messaggio personalizzato.
Esempio — aggiungere la dicitura «IVA inclusa» sotto ogni prezzo:
add_filter( woocommerce_get_price_html, gtg_prezzo_iva_inclusa, 10, 2 );
function gtg_prezzo_iva_inclusa( $price, $product ) {
return $price . <small class="iva-info"> IVA inclusa</small>;
}
woocommerce_cart_item_name
Filtra il nome del prodotto visualizzato nel carrello. Si utilizza per aggiungere informazioni extra accanto al nome, come badge «In saldo», icone di disponibilità o messaggi relativi ai tempi di consegna stimati per quello specifico articolo.
Dove Inserire il Codice Personalizzato
Sapere quali hooks utilizzare è solo metà della questione. È altrettanto importante scegliere il posto giusto dove scrivere il codice. Esistono tre opzioni principali, ciascuna con vantaggi e svantaggi specifici.
File functions.php del tema figlio (child theme)
Il metodo classico prevede di inserire il codice nel file functions.php di un tema figlio. Mai nel tema principale, perché le modifiche verrebbero perse con il prossimo aggiornamento del tema.
- Pro — nessun plugin aggiuntivo necessario, controllo completo.
- Contro — il codice è legato al tema; cambiando tema si perdono tutte le personalizzazioni.
Plugin personalizzato dedicato
Creare un piccolo plugin dedicato è la soluzione più professionale. Basta creare un file PHP nella cartella wp-content/plugins/ con un header standard di WordPress. In questo modo le personalizzazioni restano attive indipendentemente dal tema utilizzato.
Questa soluzione è particolarmente indicata quando le modifiche riguardano la logica di business (calcolo prezzi, regole di spedizione, integrazioni con sistemi esterni) piuttosto che la presentazione visiva.
Plugin Code Snippets
Per chi preferisce evitare la gestione diretta dei file via FTP o SSH, il plugin Code Snippets offre un comodo editor integrato nella bacheca di WordPress. Ogni frammento di codice può essere attivato, disattivato, organizzato con tag e persino esportato.
- Pro — interfaccia grafica intuitiva, gestione centralizzata, possibilità di disattivare singoli snippet senza cancellare codice.
- Contro — aggiunge un plugin in più al sito; non adatto a progetti con decine di personalizzazioni complesse.
Esempi Pratici Completi
Passiamo ora a scenari reali che combinano più hooks per ottenere risultati concreti.
Esempio 1: Aggiungere una scheda personalizzata al prodotto
Un negozio di elettronica vuole aggiungere la scheda «Specifiche Tecniche» a tutti i prodotti di una determinata categoria. Si combinano il filtro woocommerce_product_tabs con una condizione sulla categoria del prodotto corrente. La funzione di callback recupera un campo personalizzato (custom field) e lo visualizza in una tabella ordinata.
Esempio 2: Modificare la visualizzazione del prezzo
Un negozio B2B desidera mostrare il prezzo unitario e quello per quantità. Si utilizza il filtro woocommerce_get_price_html verificando se il cliente appartiene al ruolo «wholesale». In caso affermativo, il prezzo viene ricalcolato applicando lo sconto per quantità e visualizzato con una formattazione dedicata.
Esempio 3: Aggiungere un campo al checkout
Per la fatturazione elettronica italiana è indispensabile raccogliere il Codice SDI o la PEC del cliente. Con il filtro woocommerce_checkout_fields si aggiunge il campo, con la action woocommerce_checkout_update_order_meta si salva il valore nei metadati del relativo ordine, e con woocommerce_admin_order_data_after_billing_address lo si visualizza nel pannello amministrativo.
add_filter( woocommerce_checkout_fields, gtg_campo_codice_sdi );
function gtg_campo_codice_sdi( $fields ) {
$fields[billing][billing_codice_sdi] = array(
type => text,
label => Codice SDI,
placeholder => Inserisci il codice destinatario,
required => false,
class => array( form-row-wide ),
priority => 120,
);
return $fields;
}
Esempio 4: Nascondere metodi di spedizione in modo condizionale
Se il carrello supera i 50 €, si desidera nascondere la spedizione standard a pagamento e lasciare solo quella gratuita. Il filtro woocommerce_package_rates riceve tutte le tariffe calcolate: basta verificare la presenza della tariffa gratuita e, se il totale del carrello supera la soglia, rimuovere le altre opzioni.
Debugging degli Hooks: Strumenti e Tecniche
Quando un hook non produce il risultato atteso, è fondamentale disporre di strumenti adeguati per individuare il problema.
Query Monitor
Il plugin Query Monitor è lo strumento di debug più completo per WordPress. Mostra tutti gli hooks eseguiti durante il caricamento della pagina, le funzioni agganciate a ciascun hook, la priorità e il file di origine. Inoltre evidenzia le query SQL lente e gli errori PHP.
La pagina Stato del sistema
WooCommerce include una sezione Stato del sistema (WooCommerce → Stato) che fornisce informazioni preziose per il debug: versione PHP, limiti di memoria, log degli errori, template sovrascritti e molto altro. È il primo posto da controllare quando qualcosa non funziona come previsto.
Log personalizzati
Per verificare che un hook venga effettivamente eseguito, si può scrivere un messaggio nel log di WooCommerce utilizzando la classe WC_Logger. I log sono consultabili dalla sezione Stato → Log nella bacheca.
Errori comuni e soluzioni
- La funzione non viene eseguita — verificare che il nome della action/filter sia scritto correttamente e che la priorità non posizioni la funzione dopo un
remove_all_actionseseguito da un altro plugin. - Conflitto tra plugin — due plugin possono agganciare lo stesso hook con la stessa priorità. Modificare la priorità numerica di uno dei due risolve quasi sempre il conflitto.
- Il filtro restituisce un valore vuoto — assicurarsi che la funzione agganciata al filtro termini sempre con
return. Dimenticare il return è un errore frequentissimo che può causare la scomparsa di prezzi, nomi prodotto o intere sezioni della pagina. - Hook eseguito troppe volte — se la funzione viene agganciata dentro un loop o un file incluso più volte, si verificano esecuzioni multiple. Racchiudere la registrazione in un controllo
did_action()previene il problema.
Best Practice per un Codice Sostenibile
Dopo anni di sviluppo su WooCommerce, ecco le pratiche che garantiscono un codice robusto e facile da mantenere nel tempo:
- Utilizzare sempre un prefisso unico per i nomi delle funzioni (es.
gtg_,mionegozio_) per evitare conflitti con altri plugin o temi. - Documentare ogni hook con un commento che spieghi il motivo della personalizzazione e la data di implementazione.
- Raggruppare le personalizzazioni per area — un file o uno snippet per la spedizione, uno per il checkout, uno per le email.
- Testare sempre su un ambiente di staging prima di applicare le modifiche al sito in produzione.
- Verificare la compatibilità dopo ogni aggiornamento di WooCommerce, WordPress e del tema.
- Mantenere le funzioni brevi e focalizzate — ogni funzione agganciata dovrebbe fare una sola cosa e farla bene.
Quando Rivolgersi a Professionisti
Gli hooks di WooCommerce offrono possibilità quasi illimitate, ma personalizzazioni complesse richiedono una conoscenza approfondita di PHP, delle API di WordPress e delle logiche interne di WooCommerce. Errori nel codice possono compromettere il funzionamento del checkout, i calcoli fiscali o le integrazioni con i gateway di pagamento.
Se il tuo progetto richiede personalizzazioni avanzate — integrazioni con gestionali, logiche di prezzo dinamiche, funzionalità su misura per il tuo settore — affidarsi a sviluppatori esperti è la scelta più sicura. Il team di G Tech Group vanta anni di esperienza nella realizzazione di e-commerce WooCommerce personalizzati, dalla configurazione iniziale fino alle integrazioni più complesse.
Per una consulenza personalizzata o per richiedere un preventivo, visita la pagina contatti di G Tech Group.
Migliora il Tuo Sito WordPress
Scopri le nostre guide complete sugli altri plugin essenziali per WordPress: