Gli Hook di WordPress sono uno degli strumenti più importanti da avere nell’arsenale di uno sviluppatore WordPress. Sono il fondamento dello sviluppo dei plugin e dei temi di WordPress. Potete utilizzare i numerosi hook integrati in WordPress per ‘agganciare’ il Core di WordPress al proprio codice personalizzato e fare o modificare qualcosa.

Ci sono due tipi di hook in WordPress: Azioni e Filtri. Gli hook sono così comuni che anche lo stesso Core di WordPress li utilizza ampiamente. WordPress include anche un modo per definire i propri hook personalizzati, così che altri sviluppatori possano agganciarsi al vostro codice.

Imparare come funzionano le azioni, i filtri e gli hook personalizzati è essenziale per padroneggiare lo sviluppo di WordPress.

La prima metà di questo articolo tratta le basi dei hook di WordPress e spiega come funzionano, offrendo molteplici esempi. Nella seconda metà, imparerete come utilizzare gli hook per personalizzare WordPress, creare i propri hook personalizzati e utilizzarli per costruire i plugin estendibili.

Sembra eccitante? Cominciamo!

Cosa Sono gli Hook di WordPress?

Una pagina di WordPress è composta da tonnellate di funzioni e di richieste al database. Il Core, i plugin e il tema di WordPress lavorano insieme per produrre gli elementi della pagina, come il testo, le immagini, gli script e gli stili. Una volta completamente assemblato, il browser li mette tutti insieme e rende la pagina.

Gli hook di WordPress vi permettono di ‘agganciarvi’ a questo processo di costruzione in alcuni punti ed eseguire codice personalizzato. La funzione principale degli hook è quella di permettere di modificare o aggiungere funzionalità a WordPress senza toccare i file del Core.

Gli hook vi aiutano ad estendere WordPress con il vostro codice
Gli hook vi aiutano ad estendere WordPress con il vostro codice

La WordPress Plugin API offre le funzionalità degli hook di WordPress. Gli hook si utilizzano invocando alcune funzioni di WordPress chiamate Funzioni di Hook in specifiche istanze durante il processo di runtime di WordPress.

Utilizzando le funzioni di hook, potete raggruppare il codice personalizzato all’interno di una funzione di Callback e registrarlo con qualsiasi hook. Una volta registrata, questa callback verrà eseguita ovunque si trovi l’hook, consentendovi di estendere o sostituire le funzioni predefinite di WordPress.

La posizione dell’hook nel processo di esecuzione del codice è un fattore importante. Nelle prossime sezioni vi diremo di più sul suo significato.

I Due Tipi di Hooks di WordPress: Azioni e Filtri

WordPress dispone di due tipi di hook chiamati Azioni e Filtri. Le azioni consentono di fare qualcosa in determinati punti predefiniti del runtime di WordPress, mentre i filtri consentono di modificare i dati elaborati da WordPress e di restituirli con un return.

Le azioni dono definite nel codice di WordPress come segue:

do_action( 'action_name', [optional_arguments] );

La stringa action_name è il nome dell’azione. Potete specificare la variabile [optional_arguments] per passare altri argomenti alla funzione di callback. Se questo campo non viene specificato, il suo valore predefinito sarà vuoto.

Esempio: L’azione do_action( 'wp_head' ) può essere agganciata per eseguire codice personalizzato ogni volta che WordPress elabora l’header del sito. Questa azione non ha altri argomenti.

I filtri sono definiti nel codice di WordPress così:

apply_filters( 'filter_name', 'value_to_be_filtered', [optional_arguments] );

La stringa filter_name è il nome del filtro, la variabile value_to_be_filtered è il valore che deve essere filtrato e restituito, e la variabile [optional_arguments] può passare altri argomenti, proprio come avviene con le azioni.

Esempio: Il filtro apply_filters( 'admin_footer_text' , stringa $text ) può essere agganciato per modificare il testo visualizzato nel footer dell’area di amministrazione. A partire da WordPress 5.4, il suo valore predefinito mostrerà la frase Grazie per aver creato con WordPress. nel footer dell’area di amministrazione.

Di seguito, imparerete come agganciarvi alle azioni e ai filtri con molti esempi dal Core di WordPress.

Una volta agganciati, potete indirizzare il vostro codice da fare o personalizzare qualcosa sul vostro sito. Ad esempio, potete utilizzare gli hook per inviare un’email automatica dopo aver pubblicato un post, o caricare fogli di stile personalizzati per cambiare l’aspetto del vostro sito.

Gli hook di WordPress vi aiutano a interagire con il vostro sito web o a modificarlo
Gli hook di WordPress vi aiutano a interagire con il vostro sito web o a modificarlo

Il modo più semplice per capire gli hook è immaginare il vostro sito WordPress come una casa in costruzione.

Utilizzare gli hook è come utilizzare una gru per spostare avanti e indietro gli oggetti da costruzione. Gli oggetti che vengono trasferiti sono le Funzioni di Callback che contengono il vostro codice personalizzato. Questi elementi (o funzioni) possono aiutarvi a costruire o modificare la casa.

Esempio di hook all'azione 'wp_head' in WordPress
Esempio di hook all’azione ‘wp_head’ in WordPress

Le funzioni di callback possono essere normali funzioni PHP, funzioni WordPress predefinite o funzioni personalizzate da voi definite.

Possiamo trasportare determinati elementi solo su specifici vettori attaccati a particolari hook. Pertanto, le azioni possono essere agganciate solo alle Funzioni di Azione. Allo stesso modo, i filtri possono essere agganciati solo alle Funzioni di Filtro.

Mentre è noioso cambiare i ganci e i trasportatori su una gru, in WordPress è super semplice, dato che dispone di oltre 2.200 tipi di hooks predefiniti.

WordPress 5.1 ha 2200+ hook nativi
WordPress 5.1 ha 2200+ hook nativi (Fonte: Adam Brown)

Potete trovare hooks sparsi in tutto il Core di WordPress, e vi permettono di individuare la posizione esatta in cui volete agganciarvi e di eseguire il vostro codice personalizzato.

Hooks, Azioni e Filtri

Come da WordPress Plugin Handbook:

Gli hook sono un modo per un blocco di codice di interagire/modificare un altro blocco di codice… Ci sono due tipi di hook: Azioni e Filtri.

C’è una diffusa incoerenza nel modo in cui vengono utilizzati i termini Hook, Azione e Filtro. Alcune guide e tutorial li confondono con le funzioni ad essi associate. Una delle ragioni principali di questa confusione è la natura complessa del funzionamento dei hook.

Anche quando si guarda attentamente all’interno del Core di WordPress, si scopre che non c’è molta differenza tra l’aggiunta di azioni e filtri. Ecco il codice sorgente della funzione add_action() dal file wp-includes/plugin.php:

function add_action( $tag, $function_to_add, $priority = 10, $accepted_args = 1 ) {
    return add_filter( $tag, $function_to_add, $priority, $accepted_args );
}

La funzione add_action() si limita a richiamare la funzione add_filter() e ne restituisce il valore. Perché? Perché entrambi funzionano fondamentalmente allo stesso modo, tranne che per una differenza.

La funzione apply_filters() restituisce un valore che può cambiare i tipi di dati esistenti, mentre la funzione do_action() non restituisce nulla (valore NULL in PHP).

Se siete ancora confusi, non vi preoccupate! Una volta superata la prima metà di questo articolo, tutto sarà chiaro. Ci atterremo alla terminologia ufficiale del Codex di WordPress, perché è chiara, precisa e universale.

Per ora, familiarizzate con la routine degli hook illustrata di seguito.

La routine degli hook: Hook, funzioni di hooks e funzioni di callback
La routine degli hook: Hook, funzioni di hooks e funzioni di callback

Analizziamo le differenze tra Azioni e Hook.

Hook di WordPress
Azioni Filtri
Le azioni vengono utilizzate per eseguire funzioni personalizzate in un punto specifico durante l’esecuzione del Core di WordPress. I filtri vengono utilizzati per modificare o personalizzare i dati utilizzati da altre funzioni.
Le azioni sono definite/create dalla funzione do_action( 'action_name' ) nel codice di WordPress. I filtri sono definiti/creati dalla funzione apply_filters( 'filter_name', 'value_to_be_filtered' ) nel codice di WordPress.
Le azioni sono anche chiamate Action Hook. I filtri sono anche chiamati Filter Hook.
Le azioni possono essere agganciate solo alle funzioni di Azione. Ad es. add_action(), remove_action(). I filtri possono essere agganciati solo alle funzioni di Filtro. Ad es. add_filter(), remove_filter().
Le funzioni di azione non devono passare alcun argomento alle loro funzioni di callback. Le funzioni di filtro devono passare almeno un argomento alle loro funzioni di callback.
Le funzioni di azione possono eseguire qualsiasi tipo di compito, compreso il cambiamento del funzionamento di WordPress. Le funzioni di filtro esistono solo per modificare i dati trasmessi loro dai filtri.
Le funzioni di azione non dovrebbero restituire (return) nulla. Tuttavia, possono produrre un echo all’uscita o interagire con il database. Le funzioni di filtro devono restituire (return) le loro modifiche all’uscita. Anche se una funzione di filtro non cambia nulla, deve comunque restituire l’input non modificato.
Le azioni possono eseguire quasi tutto, purché il codice sia valido. I filtri dovrebbero funzionare in modo isolato, in modo da non avere effetti indesiderati.
Riepilogo: un’azione interrompe il regolare processo di esecuzione del codice per fare qualcosa con le informazioni che riceve, ma non restituisce nulla, e poi esce. Riepilogo: un filtro modifica le informazioni che riceve, le restituisce alla funzione di hook chiamante e altre funzioni possono utilizzare il valore che restituisce.

A volte, potete utilizzare un’azione o un filtro per raggiungere lo stesso obiettivo. Per esempio, se desiderate modificare il testo di un post, potete registrare una funzione di callback con l’azione publish_post e modificare il contenuto del post quando viene salvato nel database.

// define the callback function to change the text
function change_text_callback() { 
    // add the code to change text here
}

// hook in to the 'publish_post' action with the add_action() function
add_action( 'publish_post', 'change_text_callback' );

Oppure potete registrare un’altra funzione di callback con il filtro the_content per modificare il contenuto del post prima che venga visualizzato nel browser.

// define the callback function to modify the text
function change_text_another_callback( $content ) { 
    // add the code to change text here and then return it 
    return $filtered_content;
}

// hook in to 'the_content' filter with the add_filter() function
add_filter( 'the_content', 'change_text_another_callback');

Due approcci diversi con lo stesso risultato. Sapere quando usare l’uno rispetto all’altro è la chiave per essere un buon sviluppatore di WordPress.

Come Funzionano gli Hook di WordPress?

L’esempio della casa era abbastanza semplice per comprendere il funzionamento di base degli hook, ma non coglie la complessità del loro funzionamento. Soprattutto i concetti della posizione e della specificità degli hook.

Un esempio migliore potrebbe essere quello di immaginare di elaborare una pagina di WordPress come l’assemblaggio di un’auto. A differenza della produzione di un’auto, che richiede tempo, l’assemblaggio di una pagina web è quasi istantaneo.

Assemblare una pagina web è come assemblare un'auto
Assemblare una pagina web è come assemblare un’auto

Proprio come una macchina viene assemblata pezzo per pezzo in una moderna catena di montaggio, una pagina web di WordPress viene assemblata elemento per elemento dal server e dal client.

Il Core di WordPress è come il motore dell’auto, il telaio e altri elementi essenziali, che alimentano la funzionalità “core” del sito web.

Potete avere un sito web funzionale con il solo Core di WordPress, ma dov’è il divertimento? È necessario aggiungere funzionalità entusiasmanti al sito. È qui che entrano in gioco i plugin e i temi di WordPress, che utilizzano entrambi ampiamente gli hook.

Nell’esempio sopra riportato, ogni stazione numerata è come un hook all’interno del Core di WordPress. Ci sono due tipi di stazioni, come le azioni e i filtri. Ogni stazione include un tipo specifico di slot che accetta solo alcuni strumenti, come le funzioni di azione e le funzioni di filtro.

Tutte le stazioni sono posizionate ad intervalli frequenti per modularità ed efficienza.

In base alla richiesta effettuata in una particolare posizione, possiamo attaccare (o agganciare) l’utensile più appropriato per il lavoro in quella specifica stazione. Questi strumenti sono come le funzioni di callback utilizzate per interagire o modificare WordPress.

Alcuni strumenti possono alterare in modo significativo il funzionamento dell’auto, proprio come callback registrate alle azioni. Altri strumenti sono utilizzati solo per personalizzare l’aspetto dell’auto, come le callback registrate ai filtri.

L’utilizzo degli strumenti giusti nelle stazioni giuste è fondamentale per costruire un’auto di prim’ordine. Allo stesso modo, gli hook ci aiutano a personalizzare WordPress in base alle nostre specifiche esigenze.

Se si estende questa analogia, i plugin sono come un’aggiunta di utili elementi dell’auto come airbag, console di intrattenimento, sistema keyless remoto, ecc. (come quelli utili per migliorare le funzionalità di WooCommerce). I temi sono analoghi alla personalizzazione dell’estetica dell’auto, come il design generale, la verniciatura, i cerchioni, ecc. (ecco come personalizzare il vostro tema WordPress).

Dove Registrare gli Hook e le Loro Funzioni?

Sono due le modalità raccomandate per aggiungere hook in WordPress:

Per questo tutorial, iniziamo creando un plugin. Create una nuova cartella nella vostra directory /wp-content/plugins/.

Chiamo il mio plugin salhooks, ma potete chiamarlo come volete. Secondo le linee guida di WordPress, è necessario creare un file PHP con lo stesso nome (salhooks.php) all’interno della directory del plugin.

Aggiungete i seguenti campi di intestazione al file del vostro plugin per registrarlo in WordPress. Per saperne di più sui requisiti dell’intestazione del plugin, consultate il Codex di WordPress.

<?php

/*
Plugin Name:  Salhooks
Version    :  1.0
Description:  Demonstrating WordPress Hooks (Actions and Filters) with multiple examples.
Author     :  Salman Ravoof
Author URI :  https://www.salmanravoof.com/
License    :  GPLv2 or later
License URI:  https://www.gnu.org/licenses/gpl-2.0.html
Text Domain:  salhooks
*/

//=================================================
// Security: Abort if this file is called directly
//=================================================
if ( !defined('ABSPATH') ) { 
    die;
}

Salvate questo file e poi attivare il plugin nella bacheca di WordPress. Userò questo plugin all’interno di un’installazione locale di WordPress per dimostrare come funzionano gli hook.

Come nota a margine, è anche possibile modificare direttamente i file del Core di WordPress per registrare gli hook. Tuttavia, non è consigliabile, in quanto tutto il codice personalizzato verrà sovrascritto ogni volta che aggiornate WordPress. Per lo stesso motivo, non dovreste aggiungere gli hook all’interno del parent theme.

Utilizzare gli Hook WordPress

Un hook WordPress da solo non fa nulla. Sta solo seduto nel codice, in attesa che qualche funzione di hook lo attivi. Per utilizzare un hook, è necessario chiamare almeno altre 2 funzioni.

Per prima cosa, è necessario registrare l’hook con una funzione di hook e fare riferimento ad una funzione di callback al suo interno. E poi bisogna definire la funzione di callback di cui si è parlato prima nella funzione di hook. WordPress eseguirà questa funzione di callback ogni volta che l’hook viene attivato.

L’ordine in cui si definiscono queste funzioni non ha importanza, ma è una buona idea metterle vicine.

Le azioni e i filtri hanno funzioni di hook distinte. D’ora in avanti, indichiamoli come Funzioni di Azione e Funzioni di Filtro. Come vedrete, hanno i loro requisiti di sintassi e i loro parametri.

Agganciare un’Azione

Le azioni forniscono un modo per eseguire codice personalizzato in un punto particolare dell’esecuzione del Core di WordPress, dei plugin o dei temi.

La Action Function add_action()

Potete registrare una funzione di callback su un’azione seguendo questi passaggi:

  1. Definite una funzione di Callback con il vostro codice al suo interno. Questa funzione di callback verrà eseguita quando qualsiasi azione su cui è registrata viene eseguita durante l’esecuzione del codice di WordPress.
  2. Agganciate la funzione di callback all’azione desiderata con la funzione add_action(). Come per il codice WordPress, la funzione add_action() deve passare almeno due parametri:
    • Nome dell’azione a cui agganciarsi.
    • Nome della funzione di callback che verrà eseguita quando l’azione viene attivata.
  1. La funzione add_action() accetta anche due parametri opzionali per l’impostazione della priority e del numero di argomenti. Li analizzeremo entrambi più avanti.

È buona regola nominare i parametri della funzione di callback nel modo più vicino possibile ai parametri passati dalla funzione di hook.

Vediamo un esempio di utilizzo della funzione add_action().

// define the callback function, the arguments are optional
function example_callback( $arg1, $arg2 ) {
    // make your code do something with the arguments
}

// hook the callback function to the 'example_action'
add_action( 'example_action', 'example_callback', [priority], [no_of_args] );

// 'priority' and 'number of arguments' are optional parameters

Esempio di Aggancio di un’Azione

WordPress dispone di un’azione nativa chiamata init che si attiva dopo che WordPress ha finito di caricare e autenticare l’utente, ma prima che vengano inviati gli header. Molti plugin utilizzano questo hook come punto di partenza per istanziare il loro codice, dato che quasi tutte le principali funzionalità di WordPress hanno finito il caricamento nel momento in cui questa azione viene eseguita da WordPress.

WordPress dispone anche di un’azione simile chiamata admin_init. Questa si attiva quando la schermata admin viene inizializzata, mentre l’azione init si attiva solo dopo che WordPress ha terminato il caricamento.

Eseguiamo un codice personalizzato per eseguire un echo di un semplice messaggio durante l’esecuzione dell’azione init. Ecco come fare:

function custom_callback_function(){
    // add your custom code here to do something
    echo 'I will be fired on WordPress initialization';
}
add_action( 'init', 'custom_callback_function' );

Potete vedere il messaggio che viene ripetuto nell’angolo in alto a sinistra della mia installazione locale di WordPress.

Non è così bello, ma è un ottimo inizio!
Non è così bello, ma è un ottimo inizio!

Trovare le Azioni Supportate da WordPress

WordPress prevede azioni ogni volta che fa qualcosa, come l’accesso di un utente o la pubblicazione di un nuovo post. Potete trovare un elenco completo di tutte le azioni eseguite da WordPress nella pagina Plugin API/Action Reference.

C'è un'azione per quasi tutti gli usi
C’è un’azione per quasi tutti gli usi

Il Codex ha suddiviso tutte le azioni ivi elencate in varie categorie e le ha disposte dalla prima all’ultima nell’ordine di esecuzione di WordPress.

Nella maggior parte dei casi, molte di queste azioni non fanno nulla, perché non c’è nulla che vi è agganciato. Ma se ne avete bisogno, sono lì perché possiate utilizzarle.

Vi sentite un po’ sopraffatti da tutte le azioni? È naturale. Man mano che si acquisisce maggiore esperienza e si passa attraverso il codice sorgente del Core di WordPress, diventerà più facile trovare l’hook perfetto per le vostre esigenze. Basta eseguire una ricerca per il termine “do_action” e troverete un sacco di azioni a cui agganciarvi.

Parametri aggiuntivi per add_action()

La funzione add_action() può accettare altri due parametri: uno per impostare la priority e l’altro per impostare il numero di argomenti. Anche se sono opzionali, se usati correttamente, possono essere super utili.

Priority

Il primo parametro aggiuntivo supportato dalla funzione add_action() imposta la priority. Questo parametro può essere solo un numero intero positivo. Più basso è il numero di priorità, prima la funzione verrà eseguita. Se non lo si specifica, il valore predefinito è 10.

Per vedere come funziona, registriamo tre funzioni di callback all’azione init, ma ognuna con priorità diverse.

// priority is set to 9, which is lower than 10, hence it ranks higher
add_action( 'init', 'i_am_high_priority', 9 );

// if no priority is set, the default value of 10 will be used
add_action( 'init', 'i_am_default_priority');

// priority is set to 11, which is higher than 11, hence it ranks lower
add_action( 'init', 'i_am_low_priority', 11 );

Negli esempi sopra riportati, la funzione di callback con il numero di priorità più basso sarà eseguita per prima e quella con il numero più alto sarà eseguita per ultima. Se le priorità sono le stesse, allora saranno eseguite nell’ordine in cui le avete registrate.

La priorità gioca un ruolo importante quando più funzioni di callback sono registrate su un singolo hook. Per evitare risultati inaspettati, potete impostare una priorità per ogni funzione di callback, in modo che si attivino nell’ordine desiderato.

Numero di Argomenti

Di default, qualsiasi funzione di callback registrata tramite la funzione add_action() accetterà un solo argomento. Tuttavia, a volte potrebbe essere necessario passare dati extra alla funzione di callback.

Per questo motivo, la funzione add_action() accetta un parametro opzionale per l’impostazione del numero di argomenti.

Un ottimo esempio per dimostrarlo è l’azione comment_post. Questa azione viene eseguita subito dopo che WordPress aggiunge un commento al database. Se non si imposta il parametro del numero di argomenti, alla funzione di callback sarà passato un singolo valore, che in questo caso sarà il comment_ID.

// register the hook with 'priority' and 'number of arguments' parameters
add_action( 'comment_post', 'show_message_function', 10, 3 );

// define the callback function
function show_message_function( $comment_ID, $comment_approved, $commentdata ) {
    // check whether a comment is approved with the second parameter
    if( 1 === $comment_approved ){
        // runs the code only if the comment is approved
    }
}

Se si imposta il parametro del numero di argomenti a 3, come nell’esempio precedente, la funzione dell’azione passerà tre valori: comment_ID, comment_approved e commentdata.

WordPress imposta il valore di comment_approved a 1 per i commenti approvati, 0 se non approvati e ‘spam‘ se il commento è contrassegnato come spam.

La variabile commentdata è un array che include tutti i dati del commento, come il nome dell’autore del commento, l’indirizzo email, il sito web e il contenuto del commento stesso. Potete consultare il Codex di WordPress per trovare tutte le coppie chiave-valore incluse nell’array ‘commentdata’.

Potete avere tutti gli argomenti che volete, ma la funzione callback e la funzione add_action() devono specificare lo stesso numero di argomenti.

Si può fare di più con il proprio codice passando ulteriori parametri alla funzione di callback. Ad esempio, potete verificare se un commento è approvato o meno e inviare automaticamente il testo del commento all’amministratore via email, se questo è approvato. Non è possibile farlo senza specificare gli argomenti aggiuntivi, perché la funzione di callback non avrà accesso ai dati del comment_content.

Se non volete impostare la priorità, ma volete solo cambiare il numero di argomenti, dovrete comunque impostare una priorità. Basta usare il suo valore predefinito (cioè 10).

Come il Core di WordPress Utilizza le Azioni

Lo stesso Core di WordPress utilizza molte delle sue azioni native per eseguire varie funzioni.

Prendete ad esempio l’azione wp_head. Viene attivata quando WordPress emette la sezione di testa delle pagine web (il codice che va tra <head> e </head>).

La maggior parte delle funzioni di azione del Core di WordPress relative all’hook wp_head si trovano nel file wp-includes/default-filters.php. Ho esaminato il codice e ho compilato una lista di tutte le funzioni add_action() che richiamano l’azione wp_head.

add_action( 'wp_head', 'rest_output_link_wp_head', 10, 0 );
add_action( 'wp_head', '_wp_render_title_tag', 1 );
add_action( 'wp_head', 'wp_enqueue_scripts', 1 );
add_action( 'wp_head', 'wp_resource_hints', 2 );
add_action( 'wp_head', 'feed_links', 2 );
add_action( 'wp_head', 'feed_links_extra', 3 );
add_action( 'wp_head', 'rsd_link' );
add_action( 'wp_head', 'wlwmanifest_link' );
add_action( 'wp_head', 'adjacent_posts_rel_link_wp_head', 10, 0 );
add_action( 'wp_head', 'locale_stylesheet' );
add_action( 'wp_head', 'noindex', 1 );
add_action( 'wp_head', 'print_emoji_detection_script', 7 );
add_action( 'wp_head', 'wp_print_styles', 8 );
add_action( 'wp_head', 'wp_print_head_scripts', 9 );
add_action( 'wp_head', 'wp_generator' );
add_action( 'wp_head', 'rel_canonical' );
add_action( 'wp_head', 'wp_shortlink_wp_head', 10, 0 );
add_action( 'wp_head', 'wp_custom_css_cb', 101 );
add_action( 'wp_head', 'wp_site_icon', 99 );
add_action( 'wp_head', 'wp_no_robots' );

Sono un sacco di funzioni di callback agganciate ad una sola azione. Impostare la priority in questo caso è fondamentale per assicurarsi che le più importanti funzioni agganciate funzionino per prime.

Nell’esempio precedente, il caricamento degli script con la funzione di callback wp_enqueue_scripts() è più importante (priority = 1) che caricare i meta tag delle icone del sito con la funzione di callback wp_site_icon() (priority = 99).

Altre Action Function

Se add_action() è la action function più utilizzata, ce ne sono molte altre che sono ugualmente utili. Vediamo come funzionano.

Questa action function controlla se un’azione è stata agganciata. Accetta due parametri. Il primo è il nome dell’azione. Il secondo parametro è opzionale ed è il nome della funzione di callback.

has_action( 'action_name', 'function_to_check' );

Se si specifica solo il primo parametro, esso restituisce true se una qualsiasi funzione è agganciata al parametro action_name.

Ma se si specifica anche il secondo parametro, questo restituirà false se la funzione di callback specificata non è registrata all’azione menzionata.

Se però trova la funzione di callback collegata all’action hook, restituirà la priority (un numero intero) impostata per quella funzione su questo action hook.

Abbiamo già incontrato questa action function in passato. WordPress la utilizza per definire tutte le sue azioni predefinite, consentendo ad altre funzioni di agganciarvisi. Proprio come WordPress, anche voi potete utilizzare la funzione do_action() per creare una nuova azione personalizzata specificando come parametro il nome di una nuova azione.

do_action( 'action_name', [argument1], [argument2] );

La sola dichiarazione di questa funzione non servirà a nulla da sola. Ma rimarrà nel codice, in attesa che venga attivata da altre action function. Il passaggio di qualsiasi argomento aggiuntivo è opzionale, ma è importante se si desidera che le funzioni di callback le utilizzino.

Questa action function è identica a do_action(), tranne che per una differenza. Qualsiasi parametro passato tramite la funzione deve essere un array. Quando si hanno molti argomenti da passare o i propri argomenti sono già in un array, questa funzione è super utile.

// here's an example array
$arguments_array = array( 'arg_1', 'foo', true, 'arg_4' );

do_action_ref_array( 'example_action', $arguments_array );

Dato che gli array PHP sono una mappa ordinata, assicuratevi che gli argomenti che passate siano nel giusto ordine.

Un esempio dell’utilizzo di questa action function è l’azione admin_bar_menu. Può essere agganciata per aggiungere, manipolare o rimuovere i vari elementi della barra di amministrazione. Tutti gli elementi della barra di amministrazione sono definiti come elementi di un array.

Si può invocare questa action function se si vuole contare il numero di volte che un’azione viene attivata.

did_action( 'action_name' );

Questa funzione restituisce un valore intero.

La funzione did_action() è estremamente utile quando si vuole eseguire una funzione di callback solo la prima volta che un’azione viene eseguita e mai più.

function example_callback_function() {
    if( did_action( 'example_action' ) === 1 ) {
    // checks if the 'example_action' hook is fired once, and only runs then, and never again!
    }
}
add_action('example_action', 'example_callback_function');

Questa action function rimuove una funzione di callback agganciata all’azione specificata. Ad esempio, potete utilizzare questa funzione per rimuovere le funzioni predefinite di WordPress agganciate alle azioni native e sostituirle con le vostre.

remove_action( 'action_name', 'function_to_be_removed', [priority] );

Ci sono alcuni prerequisiti per chiamare la funzione remove_action():

  1. I parametri function_to_be_removed e priority devono essere gli stessi utilizzati originariamente nella funzione add_action().
  2. Non è possibile richiamare direttamente la funzione remove_action(). È necessario chiamarla dall’interno di un’altra funzione.
  3. Se la funzione di callback è registrata da una classe, la sua rimozione ha altri requisiti. Per maggiori informazioni, potete consultare la documentazione del Codex di WordPress.
  4. Non è possibile rimuovere la funzione di callback prima che sia registrata o dopo che sia stata eseguita.

Ecco un esempio di come WooCommerce utilizza questa action function per rimuovere la miniatura predefinita del prodotto nella pagina principale del negozio.

remove_action( 'woocommerce_before_shop_loop_item_title', 'woocommerce_template_loop_product_thumbnail', 10 );

Questa action function rimuove tutto ciò che è agganciato ad un’azione. Il parametro priority è opzionale.

remove_all_actions( 'action_name', [priority] );

Ricordate che questa funzione non può essere richiamata dall’azione da cui volete cancellare le funzioni di callback. Ciò causerebbe un loop infinito. Per eseguire questa funzione senza errori, potete agganciarvi ad un’azione che è stata attivata in precedenza.

Questa action function controlla se l’azione specificata viene eseguita o meno. Essa restituisce un valore booleano (true o false).

// check whether the 'action_name' action is being executed
if ( doing_action( 'action_name' ) ) {
    // execute your code here
}

Potete lasciare vuoto il parametro action_name per verificare se una qualsiasi azione viene attivata. In questo caso, restituirà true.

// check if any action is running and do something
if ( doing_action() ) {
    // the code here is run when any action is fired
}

Esempio di Azione 1: Mostrare un Messaggio di Manutenzione ai Visitatori del Sito

A volte, è meglio mettere il sito offline e metter su una pagina in manutenzione. Fortunatamente, WordPress fornisce un modo semplice per farlo.

// show a maintenance message for all your site visitors
add_action( 'get_header', 'maintenance_message' );
function maintenance_message() {
    if (current_user_can( 'edit_posts' )) return;
    wp_die( '<h1>Stay Pawsitive!</h1><br>Sorry, we\'re temporarily down for maintenance right meow.' );
}

Analizziamo il codice ad ogni passaggio:

  • get_header è un’azione che viene attivata prima che venga caricato il template file dell’header del sito. È un’azione perfetta a cui agganciarsi se si vuole interrompere il caricamento del sito principale.
  • Ci agganciamo all’azione get_header utilizzando la funzione add_action() con la funzione di callback maintenance_message().
  • Definiamo la funzione di callback maintenance_message().
  • current_user_can( 'edit_posts' ) è una funzione di test delle capacità dell’utente che controlla se l’utente corrente è registrato e può modificare i messaggi. Ogni utente registrato su un sito WordPress, ad eccezione di quelli con ruoli di Subscriber, ha la possibilità di modificare i messaggi. Ci sono altri modi efficaci per eseguire questo controllo, ma qui ci atterremo a questo semplice metodo.
  • Utilizziamo la funzione predefinita wp_die() per interrompere correttamente l’esecuzione di WordPress e visualizzare una pagina HTML con un messaggio di errore. Potete utilizzare la sintassi HTML nel parametro del messaggio di errore per formattarlo.

Dopo aver salvato il codice nel mio plugin personalizzato, ho caricato la mia installazione locale di WordPress in modalità di navigazione anonima. La pagina Under Maintenance è stata caricata con successo!

Mostrare un messaggio di errore ai visitatori del sito
Mostrare un messaggio di errore ai visitatori del sito

Se ho effettuato l’accesso, il sito si carica regolarmente non appena si supera il test di capacità dell’utente. Ora è possibile continuare a lavorare per sistemare il sito mentre ai visitatori regolari viene mostrata questa pagina.

Esempio di Azione 2: Nascondere le Voci del Menu della Bacheca per gli Utenti non Amministratori

Se si gestisce un blog con più autori o si gestisce un sito per i propri clienti, potrebbe essere necessario nascondere alcuni menu di amministrazione dalla bacheca di WordPress per gli utenti non amministratori. È possibile farlo agganciandosi all’azione admin_menu.

// remove specific dashboard menus for non-admin users
add_action( 'admin_menu', 'hide_admin_menus' );
function hide_admin_menus() {
    if (current_user_can( 'create_users' )) return;
    if (wp_get_current_user()->display_name == "Salman") return; 
    remove_menu_page( 'plugins.php' ); 
    remove_menu_page( 'themes.php' ); 
    remove_menu_page( 'tools.php' ); 
    remove_menu_page( 'users.php' ); 
    remove_menu_page( 'edit.php?post_type=page' ); 
    remove_menu_page( 'options-general.php' );
}

Ecco una spiegazione passo passo del frammento di codice qui sopra:

  • admin_menu è un’azione che si attiva prima che il menu admin si carichi nell’area di amministrazione di WordPress.
  • Ci agganciamo all’azione admin_menu utilizzando la funzione add_action() con la funzione di callback hide_admin_menus().
  • La funzione di callback hide_admin_menus() definisce la logica del codice. Viene eseguita ogni volta che l’azione admin_menu si attiva.
  • All’interno della funzione di callback, la funzione current_user_can( 'create_users' ) controlla se l’utente registrato è un amministratore. Poiché solo gli amministratori del sito hanno la capadità create_user, la funzione termina con una dichiarazione return se l’utente è un amministratore.
  • La funzione wp_get_current_user() di WordPress recupera l’oggetto utente corrente. Con questa funzione, possiamo verificare se l’utente registrato ha un particolare display_name. Questa è una linea opzionale, nel caso in cui vogliate evitare che alcuni utenti non admin vengano bloccati a causa di questa funzione di callback.
  • La funzione remove_menu_page() di WordPress rimuove i menu di amministrazione di primo livello. Nel codice dell’esempio di cui sopra, vengono rimossi i seguenti menu di amministrazione: Plugin, Temi, Strumenti, Utenti, Pagine e Opzioni.

Dopo aver salvato il file del plugin, ecco un’istantanea del cruscotto di WordPress con un amministratore connesso.

Il cruscotto di amministrazione predefinito di WordPress
Il cruscotto di amministrazione predefinito di WordPress

Ed ecco una schermata del cruscotto di WordPress con un utente non amministratore connesso.

Nascondere le voci sensibili del menu di amministrazione agli utenti non amministratori
Nascondere le voci sensibili del menu di amministrazione agli utenti non amministratori

Questa soluzione nasconde dalla bacheca di WordPress solo le voci del menu di amministrazione specificate. Tutti gli utenti possono comunque accedervi inserendo gli URL dei menu nel loro browser.

Per impedire ad alcuni ruoli utente di accedere a menu specifici, è necessario modificare le loro capacità.

Agganciare un Filtro

I filtri offrono un modo per modificare i dati utilizzati da altre funzioni di WordPress attraverso vostro codice personalizzato. A differenza delle azioni, le funzioni agganciate ai filtri devono restituire un valore.

La Funzione Filtro add_filter()

Potete agganciare una funzione di callback ad un filtro seguendo questi passaggi:

  1. Definire una funzione di Callback che venga eseguita quando WordPress attiva il filtro. Le funzioni di callback per i filtri devono avere specificato almeno un argomento, in quanto tutti i filtri passano almeno un valore alle loro funzioni di callback.
  2. Registrare la funzione di calback su un filtro con la funzione add_filter(). Il filtro si occuperà di invocare la funzione callback. Come per riportato nel Codex di WordPress, la funzione add_filter() richiede che vengano passati almeno due parametri:
    • Nome del filtro da agganciare.
    • Nome della funzione di callback che verrà eseguita all’attivazione del filtro.
  1. La funzione add_filter() accetta anche due ulteriori parametri opzionali per l’impostazione della priorità e del niumero di argomenti. Questi parametri funzionano allo stesso modo della funzione add_action().

Ecco un esempio di come utilizzare la funzione add_filter() per agganciare una funzione di callback ad un filtro.

// define the filter callback function with at least one argument passed
// the number of arguments that you can pass depends on how the filter is defined
function filter_callback_function( $arg1, $arg2 ) {
    // make your code do something with the arguments and return something
    return $something;
}

// now hook the callback function to the 'example_filter'
add_filter( 'example_filter', 'filter_callback_function', [priority], [no_of_args] );

// '10' is the default priority set for the callback function
// and '1' is the default number of arguments passed

Esempio di Aggancio di un Filtro

WordPress dispone di un filtro chiamato login_message che permette di filtrare il messaggio visualizzato nella pagina di login al di sopra del modulo di accesso. Il valore restituito da questo filtro può avere un markup HTML.

Agganciamoci al filtro login_message e modifichiamo il messaggio visualizzato nella schermata di login.

// show a custom login message above the login form
function custom_login_message( $message ) {
    if ( empty( $message ) ) {
        return "<h2>Welcome to Let's Develop by Salman Ravoof! Please log in to start learning.</h2>";
    } 
    else {
        return $message;
    }
}
add_filter( 'login_message', 'custom_login_message' );

La dichiarazione if-else presente nella funzione di callback controlla se il messaggio di login è già impostato, per lo più da un altro plugin o da un tema. In questi casi, la funzione di callback restituisce il valore originale senza modifiche. Questo è un modo per evitare conflitti con altri temi o plugin.

Il messaggio viene visualizzato sopra il modulo di login nella pagina di login di WordPress.

Visualizzazione di un messaggio di login personalizzato sopra il modulo di accesso
Visualizzazione di un messaggio di login personalizzato sopra il modulo di accesso

È possibile personalizzare l’aspetto di tutti gli elementi della pagina di login, inserendo fogli di stile personalizzati. In questo modo potrete personalizzare completamente la vostra pagina di accesso predefinita di WordPress.

Imparerete come caricare fogli di stile personalizzati utilizzando le azioni descritte nella sezione “Personalizzare la Pagina di Accesso di WordPress con gli Hook”.

Trovare i Filtri Supportati da WordPress

Ovunque WordPress elabori o modifichi dati, è quasi certamente possibile trovare un filtro cui agganciarsi per modificarli. Pensate ai filtri come a un’interfaccia tra il database di WordPress e il browser.

Un elenco esaustivo di tutti i filtri supportati da WordPress è disponibile nella pagina Plugin API/Filter Reference.

WordPress fornisce una varietà di filtri cui agganciarsi
WordPress fornisce una varietà di filtri cui agganciarsi

Tutti i filtri elencati sono suddivisi in più categorie e disposti dall’alto verso il basso nell’ordine di esecuzione di WordPress.

Se volete trovare dei filtri cui agganciarvi nel codice sorgente di WordPress, effettuate una ricerca del termine “apply_filters” e otterrete tonnellate di risultati. Anche la WordPress Code Reference è un ottimo posto per cercare tutto ciò che è incluso in WordPress, tra cui le azioni e i filtri.

Come il Core di WordPress Utilizza i Filtri

Lo stesso Core di WordPress utilizza molti dei suoi filtri incorporati per modificare i dati utilizzati dalle sue varie funzioni.

Si consideri ad esempio il filtro the_content. Questo filtra i contenuti dopo che sono stati recuperati dal database e prima che vengano visualizzati dal browser.

Proprio come avviene per le azioni, potete trovare la maggior parte delle filter function del Core di WordPress relative all’hook the_content nel file wp-includes/default-filters.php.

Ecco un elenco di tutte le funzioni add_filter() del Core che si agganciano al filtro the_content:

add_filter( 'the_content', 'do_blocks', 9 );
add_filter( 'the_content', 'wptexturize' );
add_filter( 'the_content', 'convert_smilies', 20 );
add_filter( 'the_content', 'wpautop' );
add_filter( 'the_content', 'shortcode_unautop' );
add_filter( 'the_content', 'prepend_attachment' );
add_filter( 'the_content', 'wp_make_content_images_responsive' );
add_filter( 'the_content', 'do_shortcode', 11 ); // AFTER wpautop(). 

Si noti la priority specificata per alcune funzioni di callback.

Ad esempio, la funzione do_blocks() analizza qualsiasi blocco dinamico nel contenuto del post e lo visualizza nuovamente per renderlo compatibile con il nuovo editor di blocchi di WordPress. Viene specificata una priority più alta rispetto a quella predefinita (10) per assicurarsi che il contenuto sia pronto per il blocco prima che altre funzioni vengano eseguite.

La funzione convert_smilies() è impostata per funzionare con una priority inferiore, dato che il suo compito è quello di convertire gli smileys di testo in sprite di immagini. Ha senso, quindi, che venga eseguita alla fine, dopo aver filtrato tutto il contenuto del post.

Fatto curioso: gli shortcode sono un sottoinsieme di filtri. Prendono l’input dal codice dello shortcode, lo elaborano e poi vi restituiscono l’output. Potete saperne di più sugli shortcode in questa guida agli shortcode di WordPress.

Altre Filter Function

Mentre add_filter() è la filter function più utilizzata, ci sono molte altre utili funzioni filtro. Analizziamole tutte in modo approfondito.

Questa funzione controlla se il filtro specificato è agganciato da una qualsiasi funzione. Accetta due parametri. Il primo parametro è per l’inserimento del nome del filtro. Il secondo parametro è opzionale e serve per inserire il nome della funzione di callback.

has_filter( 'filter_name', 'function_to_check' );

Se si specifica solo il primo parametro, questo restituirà true se il filter_name è agganciato a una qualsiasi funzione.

Tuttavia, se si specificano entrambi i parametri, allora restituirà false se la funzione di calback specificata non è registrata sul filtro dato. Se trova la funzione di callback registrata sul filtro, allora restituirà la priority (un numero intero) impostata per quella funzione su questo filtro.

Una possibile applicazione della funzione has_filter() è quella di verificare se un filtro è già stato agganciato e, in base a questo, procedere con l’esecuzione del codice.

// check to see if 'the_content' filter has been hooked
if ( ! has_filter( 'the_content' ) {
    // hook the filter if and only if it hasn't been hooked before
    add_filter( 'the_content', 'modify_the_content' );
}

Questa filter function è come la action function do_action(). Qualsiasi funzione di callback agganciata a questo filtro verrà eseguita ovunque questa funzione si trovi nel codice di WordPress.

Potete anche utilizzare questa funzione per creare un nuovo filtro personalizzato specificando il nome e il valore del filtro come parametri.

apply_filters( 'filter_name', 'value_to_filter', [argument1], [argument2] );

Non dimenticate di specificare eventuali argomenti aggiuntivi se volete trasmetterli alle vostre funzioni di callback. La maggior parte dei filtri utilizza un solo argomento, quindi è facile perdere l’occasione di definire gli argomenti aggiuntivi.

Questa funzione è come la funzione apply_filters(), tranne per il fatto che tutti gli argomenti che accetta sono raggruppati in un array.

// an example array
$arguments_array = array( 'some_value', 'foo', false, 'another_value' );

apply_filters_ref_array( 'example_filter', $arguments_array );

Questa filter function può essere utile quando si hanno molti argomenti da passare o se tutti sono già in un array. Assicuratevi che gli argomenti all’interno dell’array siano nel giusto ordine.

Questa funzione filtro recupera il nome del filtro o dell’azione in esecuzione. Non è necessario specificare alcun parametro poiché viene eseguito all’interno della funzione di callback.

Ecco un esempio del suo utilizzo:

function example_callback() {
    echo current_filter(); // 'the_title' will be echoed
    return
}
add_filter( 'the_title', 'example_callback' );

Nonostante il suo nome, questa funzione può recuperare il nome sia delle azioni che dei filtri.

Questa funzione rimuove la funzione di callback collegata al filtro specificato. Funziona esattamente come la funzione remove_action(). Si può utilizzare per cancellare le funzioni predefinite di WordPress registrate su un filtro specifico e, se necessario, sostituirle con le proprie funzioni.

remove_filter( 'filter_name', 'function_to_be_removed', [priority] );

Per sganciare una funzione di callback agganciata ad un filtro, i parametri di function_to_be_removed e di priority devono essere identici agli argomenti utilizzati quando si aggancia la funzione di callback.

Se il filtro è stato aggiunto dall’interno di una classe, cosa che di solito avviene quando vengono aggiunti dai plugin, allora è necessario accedere alla variabile della classe per rimuovere il filtro.

// access the class variable first, and then remove the filter through it
global $some_class;

remove_filter( 'the_content', array($some_class, 'class_filter_callback') );

Vediamo un ottimo esempio di remove_filter() in azione.

Il plugin WooCommerce utilizza la funzione di chiamata wc_lostpassword_url() agganciata al suo filtro lostpassword_url per reindirizzare i tentativi “Lost Your Password? ” degli utenti.

Basta un clic su quel link per accedere a una pagina del frontend personalizzata con l’URL /my-account/lost-password. Senza questo filtro, gli utenti sarebbero indirizzati all’URL standard di login di WordPress all’indirizzo /wp-login.php.

Supponete di voler ripristinare questa funzionalità e inviare i vostri utenti alla pagina di recupero password predefinita o ad una pagina diversa. Potete rimuovere questa funzione di callback in questo modo:

remove_filter( 'lostpassword_url', 'wc_lostpassword_url', 10 ); 

Questa funzione filtro rimuove tutte le funzioni di callback registrate su un filtro.

remove_all_filters( 'filter_name', [priority] );

È simile alla funzione remove_all_actions().

Il popolare plugin Advanced Excerpts utilizza questa funzione per rimuovere tutte le funzioni predefinite agganciate ai filtri the_excerpt e get_the_excerpt. Dopo aver fatto questo, aggancia la propria funzione di callback al filtro.

// Ensure our filter is hooked, regardless of the page type 
if ( ! has_filter( 'get_the_excerpt', array( $advanced_excerpt, 'filter_excerpt' ) ) ) {
    remove_all_filters( 'get_the_excerpt' ); 
    remove_all_filters( 'the_excerpt' ); 
    add_filter( 'get_the_excerpt', array( $advanced_excerpt, 'filter_excerpt' ) );
}

Questa funzione controlla se il filtro specificato viene eseguito in quel momento.

if ( doing_filter( 'save_post' ) ) {
    // run your code here
}

Restituisce un valore booleano (true o false).

Si dovrebbe notare la differenza tra questa funzione e la funzione current_filter(), che restituisce il nome del filtro o dell’azione in esecuzione (una stringa).

Esempio di Filtro 1: Aggiungere un Filtro delle Volgarità per i Commenti

La gestione di tutti i commenti sul vostro sito WordPress può essere un procedura macchinoso. Il filtro comment_text consente di impostare delle regole per modificare i commenti prima che vengano stampati sul display.

Commenti non filtrati con volgarità evidenziate
Commenti non filtrati con volgarità evidenziate

Potete istruire WordPress in modo che rimuova automaticamente eventuali imprecazioni prima che vengano visualizzate ai visitatori del sito. Diamoci da fare.

// hook into the 'comment_text' filter with the callback function
add_filter( 'comment_text', 'the_profanity_filter' );

// define a callback function to filter profanities in comments 
function the_profanity_filter( $comment_text ) {
    // define an array of profane words and count how many are there 
    $profaneWords = array('fudge', 'darn', 'pickles', 'blows', 'dangit');
    $profaneWordsCount = sizeof($profaneWords);
    
    // loop through the profanities in $comment_text and replace them with '*'
    for($i=0; $i < $profaneWordsCount; $i++) {
        $comment_text = str_ireplace( $profaneWords[$i], str_repeat('*', strlen( $profaneWords[$i]) ), $comment_text );
    } 
    
    return $comment_text;
}

Ecco un’analisi del codice riga per riga:

  • comment_text è un filtro che permette di modificare il testo di un commento prima che il browser lo visualizzi. Potete registrare la vostra funzione di callback per filtrarne l’output.
  • La funzione add_filter() permette di agganciarsi al filtro comment_text e di collegarvi una funzione di callback.
  • the_profanity_filter() è il nome della funzione di callback. Accetta solo un parametro, che è una stringa contenente il testo del commento. Definite questa funzione personalizzata con la logica di codice appropriata.
  • Memorizza tutte le parole volgari in un array PHP chiamato profaneWords. A questo array si possono aggiungere tutte le parole che desiderate. Memorizzo la dimensione di questo array nella variabile profaneWordsCount con l’aiuto della funzione PHP sizeof().
  • Esamina tutte le parole volgari e utilizza la funzione str_ireplace() predefinita di PHP per sostituire qualsiasi parola volgare corrispondente con i simboli *. Dato che si tratta di una funzione di sostituzione delle stringhe che non distingue tra maiuscole e minuscole, non vi dovete preoccupare della capitalizzazione. Scopri i Diversi Modi per Eseguire un “Ricerca e Sostituzione“.
  • return restituisce il testo del commento filtrato.

Salvate le modifiche nel file del vostro plugin personalizzato e ricaricate qualsiasi post con i commenti. Tutte le parole che avete incluso nell’array profaneWords dovrebbero ora essere sostituite con i simboli ‘*‘.

Sostituire le parole volgari nei commenti con i simboli '*'.
Sostituire le parole volgari nei commenti con i simboli ‘*’.

I commenti originali saranno ancora disponibili così come sono nel database. Questo filtro modifica il testo del commento solo prima che venga inviato al frontend.

Il commento originale sul backend del sito
Il commento originale sul backend del sito

Una volta agganciati al filtro giusto, potete fare un sacco di cose interessanti.

Ad esempio, potete anche utilizzare il filtro comment_text per rimuovere eventuali URL da tutti i commenti (assicuratevi di leggere questa guida approfondita su come bloccare i commenti spam in WordPress).

Oppure potete agganciarvi al filtro pre_comment_approved e contrassegnare i commenti come approvati, spam o thrash in base a criteri predefiniti.

Esempio di Filtro 2: Inserire Contenuto Dopo un Post

Avete già visto come WordPress utilizza il filtro the_content per modificare i contenuti dei post e delle pagine. Utilizziamo lo stesso filtro per aggiungere qualcosa alla fine di ogni post.

// hook into 'the_content' filter with a callback function
add_filter( 'the_content', 'insert_content_below' );

// define the callback function to insert something below the post
function insert_content_below( $content ) {
    // check to see if we're inside the main loop in a single post
    if ( is_single() && in_the_loop() && is_main_query() ) {
        return $content . "<h3 style=\"text-align: center;\">Let me insert myself here</h3><p style=\"text-align: center;border: 3px solid #5333ed;\">I'll appear after the post. You can insert anything here. Even HTML. Headers, links, images, scripts, I'll take them all and append it to the end of the post content. You can also give me a class, so you can style me easily with CSS style sheets.</p>" ;
    } 
    
    return $content;
}

Capiamo la logica del codice dell’esempio precedente:

  • Il filter hook  the_content permette di afferrare il contenuto del post corrente e personalizzarlo.
  • Utilizza la funzione add_filter() per agganciarsi al filtro the_content con la funzione di callback insert_content_below().
  • Definisce la funzione di callback passando il contenuto del post corrente come parametro ($content).
  • All’interno della funzione di callback, verificate di filtrare solo il contenuto della query principale, che in questo caso è il contenuto del post. Se non si verifica questo, a volte il codice filtra inavvertitamente il contenuto di altri elementi, come le barre laterali e i footer.
  • Le condizioni is_main_query() e in_the_loop() stabiliscono se la query è una query principale e avviene all’interno del Loop principale di WordPress.
  • is_single() verifica se la query è per un singolo post.
  • Utilizza l’operatore di concatenazione di stringhe di PHP ($content . "your additions") per aggiungere roba extra al contenuto della pagina.
  • resturn restituisce il contenuto filtrato se tutte le condizioni di cui sopra sono state verificate. Se non lo sono, allora restituisce il contenuto senza modifiche.

Salvate il file del vostro plugin, caricate qualsiasi post sul vostro sito e scorrete fino alla fine.

Inserire qualcosa alla fine del contenuto del post
Inserire qualcosa alla fine del contenuto del post

Potete seguire la stessa logica per aggiungere qualcosa all’inizio di tutti i vostri post invertendo la posizione dei parametri di concatenazione delle stringhe ("your additions" . $content).

Personalizzare la Pagina di Login di WordPress con gli Hook

Utilizziamo sia le azioni che i filtri per personalizzare la pagina di login di default di WordPress. Per farlo, creerò un nuovo plugin chiamato Sal Custom Login Page. Potete trovare il codice sorgente completo di questo plugin alla fine di questa sezione.

La schermata di accesso personalizzata di WordPress
La schermata di accesso personalizzata di WordPress

Iniziamo aggiungendo i campi di intestazione standard del plugin e registrandolo con WordPress.

<?php

/*
Plugin Name:  Sal Custom Login Page
Version:  1.0
Description:  Demonstrating WordPress Hooks (Actions and Filters) by customizing the WordPress login page.
Author:  Salman Ravoof
Author URI:  https://www.salmanravoof.com/License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Text Domain:  sal-custom-login-page
*/

// enqueueing the custom style sheet on WordPress login page
add_action( 'login_enqueue_scripts', 'salhooks_login_stylesheet');
function salhooks_login_stylesheet() {
    // Load the style sheet from the plugin folder
    wp_enqueue_style( 'sal-custom-login-page', plugin_dir_url( __FILE__ ).'sal-custom-login-page-styles.css' );
}

Per prima cosa, agganciatevi all’azione login_enque_scripts per accodare il vostro foglio di stile personalizzato. Tutti gli script o gli stili che avete inserito qui sono inclusi nella sezione di testa della vostra pagina di login.

Se volete caricare script e fogli di stile personalizzati sul frontend del vostro sito (piuttosto che sul backend di amministrazione o nell’area di login), allora è necessario agganciarsi all’azione wp_enqueue_scripts. Potete saperne di più nel Codex di WordPress e nell’articolo di Kinsta su come utilizzare wp_enqueue_scripts.

All’interno della funzione di callback salhooks_login_stylesheet(), usate la funzione wp_enqueue_style() per caricare il foglio di stile personalizzato (sal-custom-login-page-styles.css) posto nella directory del plugin stesso. La funzione plugin_dir_url( __FILE__ ) integrata in WordPress rende facile ottenere il percorso dell’URL (con una barra finale) della directory del plugin corrente.

Non vi spiegherò gli stili CSS applicati qui, ma li potete trovare tutti nel codice sorgente collegato alla fine di questa sezione.

// Custom login ERROR message to keep the site more secure
add_filter( 'login_errors', 'salhooks_remove_login_errors', 10 );
function salhooks_remove_login_errors() {
    return 'Incorrect credentials. Please try again!';
}

Successivamente, agganciatevi al filtro login_errors per modificare il messaggio di errore mostrato quando qualcuno inserisce credenziali errate. Il filtro del messaggio di errore impedirà agli aggressori di indovinare facilmente il vostro nome utente.

// Remove the login form box shake animation for incorrect credentials
add_action( 'login_head', 'remove_login_error_shake' );
function remove_login_error_shake() {
    remove_action( 'login_head', 'wp_shake_js', 12 );
}

Ogni volta che qualcuno inserisce credenziali di accesso errate, la casella del modulo di accesso trema in modo aggressivo. Questo è un passaggio facoltativo, ma l’ho incluso per mostrare che è anche possibile rimuovere alcune funzionalità dalla pagina di login.

Per saperne di più sulle funzioni remove_action() e remove_filter(), andate alla sezione finale di questo articolo.

// Change the logo and header link above the login form
add_filter( 'login_headerurl', 'salhooks_login_headerurl');
function salhooks_login_headerurl( $url ) {
    $url = 'https://salmanravoof.com';
    return $url;
}

add_filter( 'login_headertext', 'salhooks_login_headertext');
function salhooks_login_headertext( $text ) {
    $text = 'Salman Ravoof';
    return $text;
}

L’ultimo passaggio consiste nel modificare l’URL e il testo dell’intestazione del login. È possibile agganciarsi ai filtri login_headerurl e login_headertext per modificarli entrambi.

Se volete costruire su questo plugin e sperimentare ulteriormente, potete scaricare il codice sorgente del plugin e iniziare il lavoro.

Elenco e Risorse sugli Hook di WordPress

È difficile memorizzare tutti i vari hook di WordPress. Ci sono migliaia di azioni e filtri incorporati cui agganciarsi. Quindi, trovare un hook appropriato può a volte sembrare una caccia al tesoro.

Per fortuna, ci sono molte risorse che potete utilizzare per identificare l’hook perfetto per le vostre esigenze.

Il primo posto per familiarizzare con gli hook è il Codex di WordPress, in particolare la sua sezione Hooks nel Plugin Handbook. Qui si possono trovare informazioni essenziali sugli hook e link per una documentazione completa su tutte le azioni e i filtri.

Iniziate a lavorare con gli hook con il Manuale dei Plugin di WordPress
Iniziate a lavorare con gli hook con il Manuale dei Plugin di WordPress

Aggiungete ai preferiti questi utili link del Manuale del Plugin per velocizzare la vostra ricerca:

Sia il riferimento alle azioni che le pagine di riferimento ai filtri vi forniranno un elenco di tutti i hook che vengono eseguiti durante una specifica richiesta a WordPress.

Ad esempio, potete trovare tutti gli hooks attivati quando si accede a una pagina di amministrazione, quando si ha a che fare con gli allegati alle pagine dei post o con le categorie.

Il Codex di WordPress comprende anche un pratico strumento di ricerca per trovare tutte le funzioni, gli hooks, i metodi e le classi. Questa pagina elenca anche i componenti nuovi e aggiornati nella versione più recente di WordPress. Se volete scoprire cosa sta succedendo all’interno di WordPress, cominciate da qui.

Cercare qualcosa all'interno di WordPress
Cercare qualcosa all’interno di WordPress

Questo indice degli hook di WordPress ordina tutti gli hook per tipo, versione di WordPress in cui hanno debuttato, e se sono deprecati.

Indice degli hook di WordPress di Adam R Brown
Indice degli hook di WordPress di Adam R Brown

Ordinando gli hook in ordine di apparizione, vedrete che i più vecchi hook di WordPress sono ancora i più utilizzati. Se siete nuovi nello sviluppo di WordPress, familiarizzare con queste azioni e con questi filtri di uso frequente è il modo più veloce per recuperare il ritardo.

Anche se questo indice non è stato aggiornato dai tempi di WordPress 5.1, è comunque utile sfogliare tutti i principali hook.

Avete ancora difficoltà a trovare l’hook che vi serve? Una ricerca online con la parola chiave giusta è sempre un buon modo per iniziare. Se tutto il resto fallisce, potete sempre scavare nel Codex di WordPress.

Trovare gli Hook Registrati su una Pagina di WordPress

Come abbiamo visto, WordPress dispone di un sacco di hook, ma non tutti gli hook si attivano su ogni pagina. Se riuscite a trovare le azioni e i filtri cui potete agganciarvi in una determinata pagina, allora siete già alla metà dell’opera.

Anche se potete utilizzare strumenti avanzati di debug PHP come xdebug e PHPCS, ci sono strumenti di sviluppo più semplici come Debug Bar e Query Monitor che possono essere eseguiti all’interno di WordPress.

Debug Bar con l’Add-On delle Actions and Filters

Debug Bar è un plugin ufficiale di WordPress che aggiunge un menu di debug alla barra di amministrazione. Mostra avvisi e notifiche di PHP, richieste di cache, query MySQL e altre informazioni utili per il debug.

Il plugin WordPress Debug Bar
Il plugin WordPress Debug Bar

Dopo aver installato il plugin, dovrete aggiungere il frammento di codice riportato qui sotto al file wp-config.php del sito, in modo da abilitare le funzionalità di debug.

define( 'WP_DEBUG', true ); // tracks PHP Warnings and Notices
define( 'SAVEQUERIES', true ); // tracks and displays MySQL queries

Ora nella barra di amministrazione dovrebbe apparire l’opzione di menu Debug. Facendo clic qui si accede alla sua dashboard dove si possono vedere varie query e cache allegate alla pagina da cui siete passati per accedere.

Il menu 'Debug' nella barra di amministrazione di WordPress
Il menu ‘Debug’ nella barra di amministrazione di WordPress

Successivamente, dovete installare il plugin Debug Bar Actions and Filters Addon. È una comoda estensione che aggiungerà altre due schede alla dashboard di Debug Bar che permettono di visualizzare le azioni e i filtri attivati sulla richiesta corrente.

Azioni elencate nel loro ordine di caricamento per la pagina corrente
Azioni elencate nel loro ordine di caricamento per la pagina corrente

Elencherà anche tutte le funzioni ad esse collegate con la loro priorità.

Filtri elencati con la rispettiva priority e le funzioni di callback registrate
Filtri elencati con la rispettiva priority e le funzioni di callback registrate

Potete cliccare sul menu Debug da qualsiasi pagina del vostro sito per conoscere tutte le azioni e i filtri a cui potete agganciarvi in quella pagina.

Query Monitor

Query Monitor è un potente pannello di strumenti di sviluppo per WordPress. Potete utilizzarlo per scavare negli hook disponibili su una pagina e nel loro ordine di caricamento.

Il plugin WordPress Query Monitor
Il plugin WordPress Query Monitor

A differenza di Debug Bar, non è necessario installare alcun add-on per vedere le azioni e i filtri attivati su una certa pagina.

È possibile accedere a Query Monitor dalla barra di amministrazione
È possibile accedere a Query Monitor dalla barra di amministrazione

Query Monitor fornisce anche maggiori informazioni su dove viene attivato esattamente un hook.

Il pannello Hooks & Actions in Query Monitor
Il pannello Hooks & Actions in Query Monitor

Nella colonna dei componenti, potete vedere che la maggior parte degli hook è registrata dal Core. Ma alcuni hook sono registrati da un tema o da un plugin. Alcuni possono essere registrati da più di un componente.

È possibile utilizzare i menu a discesa degli hook e dei componenti per visualizzare solo gli hook necessari.

Nota: Query Monitor usa “Hooks” come termine generale sia per le azioni che per i filtri, ma chiama le funzioni di callback registrate come “Actions”. Questa è una definizione tecnicamente sbagliata e può confondervi, quindi tenetelo a mente.

Con Query Monitor potete fare molto di più che controllare tutte le query e le richieste. Dispone anche di funzioni avanzate come stili di elenchi, script, lingue, chiamate Ajax, controlli delle capacità dell’utente e chiamate alla REST API.

L’Hook “all”

WordPress ha un hook speciale chiamato ‘all’ cui potete agganciarvi per eseguire una funzione di callback per ogni singolo hook, indipendentemente dal fatto che sia registrato con tutti. È utile per eseguire il debug dei crash delle pagine o se volete sapere quando un particolare evento sta accadendo.

Ad esempio, potete utilizzare l’hook all come nell’esempio qui sotto per fare l’echo di tutte le azioni in corso.

// echo all the actions being run
function debug_helper_function(){
    echo '<p>' . current_action() . '</p>';
}
add_action( 'all', 'debug_helper_function' );

La debug_helper_function() definita sopra verrà eseguita quando si attiva una qualsiasi azione. Sapere quale è stata l’ultima azione eseguita vi darà un’idea migliore di dove dovete guardare.

Dove Sono Memorizzati gli Hook di WordPress?

Per implementare il funzionamento degli hook, WordPress utilizza la classe WP_Hook. Questa classe del Core è utilizzata per gestire tutte le azioni e i filtri incorporati in WordPress. Trovate quasi tutto il codice relativo a questa classe nel file wp-includes/class-wp-hook.php.

Tecnicamente, la classe WP_Hook è un array di oggetti che comprende proprietà come callback, iterations, current_priority, nesting_level e doing_action. Definisce anche molte utili hook function che possono essere invocate utilizzando i metodi di WP_Hook.

La maggior parte degli sviluppatori di WordPress non deve preoccuparsi molto di dove WordPress memorizza gli hook, purché si attengano alle linee guida delle API dei Plugin.

Come Creare i Vostri Hook di WordPress Personalizzati

Avete visto i vari hooks forniti da WordPress attraverso la Plugin API. Avete anche visto come utilizzare gli hook predefiniti per iniettare il vostro codice nella runtime di WordPress.

Se siete sviluppatori di temi o di plugin, è buona pratica fornire allo stesso modo ad altri sviluppatori un modo per interagire con il vostro codice. Gli hook personalizzati consentono di fare esattamente questo. Permettono ad altri sviluppatori di estendere e modificare le funzionalità dei vostri temi e plugin.

Creare le proprie azioni e i propri filtri è abbastanza semplice. Si utilizzano le stesse funzioni che il Core di WordPress utilizza per creare gli hook. Vediamo alcuni esempi.

Come Creare Azioni Personalizzate in WordPress

Per creare un hook personalizzato per le azioni, utilizzate la funzione do_action(). Ecco come si fa:

// the position where you insert your action is where it'll run when called
do_action( ' my_unique_custom_action' );
// continue with the rest of your code

Ora, altri sviluppatori possono agganciarsi al vostro plugin o al vostro tema senza modificare il codice sorgente. Tutto quello che devono fare è registrare le loro funzioni di callback all’azione personalizzata del vostro plugin utilizzando la funzione add_action().

add_action( 'my_unique_custom_action', 'some_callback_function' );

// define the callback function you mentioned in the above action function
some_callback_function() {
     // this code will run wherever your custom action hook is 
}

Assicuratevi di documentare accuratamente i vostri hook personalizzati, spiegando in dettaglio ciò che fanno. Dopo tutto, lo scopo principale della creazione di hook personalizzati è quello di aiutare gli altri sviluppatori ad interagire con il vostro codice.

Come Creare un Filtro Personalizzato in WordPress

Usate la funzione apply_filters() per creare un filtro personalizzato. Ecco come fare:

$value_to_filter = "I'm a string, but this can be any PHP data type";

// filters modify a value and are typically tied to a predefined variable
apply_filters( 'my_custom_filter', $value_to_filter );

I parametri del vostro filtro personalizzato dovrebbero includere un identificatore univoco e un valore da filtrare. Altri sviluppatori possono agganciarsi al vostro filtro personalizzato con la funzione add_filter() e modificare il valore passato.

add_filter( 'my_custom_filter', 'some_callback_function' );

// define the callback function you mentioned in the above filter function
function some_callback_function( $value_to_filter ) {
    // modify the passed value (or not) 
    return $value_to_filter; // returning a value is a must for filters
}

Quando si definisce il filtro personalizzato, assicuratevi che non sia posizionato prima della definizione del valore che si suppone debba filtrare. Se non si posiziona correttamente il filtro, il valore filtrato verrà in seguito sovrascritto dal valore di default.

Convenzione per la Denominazione degli Hook Personalizzati

È importante scegliere un nome univoco per tutti gli hook personalizzati. Dal momento che qualsiasi plugin o tema può avere i propri hook personalizzati, avere nomi di hook identici può causare conflitti di codice con risultati inaspettati.

Per esempio, se si assegna un nome alla propria azione send_email, è molto probabile che anche altri sviluppatori di plugin possano scegliere lo stesso termine, in quanto non è abbastanza univoco. Se un sito web installa sia il vostro plugin che quello dell’altro sviluppatore, può causare errori che saranno difficili da rintracciare.

Potete applicare un prefisso a tutti i vostri hook personalizzati con un identificatore comune per mantenerli semplici e unici. Così, invece di send_email, potete assegnargli il nome plugin_name_send_email (il plugin_name_ è il prefisso univoco).

Demo di Hook Personalizzati con un Plugin Estendibile

Creiamo un plugin estendibile (o un plugin pluggable) che permetta ad altri sviluppatori di interagire con esso utilizzando i suoi hook personalizzati.

Chiamerò questo plugin Custom Hooks Demo. La sua funzione principale è quella di emettere un box di citazione ovunque si inserisca uno shortcode. Includerà azioni e filtri personalizzati nelle posizioni giuste per consentire ad altri sviluppatori di modificare o estendere le sue funzionalità.

Potete consultare la mia guida agli shortcode di WordPress per saperne di più sul loro funzionamento.

Iniziamo con il plugin estendibile.

<?php

/*
Plugin Name :  Custom Hooks Demo
Description :  Demonstrating how to create an extensible WordPress plugin using custom hooks.
Author      :  Salman Ravoof
Author URI  :  https://salmanravoof.com/
License     :  GPLv2 or later
License URI :  https://www.gnu.org/licenses/gpl-2.0.html
Text Domain :  custom-hooks-demo
*/

/** 
 * the [custom_hooks_demo] shortcode returns the HTML code for a quote box.
 * @return string HTML code for a quote box
*/
add_shortcode( 'custom_hooks_demo', 'my_shortcode_callback' );

function my_shortcode_callback ( $arguments ) {
    ob_start(); // start object buffering to collect all output before sending it to the browser
    
    // set an action hook to run before you output anything
    do_action( 'the_topmost_custom_action' );
    
    // define your variables which you want to allow to be filtered
    $quote_content = "Z.E.R.O. That's the number of people who'd like to have any website autoplay music on their browsers.";
    $quote_author = "John Doenuts";
    
    // create your custom filters after you've set the variables
    $quote_content = apply_filters( 'custom_quote_content', $quote_content );
    $quote_author = apply_filters( 'custom_quote_author', $quote_author );
    
    // build the shortcode output template
    echo "<div style=\"border:3px solid #5333ed;\"><blockquote style=\"margin:20px;border-color:#5333ed;\">";
    echo $quote_content;
    echo "<br><br>";
    echo "― <strong>" . $quote_author . "</strong>";
    echo "</blockquote></div>";
    
    // set an action hook to run after you output everything
    do_action( 'the_ending_custom_action' );
    
    return ob_get_clean(); // get buffer contents, delete the buffer, and then stop buffering
}
  • La funzione add_shortcode() viene utilizzata per creare lo shortcode personalizzato. Poi si definisce la funzione di callback dello shortcode con tutte le funzionalità di questo plugin.
  • ob_start() è una funzione PHP che abilita il buffering dell’output. È una funzione molto comoda che istruisce PHP a mantenere qualsiasi output nella memoria buffer del server, invece di emetterlo subito. Potete utilizzarla per costruire codice HTML complesso e leggibile in PHP.
  • do_action( 'the_topmost_custom_action' ) definisce la prima azione personalizzata. Per renderla utile, è necessario definirla prima che il plugin emetta qualcosa. Altri sviluppatori possono agganciarsi a questa azione personalizzata per eseguire il loro codice prima che questo shortcode personalizzato stampi qualcosa.
  • Crea le variabili che si desidera filtrare. In questo plugin, queste variabili sono $quote_content e $quote_author. In questo esempio sono entrambe stringhe, ma possono essere qualsiasi tipo di dato PHP (p.e. intero, booleano, array).
  • Usa la funzione apply_filters() per creare i filtri personalizzati. Dato che tutti i filtri restituiscono un valore, potete assegnare le variabili definite in precedenza al valore restituito da questo filtro. Altri sviluppatori possono ora agganciarsi a questo filtro per modificare i valori di default delle variabili predefinite.
  • Utilizza le istruzioni echo per costruire il vostro shortcode di uscita riga per riga. Dal momento che abbiamo abilitato il buffering dell’output, nessun output raggiungerà subito il browser.
  • do_action( 'the_ending_custom_action' ) definisce la vostra ultima azione personalizzata. È necessario definirla alla fine, ma prima di restituire tutti i contenuti del buffer.
  • ob_get_clean() è una funzione PHP predefinita 3-in-1. Recupera il contenuto del buffer, elimina tutti i dati del buffer e poi arresta il buffering in uscita. La funzione restituisce con return il contenuto del buffer raccolto come singola stringa concatenata.

Una volta salvato e attivato il plugin, aggiungendo lo shortcode [custom_hooks_demo] al contenuto del vostro post, verrà visualizzato un riquadro di citazione con i valori predefiniti.

Il riquadro di citazione originale ottenuto utilizzando il plugin demo Custom Hooks
Il riquadro di citazione originale ottenuto utilizzando il plugin demo Custom Hooks

Ora, creiamo un altro plugin chiamato Custom Hooks Demo Extension. Si aggancerà a tutti gli hook personalizzati creati dal plugin precedente e farà o modificherà qualcosa.

<?php

/*
Plugin Name :  Custom Hooks Demo Extension
Description :  Demonstrating how you can extend WordPress plugin functionality with its custom hooks.
Author      :  Salman Ravoof
Author URI  :  https://salmanravoof.com/
License     :  GPLv2 or later
License URI :  https://www.gnu.org/licenses/gpl-2.0.html
Text Domain :  custom-hooks-demo-extension
*/

/**
 * replace the quote content by hooking into the 'custom_quote_content' filter
*/
add_filter( 'custom_quote_content', 'new_quote_content_callback' );
function new_quote_content_callback( $content ) {
    $content = "There are no bugs in programming. Only unexpected features.";
    return $content;
}

/**
 * replace the quote author by hooking into the 'custom_quote_author'
*/
add_filter( 'custom_quote_author', 'new_quote_author_callback' );
function new_quote_author_callback( $author ) {
    $author = "Jane Doodle";
    return $author;
}

/**
 * add an image to the top of the shortcode output by hooking into the 'the_topmost_custom_action'
*/
add_action( 'the_topmost_custom_action', 'quote_image_callback' );
function quote_image_callback() {
    $url = "https://upload.wikimedia.org/wikipedia/commons/thumb/f/f9/Quote-right-cs.svg/75px-Quote-right-cs.svg.png";
    echo '<div><img class="aligncenter" src="'.$url.'"></div>';
}

/**
 * add a button below the shortcut output by hooking into the 'the_ending_custom_action'
*/
add_action( 'the_ending_custom_action', 'add_button_callback' );
function add_button_callback() {
    echo '<div style="text-align:center;"><button name="nice">Nice Quote!</button></div>';
}

Come potete vedere, questo plugin di estensione non contiene altro che action e filter function che si agganciano al plugin originale nei punti giusti per apportare modifiche.

Utilizza le funzioni add_action() e add_filter() per registrare le sue funzioni di callback sulle azioni e sui filtri personalizzati creati dal plugin originale (p.e. the_topmost_custom_action, custom_quote_author).

Il plugin di estensione modifica il riquadro della citazione originale
Il plugin di estensione modifica il riquadro della citazione originale

Gli action hook personalizzati consentono di interporre il codice agli intervalli giusti nel plugin originale ed eseguire i propri script. Qui aggiungiamo un’immagine in alto e un pulsante in basso.

Allo stesso modo, i filtri personalizzati consentono di modificare i valori del contenuto della citazione e il nome dell’autore. Il risultato finale è un plugin che è completamente estendibile da chiunque senza che sia necessario apportare modifiche al suo codice sorgente.

Lavorare con Hook Personalizzati di Sviluppatori di Terze Parti

Gli hook personalizzati consentono ai singoli plugin e temi di WordPress di avere un ricco ecosistema di plugin estendibili. Considerate il plugin WooCommerce. Aggiunge funzionalità di ecommerce a WordPress, ma include anche un sacco di hook all’interno del suo codice.

WooCommerce Action and Filter Hook Reference
WooCommerce Action and Filter Hook Reference

WooCommerce ha centinaia di estensioni e plugin che utilizzano i suoi hook per migliorare ulteriormente le sue funzionalità di base.

Potete utilizzare queste estensioni per integrare WooCommerce con Stripe, MailChimp, Salesforce, Zapier e molto altro.

Le estensioni estendono le funzionalità di WooCommerce
Le estensioni estendono le funzionalità di WooCommerce

Una buona pratica è quella di controllare la sezione della documentazione dei popolari plugin di WordPress per vedere come implementano gli hook personalizzati. Tra quelli che considermo migliori, suggerisco Easy Digital Downloads, BuddyPress, Quiz and Survey Master e Gravity Forms.

Quando Utilizzare gli Hook Personalizzati?

A seconda del tema o del plugin che si sta creando e a chi è destinato, ci si può chiedere se sia necessario aggiungere degli hook personalizzati.

Una buona regola empirica quando si decide se aggiungere o meno hook personalizzati è quella di verificare se offrono vantaggi di estendibilità ad altri sviluppatori. In caso contrario, è meglio aspettare fino a quando gli altri sviluppatori non vi chiederanno di aggiungerli.

È necessario essere molto sicuri se aggiungere hook personalizzati al plugin o al tema. Una volta rilasciato, e se altri sviluppatori lo hanno già utilizzato, non si può mai cambiare senza rompere la compatibilità a ritroso.

Rimuovere le Funzioni di Callback dagli Hook di WordPress

Avete già visto come rimuovere le funzioni di callback registrate su alcuni hooks. Queste callback potrebbero essere registrate da plugin, temi o anche dallo stesso Core di WordPress. Vediamo come rimuovere le funzioni di callback ad aggancio con altri esempi.

Per rimuovere una funzione di callback da un hook, a seconda che sia registrata ad un’azione o ad un filtro, è necessario utilizzare le funzioni remove_action() e remove_filter().

Un avvertimento è che è necessario invocare queste funzioni con gli identici parametri utilizzati per registrarle. Fondamentalmente, copiate-incollate i parametri dalle loro funzioni add_action() e add_filter().

Inoltre, è possibile rimuovere le funzioni di callback solo dopo che sono state registrate. Se tentate di rimuoverle prima che siano registrate, la rimozione fallirà. È necessario avere l’ordine di esecuzione degli hook giusto.

Supponiamo che vogliate rimuovere una funzione di callback registrata da un tema che appesantisce il vostro sito (volete un sito veloce, non è vero?).

function wp_bloated_callback_function() {    
// some code that adds a lot of bloat to the site
}
add_action( 'template_redirect', 'wp_bloated_callback_function', 5 );

Ad esempio, la funzione di callback qui sopra potrebbe caricare molti script e fogli di stile non necessari. La sua rimozione darebbe al vostro sito un enorme aumento delle prestazioni.

Tuttavia, è necessario assicurarsi che la funzione remove_action() venga eseguita solo dopo l’azione template_redirect. Un modo per farlo è quello di agganciarsi all’azione after_setup_theme, in quanto questa viene attivata dopo l’azione template_redirect.

function wp_remove_bloat() {
    // ensure all parameters are identical to the original add_action() function
    remove_action( 'template_redirect', 'wp_bloated_callback_function', 5 );
}

// ensure that remove_action() is called only after add_action()
add_action( 'after_setup_theme', 'wp_remove_bloat' );

La funzione wp_bloated_callback_function() ora sarà sganciata dall’azione template_redirect.

Casi Speciali per la Rimozione delle Funzioni di Callback

La rimozione delle funzioni di callback non si limita a disabilitarle del tutto. A volte potrebbe essere necessario rimuoverle temporaneamente, eseguire il codice e poi aggiungerle di nuovo.

Ad esempio, l’azione save_post viene attivata ogni volta che vengono richiamate le funzioni wp_insert_post() e wp_publish_post(). Potete trovare la definizione di entrambe nel file wp-includes/post.php.

Quindi, se avete una funzione di callback agganciata all’azione save_post, e se invocate le funzioni wp_insert_post() o wp_publish_post() all’interno della vostra funzione di callback, l’azione save_post si attiverà più volte.

function some_callback_function( $post_id, $post ) {
    // do something here
    wp_insert_post( [some_array] ); // this function also calls the 'save_post' action
    // maybe do something more
}
add_action( 'save_post', 'some_callback_function', 10, 2 );

Una funzione che chiama l’azione che la chiama può anche creare risultati inaspettati. Un modo per aggirare questo problema è usare la funzione remove_action() all’interno della funzione di callback prima di invocare wp_insert_post().

function some_callback_function( $post_id, $post ) {
    // do something here
    
    // remove the callback function from the ‘save_post’ action
    remove_action( 'save_post', 'some_callback_function', 10, 2 );
    
    // now run the wp_insert_post() function
    wp_insert_post( [some_array] );
    
    // add the callback function back to the ‘save_post’ action
    add_action( 'save_post', 'some_callback_function', 10, 2 );
    
    // maybe do something more
}
add_action( 'save_post', 'some_callback_function', 10, 2 );

Questo è un altro uso pratico delle funzioni remove_action() e remove_filter(). Scavando più a fondo nel Core di WordPress potrete capire meglio come evitare queste situazioni.

Tutorial Bonus sugli Hook di WordPress

Riepilogo

Se siete sviluppatori WordPress, Utilizzare gli hook di WordPress vi offre molteplici vantaggi.

Non solo gli hook consentono di modificare o estendere le funzionalità di base di WordPress, ma è anche possibile utilizzarli per modificare plugin, temi, e lasciare che altri sviluppatori interagiscano con i vostri temi e plugin.

È ora di agganciarsi agli hook di WordPress!

Salman Ravoof

Salman Ravoof is a self-taught web developer, writer, creator, and a huge admirer of Free and Open Source Software (FOSS). Besides tech, he's excited by science, philosophy, photography, arts, cats, and food. Learn more about him on his website, and connect with Salman on Twitter.