Hook WordPress per Sviluppatori — Action, Filter e Priorità che Funzionano

Un plugin che non parte, una funzione che si esegue al momento sbagliato, un filtro che viene ignorato. Se sviluppi in WordPress, questi problemi li hai visti. Spesso non è colpa del codice, ma di come e quando viene eseguito. Noi, di Meteora Web, lo vediamo ogni giorno nei progetti che ci arrivano: siti lenti, funzionalità rotte, conflitti tra plugin. Il motivo? Hooks usati male. In questa guida operativa affrontiamo cosa sono, come funzionano azioni e filtri, come gestire la priorità e quali best practice adottare per scrivere codice che non si rompa quando arriva un aggiornamento.

Che differenza c'è tra action e filter in WordPress?

Action e filter sono i due tipi di hook di WordPress. Entrambi permettono di "attaccarsi" al flusso di esecuzione del core, dei temi o dei plugin. La differenza è sostanziale:

Action: esegue un'azione personalizzata in un punto specifico del ciclo della pagina. Ad esempio: wp_head, init, save_post. Non restituisce un valore, ma esegue codice (inviare email, aggiornare dati, registrare script).

Filter: modifica un dato prima che venga restituito o salvato. Riceve un argomento (il dato), lo trasforma e lo restituisce. Esempi: the_content, wp_title, woocommerce_product_price.

Errori comuni: usare un filter dove serve un action (modificare dati ma non restituirli) o viceversa. Se il tuo codice non produce l'effetto atteso, controlla quale tipo di hook stai usando.

Esempio pratico: action per aggiungere un meta box

// Action corretta: aggiunge un meta box al post editor
add_action('add_meta_boxes', 'aggiungi_mia_meta_box');
function aggiungi_mia_meta_box() {
    add_meta_box('mio_id', 'Mio Box', 'render_mia_meta_box', 'post', 'side', 'default');
}

Esempio pratico: filter per modificare il contenuto

// Filter corretto: aggiunge un avviso dopo il contenuto
add_filter('the_content', 'aggiungi_avviso_dopo_contenuto');
function aggiungi_avviso_dopo_contenuto($content) {
    if (is_single()) {
        $content .= '
Questo articolo è stato aggiornato il ' . get_the_modified_date() . '.
                                                                                        

                            
Sponsored Protocol
                            

                                                                                                                                            


                                                                                                
                        
                    
                                                    ';
    }
    return $content;
}

Cosa fare subito: rivedi i tuoi hook esistenti. Ogni add_action e add_filter deve avere il tipo corretto. Se non restituisci un valore, usa action. Se modifichi un dato, usa filter.

Come funziona la priorità negli hook WordPress?

La priorità determina l'ordine di esecuzione quando più funzioni sono agganciate allo stesso hook. Il parametro $priority è un intero, di default 10. Più basso è il numero, prima viene eseguita la funzione. Priorità uguali vengono eseguite nell'ordine di registrazione.

Perché è importante? Immagina due plugin che modificano the_content: uno aggiunge uno shortcode, l'altro lo filtra. Se il filtro viene eseguito prima dello shortcode, il contenuto non verrà processato correttamente.

Esempio di gestione priorità

// Eseguito per primo (priorità 5)
add_filter('the_content', 'funzione_priorita_alta', 5);
// Eseguito per ultimo (priorità 20)
add_filter('the_content', 'funzione_priorita_bassa', 20);
// Eseguito al centro (priorità 10, default)
add_filter('the_content', 'funzione_priorita_media');

Errore comune: non specificare la priorità quando si deve agire prima o dopo un altro hook. Se un plugin usa add_action('init', 'sua_funzione', 10) e tu usi add_action('init', 'mia_funzione'), saranno eseguiti nell'ordine di registrazione, non sempre prevedibile. Specifica sempre la priorità se l'ordine conta.

Come individuare la priorità giusta

Usa un plugin come Query Monitor per vedere l'elenco delle funzioni agganciate a un hook e la loro priorità. In alternativa, in fase di sviluppo, puoi usare:

// Debug: stampa tutte le funzioni agganciate a 'wp_head'
global $wp_filter;
var_dump( $wp_filter['wp_head'] );

Cosa fare subito: se stai riscontrando conflitti tra plugin o temi, controlla la priorità. Usa Query Monitor o il dump per capire chi si esegue prima e chi dopo. Regola le tue priorità di conseguenza.

Quali best practice per gestire gli hook WordPress senza conflitti?

Dopo anni di sviluppo su WordPress (oltre 8 progetti reali, con clienti in tutta Italia), abbiamo messo a punto alcune regole che evitano il 90% dei conflitti:

1. Prefissare i nomi delle funzioni

Non usare nomi generici come mia_funzione. Usa un prefisso unico: miaazienda_miafunzione. Così eviti collisioni con altri plugin o temi.

2. Non usare remove_action o remove_filter alla leggera

Rimuovere hook altrui può rompere funzionalità. Se devi farlo, assicurati di passare lo stesso $priority con cui è stato registrato. Esempio:

// Rimuovi un'azione di un plugin (supponendo priorità 10)
remove_action('init', 'plugin_function', 10);
// Per sicurezza, usa una priorità bassa per eseguire la rimozione prima che l'azione venga eseguita
add_action('init', 'rimuovi_hook_plugin', 0);
function rimuovi_hook_plugin() {
    remove_action('init', 'plugin_function', 10);
}

Attenzione: la rimozione deve avvenire prima dell'esecuzione dell'hook. Spesso va fatta in un hook di priorità più bassa (es. 0).

3. Usare did_action() per evitare esecuzioni multiple

Se la tua funzione deve essere eseguita una sola volta, verifica se l'hook è già stato lanciato:

add_action('wp_enqueue_scripts', 'carica_mio_script');
function carica_mio_script() {
    if (did_action('wp_enqueue_scripts') && !wp_script_is('mio-script', 'enqueued')) {
        wp_enqueue_script('mio-script', get_template_directory_uri() . '/js/mio.js', array(), '1.0', true);
    }
}

4. Separare logica di business e presentazione

Usa gli action per logiche di backend (salvataggio, invio email, aggiornamento dati). Usa i filter per modificare l'output visivo. Mescolare i due crea dipendenze difficili da debuggare.

5. Documentare ogni hook personalizzato

Se crei plugin o temi, dichiara i tuoi hook personalizzati con do_action() o apply_filters() e documentali. Esempio:

/**
 * Fires after saving a custom post type.
 *
 * @param int $post_id The post ID.
 */
do_action('miaazienda_after_save', $post_id);

Cosa fare subito: rivedi il codice dei tuoi plugin o temi. Applica almeno la prefissazione dei nomi e la documentazione degli hook personalizzati. Se lavori in team, stabilisci un naming convention comune.

Come testare e debuggare gli hook WordPress?

Il debugging degli hook è essenziale per capire l'ordine di esecuzione e i conflitti. Ecco gli strumenti che usiamo quotidianamente:

• Query Monitor — mostra tutti gli hook eseguiti, le funzioni agganciate e i tempi di esecuzione. Indispensabile.
• WP Debugging — abilita WP_DEBUG e WP_DEBUG_LOG nel wp-config.php per loggare errori e avvisi.
• Hooks Debugger — plugin leggero per vedere quali hook vengono lanciati in una pagina.

Inoltre, puoi creare un semplice log personalizzato:

// Log personalizzato per tracciare l'esecuzione degli hook
if (!function_exists('log_hook')) {
    function log_hook($hook_name) {
        if (defined('WP_DEBUG') && WP_DEBUG) {
            error_log('Hook eseguito: ' . $hook_name);
        }
    }
}
add_action('init', function() { log_hook('init'); });
add_action('wp_head', function() { log_hook('wp_head'); });

Cosa fare subito: installa Query Monitor sul tuo ambiente di sviluppo. Esamina la scheda "Hooks & Actions" per un paio di pagine. Imparerai più in 10 minuti che in ore di lettura.

Quali errori evitare con gli hook WordPress?

Ecco gli errori che abbiamo visto più spesso nei progetti che ci arrivano:

• Usare add_action dentro un altro action senza priorità — esempio: aggiungere add_action('wp_footer', ...) dentro wp_head. Funziona, ma l'ordine non è garantito. Meglio specificare priorità o usare hook dedicati.
• Non rimuovere hook obsoleti — se un plugin non è più attivo, i suoi hook rimangono nel database (es. option transients). Pulisci.
• Modificare variabili globali in un filter — i filter devono restituire il dato, non modificare globali. Se hai bisogno di uno stato, usa un action separato.
• Usare the_content per modifiche pesanti — se devi manipolare molto l'output, considera di usare template_include o un template part.

Cosa fare subito: scorri il tuo tema o plugin alla ricerca di add_action e add_filter. Controlla che non ci siano hook annidati senza priorità e che i filter non modifichino variabili globali.

Cosa fare adesso

Gli hook WordPress sono il cuore dello sviluppo estendibile. Se li usi bene, il tuo codice diventa modulare, manutenibile e a prova di aggiornamenti. Ecco 5 azioni concrete da fare subito:

1. Controlla i tipi di hook — ogni add_action e add_filter deve essere del tipo giusto. Se modifichi dati, usa filter; se esegui codice, usa action.
2. Specifica sempre la priorità — anche se è 10, scrivilo. Chi legge capisce le tue intenzioni.
3. Usa Query Monitor — installalo e analizza le pagine del tuo sito per vedere l'ordine di esecuzione degli hook.
4. Prefissa i nomi delle funzioni — evita collisioni con altri plugin o temi.
5. Documenta gli hook personalizzati — i tuoi colleghi (e il te del futuro) ti ringrazieranno.

Per approfondire lo sviluppo WordPress avanzato con temi custom, plugin e REST API, visita la nostra Pagina Pillar su WordPress Sviluppo Avanzato.