Indice degli hook di WordPress

Un indice ricercabile delle azioni e dei filtri di WordPress che gli sviluppatori usano davvero — con la firma esatta di add_action/add_filter, quando viene eseguito, un esempio funzionante e il dettaglio che frega tutti.

39 hook, con la firma esatta di add_action / add_filter, quando viene eseguito, un esempio funzionante e il dettaglio che coglie tutti di sorpresa. 1 sono contrassegnati come non verificati: non abbiamo controllato il numero dei loro argomenti rispetto al sorgente di WordPress e preferiamo segnalarlo piuttosto che spacciare una supposizione per un dato di fatto.

Non è un elenco esaustivo e non pretende di esserlo: WordPress ha migliaia di hook. Copre quelli che si usano davvero.

39 di 39

Viene eseguito dopo che WordPress ha terminato il caricamento ma prima che venga inviato qualsiasi header. Il posto standard per registrare tipi di contenuto personalizzati, tassonomie e regole di rewrite.

Quando si attiva

A ogni richiesta, sia sul front end che nell'area di amministrazione, dopo il caricamento del core, dei plugin e del tema.

Firma

add_action( 'init', 'my_callback' );

Esempio

add_action( 'init', function () {
    register_post_type( 'book', array(
        'public'       => true,
        'label'        => 'Books',
        'show_in_rest' => true, // required for the block editor
    ) );
} );

L'insidia

init viene eseguito a OGNI richiesta, incluse AJAX, REST e cron. Fare qualcosa di lento qui (una richiesta HTTP, una query pesante) appesantisce ogni singolo caricamento di pagina. Inoltre: l'utente corrente è disponibile qui, ma non puoi produrre alcun output — gli header non sono ancora stati inviati, ma stanno per esserlo.

Viene eseguito una volta caricato il tema. Il posto corretto per add_theme_support(), add_image_size() e la registrazione dei menu di navigazione.

Quando si attiva

Dopo il caricamento del functions.php del tema, PRIMA di init.

Firma

add_action( 'after_setup_theme', 'my_callback' );

Esempio

add_action( 'after_setup_theme', function () {
    add_theme_support( 'post-thumbnails' );
    add_theme_support( 'title-tag' );
    add_image_size( 'card', 600, 400, true ); // true = hard crop
} );

L'insidia

Registrare le dimensioni delle immagini su init invece che qui funziona per caso nella maggior parte dei casi e poi fallisce in modo misterioso in alcuni. Usa after_setup_theme — è fatto apposta per questo.

Viene eseguito una volta caricati tutti i plugin attivi. Il primo punto sicuro per interagire con un altro plugin.

Quando si attiva

Dopo che ogni file di plugin è stato incluso, prima del caricamento del tema.

Firma

add_action( 'plugins_loaded', 'my_callback' );

L'insidia

L'utente corrente NON è ancora disponibile qui — wp_get_current_user() non funzionerà in modo affidabile. Se ti serve l'utente, usa init.

Viene eseguito dopo che WordPress è completamente caricato — plugin, tema, init e utente sono tutti pronti.

Quando si attiva

Dopo init e dopo che l'utente corrente è stato configurato.

Firma

add_action( 'wp_loaded', 'my_callback' );

Viene eseguito all'inizio di ogni richiesta nell'area di amministrazione. Usato per register_setting(), controlli sui permessi e reindirizzamenti nell'amministrazione.

Quando si attiva

A ogni richiesta lato amministrazione.

Firma

add_action( 'admin_init', 'my_callback' );

L'insidia

Viene eseguito anche sulle richieste ad admin-ajax.php, che non sono vere e proprie "schermate di amministrazione". Se la tua callback presuppone l'esistenza di una schermata, proteggila con wp_doing_ajax().

L'unico posto corretto per accodare CSS e JavaScript del front end.

Quando si attiva

Al caricamento delle pagine del front end, prima che venga renderizzato l'head.

Firma

add_action( 'wp_enqueue_scripts', 'my_callback' );

Esempio

add_action( 'wp_enqueue_scripts', function () {
    wp_enqueue_style(
        'child-style',
        get_stylesheet_uri(),
        array( 'parent-style' ),          // load AFTER the parent
        wp_get_theme()->get( 'Version' )  // cache-bust on version change
    );
} );

L'insidia

Nonostante il nome, gestisce gli STILI oltre agli script — non esiste un hook wp_enqueue_styles, e c'è chi perde tempo prezioso a cercarlo. Inoltre: non viene eseguito nell'area di amministrazione (usa admin_enqueue_scripts) né nell'editor a blocchi (usa enqueue_block_editor_assets).

Accoda CSS/JS nell'area di amministrazione. Riceve l'hook suffix della schermata corrente, così puoi caricare le risorse su una sola schermata.

Quando si attiva

Al caricamento delle pagine di amministrazione.

Firma

add_action( 'admin_enqueue_scripts', 'my_callback' ); // receives $hook_suffix

Esempio

add_action( 'admin_enqueue_scripts', function ( $hook ) {
    if ( 'settings_page_my-plugin' !== $hook ) {
        return; // do not load our JS on every admin screen
    }
    wp_enqueue_script( 'my-admin', plugins_url( 'admin.js', __FILE__ ), array(), '1.0', true );
} );

L'insidia

Non fare il controllo su $hook è la causa più comune in assoluto di un plugin che rompe schermate di amministrazione non correlate. Carica le tue risorse dove servono e da nessun'altra parte.

Accoda risorse solo nell'editor a blocchi (Gutenberg) — non nel front end, non nel resto dell'area di amministrazione.

Quando si attiva

Quando si carica l'editor a blocchi.

Firma

add_action( 'enqueue_block_editor_assets', 'my_callback' );

Stampa output all'interno di <head>. Usato per meta tag e CSS critico inline.

Quando si attiva

All'interno di <head>, sul front end.

Firma

add_action( 'wp_head', 'my_callback' );

L'insidia

NON accodare script o stili qui — usa wp_enqueue_scripts, che permette a WordPress di gestire dipendenze e deduplicazione. Stampare un tag <script> in wp_head aggira tutto questo ed è il motivo per cui così tanti siti caricano jQuery tre volte.

Stampa output appena prima di </body>. Il posto giusto per gli snippet di analytics e il markup differito.

Quando si attiva

Alla fine della pagina del front end.

Firma

add_action( 'wp_footer', 'my_callback' );

L'insidia

Un tema che dimentica di chiamare wp_footer() rompe la barra di amministrazione, rompe qualsiasi plugin che accoda uno script nel footer ed è motivo di rifiuto automatico nella revisione dei temi di wordpress.org.

Filtra il contenuto dell'articolo immediatamente prima che venga mostrato. Il posto abituale per aggiungere markup all'inizio o alla fine di un articolo.

Quando si attiva

Ogni volta che viene chiamato the_content().

Firma

add_filter( 'the_content', 'my_callback' ); // receives $content

Esempio

add_filter( 'the_content', function ( $content ) {
    if ( ! is_singular( 'post' ) || ! in_the_loop() || ! is_main_query() ) {
        return $content; // <- the guard everyone forgets
    }
    return $content . '<p class="cta">Enjoyed this? Read more.</p>';
} );

L'insidia

Viene eseguito molto più spesso di quanto pensi — nei widget, nelle risposte REST, nella generazione dei riassunti di alcuni plugin e una volta per articolo in un loop su un archivio. Senza il controllo is_singular / in_the_loop / is_main_query, la tua CTA appare quindici volte nell'indice del blog e dentro il feed RSS. È il filtro usato in modo più scorretto in WordPress.

Filtra il titolo dell'articolo prima della visualizzazione.

Quando si attiva

Ogni volta che viene chiamato the_title() o get_the_title().

Firma

add_filter( 'the_title', 'my_callback', 10, 2 ); // receives $title, $post_id

L'insidia

Viene eseguito anche per i titoli nel menu di amministrazione, nei menu di navigazione e nel <title> del documento. Filtrarlo senza condizioni rinominerà cose in posti che non intendevi.

Imposta quante PAROLE contiene un riassunto generato automaticamente. Il valore predefinito è 55.

Quando si attiva

Quando WordPress genera un riassunto per un articolo che non ha un riassunto manuale.

Firma

add_filter( 'excerpt_length', 'my_callback' ); // receives $length (words)

Esempio

add_filter( 'excerpt_length', function ( $length ) {
    return 25;
}, 999 ); // high priority: many themes set this too, and last one wins

L'insidia

Non ha effetto sugli articoli che hanno un riassunto MANUALE — quelli vengono usati testualmente. E molti temi impostano questo filtro da soli, quindi spesso serve un numero di priorità alto per prevalere.

Cambia la stringa aggiunta a un riassunto troncato. Il valore predefinito è " […]".

Quando si attiva

Quando un riassunto generato automaticamente viene troncato.

Firma

add_filter( 'excerpt_more', 'my_callback' ); // receives $more

Modifica una query PRIMA che venga eseguita. Il modo corretto per cambiare ciò che appare in un archivio — molto meglio di una seconda WP_Query.

Quando si attiva

Dopo che le variabili della query sono state analizzate, prima che venga costruito l'SQL.

Firma

add_action( 'pre_get_posts', 'my_callback' ); // receives WP_Query $query (by reference)

Esempio

add_action( 'pre_get_posts', function ( $query ) {
    if ( is_admin() || ! $query->is_main_query() ) {
        return; // <- both guards are mandatory
    }
    if ( $query->is_category() ) {
        $query->set( 'posts_per_page', 12 );
    }
} );

L'insidia

Viene eseguito anche nell'area di AMMINISTRAZIONE, e viene eseguito per OGNI query, inclusi menu, widget e libreria media. Ometti i controlli is_admin() e is_main_query() e cambierai silenziosamente ciò che mostra l'elenco degli articoli nell'amministrazione — un bug davvero difficile da rintracciare. Nota anche: modifica $query, non restituire nulla.

Filtra la clausola SQL WHERE grezza di una query.

Quando si attiva

Mentre l'SQL della query viene assemblato.

Firma

add_filter( 'posts_where', 'my_callback', 10, 2 ); // receives $where, WP_Query $query

L'insidia

Stai scrivendo SQL grezzo. Proteggi sempre con $query->is_main_query() e usa sempre $wpdb->prepare() per qualsiasi input dell'utente. È il modo più rapido per introdurre una SQL injection in un sito WordPress.

Filtra il numero totale di articoli trovati da una query — che è ciò da cui viene calcolata la paginazione.

Quando si attiva

Dopo l'esecuzione della query, prima che venga calcolata la paginazione.

Firma

add_filter( 'found_posts', 'my_callback', 10, 2 ); // receives $found_posts, WP_Query $query

Imposta la dimensione in pixel oltre la quale WordPress riduce un caricamento e serve una copia "-scaled" invece dell'originale. Valore predefinito 2560.

Quando si attiva

Al caricamento, quando WordPress decide se un'immagine è "grande".

Firma

add_filter( 'big_image_size_threshold', 'my_callback' ); // receives int $threshold

Esempio

// Serve originals at full resolution — no -scaled copy.
add_filter( 'big_image_size_threshold', '__return_false' );

// Or just raise the ceiling:
add_filter( 'big_image_size_threshold', function () {
    return 3840;
} );

L'insidia

È la causa più comune in assoluto del problema "la mia immagine appare sfocata dopo il caricamento su WordPress", e quasi nessuno sa che esiste. Il tuo originale è ancora sul disco — semplicemente non viene mai servito. Nota che si applica al lato più LUNGO e riguarda solo le immagini caricate dopo l'attivazione del filtro.

Filtra l'array delle dimensioni delle immagini che WordPress sta per generare per un caricamento. Rimuovi una dimensione per smettere di generarla.

Quando si attiva

Al caricamento, prima che vengano creati i file derivati.

Firma

add_filter( 'intermediate_image_sizes_advanced', 'my_callback', 10, 2 ); // receives $sizes, $metadata

Esempio

add_filter( 'intermediate_image_sizes_advanced', function ( $sizes ) {
    unset( $sizes['1536x1536'] );
    unset( $sizes['2048x2048'] );
    return $sizes;
} );

L'insidia

Rimuovere una dimensione che il tuo tema USA davvero significa che WordPress ripiega sull'originale a grandezza piena — il che è peggio dello spazio su disco che hai risparmiato. E questo impedisce solo la creazione di NUOVI file; quelli esistenti restano finché non li rigeneri.

Imposta la qualità JPEG con cui WordPress ricodifica le immagini caricate. Valore predefinito 82.

Quando si attiva

Ogni volta che WordPress scrive un JPEG.

Firma

add_filter( 'jpeg_quality', 'my_callback', 10, 2 ); // receives $quality, $context

L'insidia

La qualità 82 va bene per le fotografie ma è visibilmente scarsa per screenshot, logo e grafiche piatte — questi hanno bordi netti e nessun rumore fotografico in cui nascondere gli artefatti. Inoltre: wp_editor_set_quality è il filtro più moderno e copre direttamente le classi dell'editor delle immagini; è comune impostarli entrambi.

Imposta la qualità di output usata dalle classi WP_Image_Editor (GD e Imagick).

Quando si attiva

Quando un'istanza dell'editor delle immagini imposta la propria qualità.

Firma

add_filter( 'wp_editor_set_quality', 'my_callback', 10, 2 ); // receives $quality, $mime_type

Aggiunge le tue dimensioni immagine personalizzate al menu a tendina delle dimensioni nella finestra dei media e nell'editor a blocchi.

Quando si attiva

Quando l'interfaccia dei media costruisce il proprio selettore delle dimensioni.

Firma

add_filter( 'image_size_names_choose', 'my_callback' ); // receives $sizes

Esempio

add_filter( 'image_size_names_choose', function ( $sizes ) {
    return array_merge( $sizes, array( 'card' => __( 'Card', 'textdomain' ) ) );
} );

L'insidia

add_image_size() registra la dimensione ma NON la rende selezionabile nell'editor. Ogni domanda del tipo "la mia dimensione immagine personalizzata non appare nel menu a tendina" è questo filtro che manca.

Ispeziona o rifiuta un file PRIMA che venga spostato nella cartella dei caricamenti.

Quando si attiva

Durante il caricamento, prima che il file venga scritto.

Firma

add_filter( 'wp_handle_upload_prefilter', 'my_callback' ); // receives $file

L'insidia

Per rifiutare un file, imposta $file['error'] su una stringa di messaggio e restituisci $file. Restituire false o lanciare un'eccezione non farà ciò che desideri.

Filtra l'array dei metadati (incluse le dimensioni generate) dopo che un allegato è stato elaborato.

Quando si attiva

Dopo che le immagini derivate sono state create al caricamento.

Firma

add_filter( 'wp_generate_attachment_metadata', 'my_callback', 10, 2 ); // receives $metadata, $attachment_id

L'insidia

È l'hook che usano i plugin di ottimizzazione delle immagini. Può essere lento — viene eseguito dopo che ogni dimensione dell'immagine è stata scritta, e fare una richiesta HTTP qui fa aspettare ogni caricamento.

Filtra i candidati srcset che WordPress genera per un'immagine responsive.

Quando si attiva

Quando viene renderizzata un'immagine responsive.

Firma

add_filter( 'wp_calculate_image_srcset', 'my_callback', 10, 5 );

L'insidia

Rimuovere altrove la dimensione medium_large (768w) degrada silenziosamente srcset — quella dimensione esiste quasi esclusivamente per alimentarlo.

Non abbiamo verificato il numero esatto di argomenti di questo hook rispetto al sorgente di WordPress. Controlla developer.wordpress.org prima di affidartici. Preferiamo segnalare l'incertezza piuttosto che spacciare in silenzio una supposizione per un dato di fatto.

Registra le pagine del menu e del sottomenu di amministrazione.

Quando si attiva

Quando viene costruito il menu di amministrazione.

Firma

add_action( 'admin_menu', 'my_callback' );

Esempio

add_action( 'admin_menu', function () {
    add_options_page(
        'My Plugin',
        'My Plugin',
        'manage_options',   // capability — NOT a role
        'my-plugin',
        'my_render_settings_page'
    );
} );

L'insidia

L'argomento capability è una CAPABILITY, non un ruolo. Passare "administrator" sembra funzionare (perché in alcune configurazioni gli amministratori hanno una capability con quel nome) e poi concede silenziosamente l'accesso alle persone sbagliate. Usa manage_options.

Stampa un avviso in cima a una schermata di amministrazione.

Quando si attiva

Al rendering della pagina di amministrazione.

Firma

add_action( 'admin_notices', 'my_callback' );

L'insidia

Viene eseguito su OGNI schermata di amministrazione. Un plugin che mostra un avviso incondizionato "grazie per l'installazione!" su tutte è il pattern più odiato in assoluto nell'amministrazione di WordPress. Proteggilo e rendilo chiudibile.

Viene eseguito ogni volta che un articolo viene creato o aggiornato. Il posto abituale per salvare i dati dei meta box.

Quando si attiva

Dopo che un articolo viene scritto nel database.

Firma

add_action( 'save_post', 'my_callback', 10, 3 ); // receives $post_id, $post, $update

Esempio

add_action( 'save_post', function ( $post_id ) {
    if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) return;
    if ( wp_is_post_revision( $post_id ) ) return;
    if ( ! current_user_can( 'edit_post', $post_id ) ) return;
    // ... now it is safe to save
}, 10, 1 );

L'insidia

Viene eseguito sui SALVATAGGI AUTOMATICI e sulle REVISIONI oltre che sui salvataggi reali. Senza i tre controlli sopra, i tuoi metadati vengono sovrascritti con valori vuoti ogni volta che l'editor salva automaticamente — un bug che sembra dati che spariscono a caso.

Registra i meta box nella schermata di modifica dell'articolo.

Quando si attiva

Quando viene costruita la schermata di modifica.

Firma

add_action( 'add_meta_boxes', 'my_callback', 10, 2 ); // receives $post_type, $post

L'insidia

I meta box classici non appaiono nell'editor a blocchi a meno che l'editor a blocchi non ripieghi sulla modalità di compatibilità. Per un sito nativo per l'editor a blocchi, registra i post meta con show_in_rest e costruisci invece un pannello nella barra laterale.

Viene eseguito dopo che un utente ha effettuato l'accesso con successo.

Quando si attiva

In caso di autenticazione riuscita.

Firma

add_action( 'wp_login', 'my_callback', 10, 2 ); // receives $user_login, WP_User $user

Viene eseguito immediatamente dopo la creazione di un nuovo utente.

Quando si attiva

Alla registrazione.

Firma

add_action( 'user_register', 'my_callback', 10, 2 ); // receives $user_id, $userdata

Filtra il risultato dell'autenticazione. Restituisci un WP_Error per bloccare un accesso.

Quando si attiva

Durante il tentativo di accesso.

Firma

add_filter( 'authenticate', 'my_callback', 30, 3 ); // receives $user, $username, $password

L'insidia

Qui la priorità conta molto. Il core di WordPress aggancia i propri controlli alle priorità 20 e 30 — aggancia troppo presto e verrai eseguito prima ancora che la password sia stata verificata.

Registra le route e i campi REST.

Quando si attiva

Quando la REST API si inizializza.

Firma

add_action( 'rest_api_init', 'my_callback' );

Esempio

add_action( 'rest_api_init', function () {
    register_rest_route( 'myplugin/v1', '/items', array(
        'methods'             => 'GET',
        'callback'            => 'my_get_items',
        'permission_callback' => '__return_true', // BE DELIBERATE ABOUT THIS
    ) );
} );

L'insidia

permission_callback è OBBLIGATORIO — da WP 5.5 ometterlo genera un notice, e impostarlo su __return_true rende l'endpoint completamente pubblico. Va bene per dati realmente pubblici ma è una grave falla per tutto il resto. Decidi, non affidarti al valore predefinito.

Aggiunge un intervallo di ricorrenza personalizzato per wp_schedule_event().

Quando si attiva

Quando WordPress costruisce il proprio elenco di pianificazioni disponibili.

Firma

add_filter( 'cron_schedules', 'my_callback' ); // receives $schedules

Esempio

add_filter( 'cron_schedules', function ( $schedules ) {
    $schedules['every_five_minutes'] = array(
        'interval' => 300,             // seconds
        'display'  => __( 'Every 5 minutes', 'textdomain' ),
    );
    return $schedules;
} );

L'insidia

WP-Cron non è un vero cron. Viene eseguito solo quando qualcuno visita il sito, quindi un sito con poco traffico non eseguirà una pianificazione di cinque minuti ogni cinque minuti. Se la tempistica conta davvero, disabilita WP-Cron (DISABLE_WP_CRON) e chiama wp-cron.php da un vero cron di sistema.

Viene eseguito immediatamente dopo che un commento viene salvato.

Quando si attiva

All'invio del commento.

Firma

add_action( 'comment_post', 'my_callback', 10, 3 ); // receives $comment_id, $approved, $commentdata

Filtra i dati del commento prima che venga salvato. Usato per i controlli antispam e la validazione.

Quando si attiva

Prima che il commento venga scritto.

Firma

add_filter( 'preprocess_comment', 'my_callback' ); // receives $commentdata

L'insidia

Per rifiutare un commento qui, chiama wp_die() con un messaggio — restituire false non lo blocca.

Viene eseguito sulla pagina di ordine ricevuto dopo un checkout riuscito.

Quando si attiva

Quando il cliente arriva sulla pagina di ringraziamento.

Firma

add_action( 'woocommerce_thankyou', 'my_callback' ); // receives $order_id

L'insidia

NON è un posto affidabile per attivare l'evasione dell'ordine. Viene eseguito solo se il cliente raggiunge effettivamente la pagina di ringraziamento — se chiude la scheda dopo aver pagato, non viene mai eseguito. Usa woocommerce_payment_complete o un hook di transizione dello stato dell'ordine per qualsiasi cosa che debba accadere.

Produce markup immediatamente prima del pulsante aggiungi al carrello in una pagina prodotto.

Quando si attiva

Mentre la pagina prodotto viene renderizzata.

Firma

add_action( 'woocommerce_before_add_to_cart_button', 'my_callback' );

Aggiunge, rimuove o riordina i campi del checkout classico.

Quando si attiva

Quando viene costruito il modulo di checkout.

Firma

add_filter( 'woocommerce_checkout_fields', 'my_callback' ); // receives $fields

L'insidia

Riguarda solo il checkout CLASSICO (shortcode). Il più recente checkout basato su blocchi lo ignora completamente e viene personalizzato tramite Slot & Fill in JavaScript. Questo inganna quasi tutti la prima volta.