Guida agli hook di WordPress: action e filter

Cosa sono gli hook di WordPress

Il sistema di hook di WordPress è la base che ti permette di estendere e modificare il sistema WordPress senza cambiare direttamente il codice sorgente. Gli hook sono punti nel codice di WordPress in cui puoi agganciare le tue funzioni, che verranno eseguite in un momento specifico o che modificheranno i dati che attraversano il sistema. Senza gli hook, ogni personalizzazione richiederebbe la modifica diretta dei file core di WordPress, che andrebbero persi a ogni aggiornamento.

Esistono due tipi di hook: gli action e i filter. Gli action ti permettono di eseguire codice in un momento specifico del ciclo di vita di WordPress, mentre i filter ti permettono di modificare i dati prima che vengano visualizzati o salvati. Comprendere questi due concetti è fondamentale per ogni sviluppatore WordPress perché sono la base per creare temi, plugin e funzionalità personalizzate.

Action - eseguire codice al momento giusto

Come funzionano gli action

Un action hook è un punto nel codice di WordPress in cui viene inserita una chiamata alla funzione do_action. Quando WordPress raggiunge quel punto durante l'esecuzione, controlla se ci sono funzioni agganciate a quell'hook e le esegue in ordine di priorità. Ad esempio, l'action wp_head si attiva all'interno del tag head di ogni pagina, wp_footer si attiva prima del tag body di chiusura e init si attiva all'inizio di ogni caricamento di WordPress dopo che tutti i plugin sono stati caricati.

Usare add_action

La funzione add_action accetta quattro parametri: nome dell'hook, funzione di callback, priorità e numero di argomenti. La priorità determina l'ordine di esecuzione quando più funzioni sono agganciate allo stesso hook, con un valore predefinito di 10 dove un numero più basso significa esecuzione anticipata. Ad esempio, se vuoi aggiungere il codice di Google Analytics nell'header del sito, aggancia la funzione all'hook wp_head con priorità 1 per eseguirla tra le prime. Se vuoi aggiungere CSS dopo tutti i plugin, usa la priorità 99.

Gli action hook più comuni

• init: Si attiva all'inizio di ogni richiesta dopo il caricamento dei plugin. Ideale per registrare custom post type, tassonomie e shortcode.
• wp_enqueue_scripts: Il modo corretto per aggiungere file CSS e JavaScript sul frontend. Usa le funzioni wp_enqueue_style e wp_enqueue_script per gestire le dipendenze ed evitare i duplicati.
• admin_init: Si attiva all'inizio di ogni pagina dell'amministrazione. Usalo per registrare le impostazioni del plugin, per i controlli dei permessi o per i redirect.
• save_post: Si attiva quando un post viene salvato o aggiornato. Ideale per salvare meta dati personalizzati, validare i contenuti o inviare notifiche.
• wp_login e wp_logout: Si attivano al login e al logout dell'utente. Usali per il logging delle attività, i redirect o la pulizia della cache.
• template_redirect: Si attiva prima del caricamento del template. Ideale per redirect personalizzati o controlli di accesso alle pagine.

Filter - modifica dei dati

Come funzionano i filter

Un filter hook funziona in modo simile a un action hook, ma con una differenza fondamentale: il filter riceve dei dati, li modifica e restituisce i dati modificati. WordPress usa la funzione apply_filters per far passare i dati attraverso tutte le funzioni filter agganciate. Ogni funzione filter deve restituire un valore perché altrimenti i dati diventano vuoti. Ad esempio, il filter the_content fa passare il contenuto del post attraverso tutte le funzioni agganciate prima della visualizzazione, permettendo ai plugin di aggiungere pulsanti di condivisione social, articoli correlati o annunci all'interno del contenuto.

Usare add_filter

La funzione add_filter ha una sintassi identica ad add_action: nome dell'hook, funzione di callback, priorità e numero di argomenti. La differenza fondamentale è che la funzione di callback deve ricevere almeno un argomento che rappresenta i dati da filtrare e deve restituire i dati modificati o originali. Se la tua funzione filter non restituisce un valore, i dati andranno persi e questo può rompere il sito. Testa sempre le funzioni filter per assicurarti che restituiscano il valore corretto anche nei casi limite.

I filter hook più comuni

• the_content: Filtra il contenuto del post prima della visualizzazione. I plugin di formattazione, gli shortcode e le modifiche al contenuto usano questo filter.
• the_title: Filtra il titolo del post. Usalo per aggiungere prefissi, suffissi o per formattare i titoli in modo programmatico.
• wp_mail: Filtra i parametri delle email prima dell'invio. Puoi modificare i destinatari, l'oggetto, il contenuto o le intestazioni delle email.
• login_redirect: Filtra l'URL a cui l'utente viene reindirizzato dopo il login. Usalo per redirect personalizzati in base al ruolo dell'utente.
• excerpt_length: Filtra la lunghezza del riassunto generato automaticamente. Il valore predefinito è 55 parole.
• upload_mimes: Filtra i tipi di file consentiti per l'upload. Usalo per aggiungere il supporto per SVG o altri formati.

Creare i propri hook

Action hook personalizzati

Quando sviluppi un plugin o un tema, creare i tuoi hook permette ad altri sviluppatori di estendere le tue funzionalità senza modificare il tuo codice. Inserisci chiamate a do_action nei punti in cui vuoi abilitare estensioni, ad esempio prima e dopo la visualizzazione di un modulo, prima del salvataggio dei dati o dopo l'elaborazione di un ordine. Dai un nome agli hook con il prefisso del tuo plugin per evitare conflitti con altri plugin, ad esempio myplugin_pre_save_data. Documenta gli hook disponibili con una descrizione di quando si attivano e quali argomenti passano.

Filter hook personalizzati

Usa apply_filters nei punti in cui vuoi abilitare la modifica dei dati. Ad esempio, se il tuo plugin genera un elenco di elementi, fai passare l'array di elementi attraverso un filter prima della visualizzazione. Altri sviluppatori possono agganciare un filter per aggiungere, rimuovere o modificare elementi. Per ogni filter documenta chiaramente il tipo di dati filtrato, il formato del valore di ritorno previsto e il contesto in cui il filter viene usato. Questo rende il tuo plugin piacevole da estendere e riduce la necessità di modifiche dirette.

Sviluppo di plugin con gli hook

Struttura del plugin

Ogni plugin WordPress inizia con un commento di intestazione che contiene nome del plugin, descrizione, versione, autore e licenza. Il file principale del plugin registra di solito gli hook nel costruttore della classe o in una funzione di inizializzazione. Organizza il codice in classi con metodi per ogni funzionalità e usa il costruttore per registrare tutti gli hook in un unico punto. Questo rende il codice leggibile e più facile da mantenere perché puoi vedere tutti gli hook in un solo posto.

Attivazione e disattivazione

WordPress fornisce hook speciali, register_activation_hook e register_deactivation_hook, che si attivano all'attivazione e alla disattivazione del plugin. Usa l'activation hook per creare tabelle del database, impostare le opzioni predefinite e pianificare i cron job. Usa il deactivation hook per ripulire i cron job pianificati e i dati temporanei. Per una rimozione completa dei dati alla cancellazione del plugin, crea un file uninstall.php che elimini le opzioni dal database, le tabelle personalizzate e i file caricati.

Best practice

Usa sempre i prefissi per i nomi di funzioni e classi per evitare conflitti con altri plugin. Verifica se un hook esiste prima di registrarlo per evitare errori. Usa has_action e has_filter per controllare se qualcuno è già agganciato a un hook specifico. Rimuovi gli hook con remove_action e remove_filter quando devi modificare il comportamento di un altro plugin o tema. La priorità è fondamentale quando si rimuove: devi usare la stessa priorità usata in fase di aggiunta.

Debug degli hook

Strumenti di debug

Il plugin Query Monitor è uno strumento indispensabile per il debug degli hook, che mostra tutti gli hook registrati, l'ordine di esecuzione e il tempo consumato da ciascun hook. La costante WP_DEBUG in wp-config.php abilita la visualizzazione di errori e avvisi PHP che aiutano a identificare i problemi con gli hook. Il plugin Debug Bar aggiunge un pannello nell'admin bar con informazioni su hook, query al database e uso della memoria. Per il debug avanzato, Xdebug con VS Code consente di impostare breakpoint all'interno delle funzioni di callback degli hook.

Errori comuni

L'errore più comune è una funzione filter che non restituisce un valore, con conseguente contenuto vuoto. Un altro errore comune è un numero di argomenti non corrispondente tra la registrazione dell'hook e la funzione di callback. Un ciclo infinito si verifica quando un filter modifica i dati in un modo che riattiva lo stesso filter. Usa una variabile statica o un flag per prevenire la ricorsione. Una priorità errata può far sì che la tua funzione non funzioni perché un hook precedente ha cambiato i dati in modo inatteso. Sui piani di hosting WordPress di BeoHosting abbiamo un ambiente ottimizzato per lo sviluppo di plugin, con supporto per gli strumenti di debug e memoria PHP sufficiente per catene di hook complesse.

Conclusione

Il sistema di hook di WordPress è un meccanismo potente ed elegante che consente un'estensione illimitata di WordPress. Gli action ti danno la possibilità di eseguire codice al momento giusto, mentre i filter consentono la modifica dei dati in qualsiasi punto del sistema. Comprendere gli hook è la chiave per il passaggio da utente a sviluppatore e apre la porta alla creazione di plugin e temi professionali. Inizia con gli hook più usati, sperimenta con la personalizzazione e costruisci gradualmente funzionalità più complesse. Se stai appena installando WordPress, consulta la nostra guida all'installazione.