Architettura degli Hook di WordPress: Azioni vs Filtri Spiegati

Ogni plugin di WordPress fa una delle due cose: esegue codice in un momento specifico (azione) o modifica un valore prima che venga utilizzato (filtro). Tutto qui. L'intero ecosistema dei plugin di WordPress è costruito su questa distinzione.

Comprendere la differenza — e quando usare ciascuno — è ciò che separa i plugin che funzionano da quelli che causano problemi.

Azioni: fare qualcosa in un dato momento

Un hook di azione è un segnale che WordPress (o un altro plugin) invia in un momento specifico. Colleghi una funzione a quel segnale e la tua funzione viene eseguita quando il segnale viene attivato.

add_action( 'wp_enqueue_scripts', 'my_plugin_load_assets' );

function my_plugin_load_assets() {
    wp_enqueue_style( 'my-plugin', plugin_dir_url( __FILE__ ) . 'style.css' );
    wp_enqueue_script( 'my-plugin', plugin_dir_url( __FILE__ ) . 'script.js', ['jquery'], '1.0', true );
}

wp_enqueue_scripts viene attivato quando WordPress si prepara a caricare gli asset per il front-end. Agganciarsi ad esso è il modo corretto per caricare CSS e JS — non inserire tag <script> direttamente nei template.

Hook di azione comuni che userai costantemente:

• init — viene eseguito presto, utile per registrare tipi di post e tassonomie
• wp_enqueue_scripts — carica gli asset del front-end
• admin_enqueue_scripts — carica gli asset dell'amministrazione
• save_post — viene eseguito quando un post viene salvato, utile per elaborare campi personalizzati
• wp_ajax_{action} — gestisce le richieste AJAX da utenti autenticati
• wp_ajax_nopriv_{action} — gestisce le richieste AJAX da utenti non registrati

Filtri: modificare un valore prima che venga utilizzato

Un hook di filtro ti fornisce un valore, ti permette di modificarlo e si aspetta che tu restituisca la versione modificata. WordPress quindi utilizza il tuo valore modificato invece dell'originale.

add_filter( 'the_content', 'my_plugin_append_cta' );

function my_plugin_append_cta( $content ) {
    if ( ! is_single() ) {
        return $content;
    }
    $cta = '<div class="post-cta">Pronto a provare PAGEnza? <a href="#">Inizia gratis →</a></div>';
    return $content . $cta;
}

La regola fondamentale: restituisci sempre qualcosa da un filtro. Se dimentichi il return, il valore diventa null e avrai appena rotto ciò che lo stava utilizzando.

Hook di filtro comuni:

• the_content — il contenuto del post prima della visualizzazione
• the_title — il titolo del post
• wp_nav_menu_items — HTML del menu di navigazione
• upload_mimes — tipi di file caricabili consentiti
• plugin_action_links_{plugin-file} — link mostrati nella pagina dell'elenco dei plugin

Come PAGEnza AI utilizza gli hook

Quando il Plugin Builder genera un plugin, struttura il codice attorno a una classe con metodi collegati agli hook nel costruttore. Questo modello evita conflitti di nomi di funzioni globali e mantiene il codice organizzato.

class My_Plugin {
    public function __construct() {
        add_action( 'init', [ $this, 'register_post_type' ] );
        add_action( 'wp_enqueue_scripts', [ $this, 'load_assets' ] );
        add_filter( 'the_content', [ $this, 'append_content' ] );
    }

    public function register_post_type() { /* ... */ }
    public function load_assets() { /* ... */ }
    public function append_content( $content ) {
        // restituisci sempre
        return $content;
    }
}

new My_Plugin();

La scansione di sicurezza verifica specificamente che i gestori AJAX includano sia un controllo nonce che un controllo delle capacità prima di fare qualsiasi cosa:

add_action( 'wp_ajax_my_action', [ $this, 'handle_ajax' ] );

public function handle_ajax() {
    // Sicurezza: verifica nonce
    check_ajax_referer( 'my_nonce_action', 'nonce' );

    // Sicurezza: verifica permessi
    if ( ! current_user_can( 'manage_options' ) ) {
        wp_send_json_error( 'Permessi insufficienti', 403 );
    }

    // Ora è sicuro elaborare
    $data = sanitize_text_field( $_POST['data'] ?? '' );
    wp_send_json_success( [ 'result' => $data ] );
}

La mancanza di uno di questi viene segnalata come problema di sicurezza e impedisce il rilascio del plugin.

Priorità e coda degli hook

Quando più funzioni sono collegate allo stesso hook, vengono eseguite in ordine di priorità (numero inferiore = esegue per primo). La priorità predefinita è 10.

add_action( 'init', 'runs_first', 5 );
add_action( 'init', 'runs_second', 10 );   // predefinito
add_action( 'init', 'runs_last', 20 );

Questo è importante quando il tuo plugin deve essere eseguito prima o dopo il codice di un altro plugin. Se stai modificando qualcosa che un altro plugin modifica anche, la priorità controlla chi vince.

Un modello comune: se stai sovrascrivendo un filtro di un tema, usa la priorità 20 o superiore per assicurarti di eseguire dopo il codice del tema.

Rimozione degli hook

Puoi rimuovere un hook che qualcun altro ha aggiunto — inclusi gli hook di temi e plugin:

remove_action( 'wp_head', 'wp_generator' );  // rimuove la versione di WP da <head>
remove_filter( 'the_content', 'wpautop' );   // rimuove l'incapsulamento automatico in paragrafi

Il trucco: puoi rimuovere un hook solo se chiami remove_action/remove_filter dopo che l'add_action/add_filter originale è stato eseguito. Questo di solito significa agganciare la tua rimozione a un'azione successiva.