Index al hook-urilor WordPress

Un index căutabil al acțiunilor și filtrelor WordPress pe care dezvoltatorii chiar le folosesc — cu semnătura exactă add_action/add_filter, când se declanșează, un exemplu funcțional și lucrul care le dă bătăi de cap.

39 hook-uri, cu semnătura exactă add_action / add_filter, momentul în care se declanșează, un exemplu funcțional și lucrul de care se împiedică toată lumea. 1 sunt marcate ca neverificate — nu am confruntat numărul lor de argumente cu sursa WordPress și preferăm să semnalăm asta decât să prezentăm o presupunere drept fapt.

Lista nu este exhaustivă și nici nu pretinde să fie — WordPress are mii de hook-uri. Le acoperă pe cele la care se apelează cu adevărat în practică.

39 din 39

Se execută după ce WordPress a terminat de încărcat, dar înainte să fie trimis vreun antet. Locul standard pentru a înregistra tipuri de conținut personalizate, taxonomii și reguli de rescriere.

Se declanșează

La fiecare cerere, atât în front-end, cât și în administrare, după ce nucleul, pluginurile și tema sunt încărcate.

Semnătură

add_action( 'init', 'my_callback' );

Exemplu

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

Capcana

init se execută la FIECARE cerere, inclusiv AJAX, REST și cron. Orice operațiune lentă aici (o cerere HTTP, o interogare grea) îngreunează fiecare încărcare de pagină. De asemenea: utilizatorul curent este disponibil aici, dar nu poți afișa nimic — antetele încă nu au fost trimise, dar sunt pe cale să fie.

Se execută odată ce tema este încărcată. Locul corect pentru add_theme_support(), add_image_size() și înregistrarea meniurilor de navigare.

Se declanșează

După ce este încărcat functions.php al temei, ÎNAINTE de init.

Semnătură

add_action( 'after_setup_theme', 'my_callback' );

Exemplu

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
} );

Capcana

Înregistrarea dimensiunilor de imagine pe init în loc de aici funcționează din întâmplare în majoritatea cazurilor și apoi eșuează misterios în unele. Folosește after_setup_theme — exact pentru asta există.

Se execută odată ce toate pluginurile active sunt încărcate. Cel mai devreme moment sigur pentru a interacționa cu un alt plugin.

Se declanșează

După ce fiecare fișier de plugin este inclus, înainte ca tema să fie încărcată.

Semnătură

add_action( 'plugins_loaded', 'my_callback' );

Capcana

Utilizatorul curent NU este încă disponibil aici — wp_get_current_user() nu va funcționa în mod fiabil. Dacă ai nevoie de utilizator, folosește init.

Se execută după ce WordPress este complet încărcat — pluginurile, tema, init și utilizatorul sunt toate gata.

Se declanșează

După init și după ce utilizatorul curent este configurat.

Semnătură

add_action( 'wp_loaded', 'my_callback' );

Se execută la începutul fiecărei cereri de administrare. Folosit pentru register_setting(), verificări de permisiuni și redirecționări în administrare.

Se declanșează

La fiecare cerere din partea de administrare.

Semnătură

add_action( 'admin_init', 'my_callback' );

Capcana

Se declanșează și pe cererile admin-ajax.php, care nu sunt cu adevărat „ecrane de administrare”. Dacă funcția ta de callback presupune că există un ecran, protejeaz-o cu wp_doing_ajax().

Singurul loc corect pentru a înregistra (enqueue) CSS și JavaScript pentru front-end.

Se declanșează

La încărcarea paginilor din front-end, înainte ca head-ul să fie randat.

Semnătură

add_action( 'wp_enqueue_scripts', 'my_callback' );

Exemplu

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
    );
} );

Capcana

În ciuda numelui, gestionează STILURILE la fel de bine ca scripturile — nu există un hook wp_enqueue_styles, iar oamenii pierd timp real căutându-l. De asemenea: acesta nu se declanșează în administrare (folosește admin_enqueue_scripts) sau în editorul de blocuri (folosește enqueue_block_editor_assets).

Înregistrează (enqueue) CSS/JS în administrare. Primește sufixul de hook al ecranului curent, astfel încât poți încărca resurse pe un singur ecran.

Se declanșează

La încărcarea paginilor de administrare.

Semnătură

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

Exemplu

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 );
} );

Capcana

Neprotejarea pe baza lui $hook este cea mai frecventă cauză a unui plugin care strică ecrane de administrare fără legătură. Încarcă-ți resursele acolo unde sunt necesare și nicăieri altundeva.

Înregistrează (enqueue) resurse doar în editorul de blocuri (Gutenberg) — nu în front-end, nu în restul administrării.

Se declanșează

Când se încarcă editorul de blocuri.

Semnătură

add_action( 'enqueue_block_editor_assets', 'my_callback' );

Afișează conținut în <head>. Folosit pentru metaetichete și CSS critic inline.

Se declanșează

În interiorul <head>, în front-end.

Semnătură

add_action( 'wp_head', 'my_callback' );

Capcana

NU înregistra (enqueue) scripturi sau stiluri aici — folosește wp_enqueue_scripts, care lasă WordPress să gestioneze dependențele și deduplicarea. Afișarea directă a unei etichete <script> în wp_head ocolește tot acest mecanism și este motivul pentru care atâtea site-uri încarcă jQuery de trei ori.

Afișează conținut chiar înainte de </body>. Locul potrivit pentru fragmentele de analytics și marcajul amânat.

Se declanșează

La sfârșitul paginii de front-end.

Semnătură

add_action( 'wp_footer', 'my_callback' );

Capcana

O temă care uită să apeleze wp_footer() strică bara de administrare, strică orice plugin care înregistrează un script în subsol și duce la respingerea automată în evaluarea temelor de pe wordpress.org.

Filtrează conținutul articolului chiar înainte de a fi afișat. Locul obișnuit pentru a adăuga marcaj la începutul sau la sfârșitul unui articol.

Se declanșează

De fiecare dată când este apelat the_content().

Semnătură

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

Exemplu

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>';
} );

Capcana

Se execută mult mai des decât crezi — în widgeturi, în răspunsurile REST, în generarea rezumatelor din unele pluginuri și o dată pe articol într-o buclă pe o arhivă. Fără verificarea is_singular / in_the_loop / is_main_query, îndemnul tău la acțiune apare de cincisprezece ori pe indexul blogului și în feedul RSS. Acesta este cel mai prost folosit filtru din WordPress.

Filtrează titlul articolului înainte de afișare.

Se declanșează

De fiecare dată când este apelat the_title() sau get_the_title().

Semnătură

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

Capcana

Se declanșează și pentru titlurile din meniul de administrare, din meniurile de navigare și din <title>-ul documentului. Filtrarea lui necondiționată va redenumi lucruri în locuri neintenționate.

Stabilește câte CUVINTE conține un rezumat generat automat. Valoarea implicită este 55.

Se declanșează

Când WordPress generează un rezumat pentru un articol care nu are un rezumat manual.

Semnătură

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

Exemplu

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

Capcana

Nu are niciun efect asupra articolelor care au un rezumat MANUAL — acelea sunt folosite ca atare. Și multe teme setează ele însele acest filtru, așa că de multe ori ai nevoie de un număr de prioritate mare pentru a câștiga.

Schimbă șirul de caractere adăugat la un rezumat trunchiat. Valoarea implicită este „ […]”.

Se declanșează

Când un rezumat generat automat este trunchiat.

Semnătură

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

Modifică o interogare ÎNAINTE de a fi executată. Modul corect de a schimba ceea ce apare pe o arhivă — mult mai bun decât un al doilea WP_Query.

Se declanșează

După ce variabilele de interogare sunt analizate, înainte ca SQL-ul să fie construit.

Semnătură

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

Exemplu

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 );
    }
} );

Capcana

Se execută și în ADMINISTRARE și se execută pentru FIECARE interogare, inclusiv meniuri, widgeturi și biblioteca media. Omite verificările is_admin() și is_main_query() și vei modifica în tăcere ceea ce afișează lista de articole din administrare — o eroare cu adevărat greu de depistat. Reține și: modifică $query, nu returna nimic.

Filtrează clauza SQL WHERE brută a unei interogări.

Se declanșează

În timp ce SQL-ul interogării este asamblat.

Semnătură

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

Capcana

Scrii SQL brut. Protejează întotdeauna cu $query->is_main_query() și folosește întotdeauna $wpdb->prepare() pentru orice date introduse de utilizator. Acesta este cel mai rapid mod de a introduce o injecție SQL într-un site WordPress.

Filtrează numărul total de articole găsite de o interogare — pe baza căruia se calculează paginarea.

Se declanșează

După ce interogarea se execută, înainte ca paginarea să fie calculată.

Semnătură

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

Stabilește dimensiunea în pixeli peste care WordPress micșorează un fișier încărcat și servește o copie „-scaled” în locul originalului tău. Implicit 2560.

Se declanșează

La încărcare, când WordPress decide dacă o imagine este „mare”.

Semnătură

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

Exemplu

// 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;
} );

Capcana

Aceasta este cea mai frecventă cauză a problemei „imaginea mea arată neclară după ce am încărcat-o în WordPress” și aproape nimeni nu știe că există. Originalul tău este încă pe disc — pur și simplu nu este servit niciodată. Reține că se aplică laturii CELEI MAI LUNGI și afectează doar imaginile încărcate după ce filtrul este activ.

Filtrează tabloul de dimensiuni de imagine pe care WordPress este pe cale să le genereze pentru un fișier încărcat. Elimină (unset) o dimensiune pentru a opri generarea ei.

Se declanșează

La încărcare, înainte ca fișierele derivate să fie create.

Semnătură

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

Exemplu

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

Capcana

Eliminarea unei dimensiuni pe care tema ta chiar o FOLOSEȘTE înseamnă că WordPress recurge la originalul la dimensiune completă — ceea ce este mai rău decât spațiul pe disc pe care l-ai economisit. Și asta oprește doar crearea fișierelor NOI; cele existente rămân până când le regenerezi.

Stabilește calitatea JPEG la care WordPress recodează imaginile încărcate. Implicit 82.

Se declanșează

Ori de câte ori WordPress scrie un JPEG.

Semnătură

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

Capcana

Calitatea 82 este bună pentru fotografii și vizibil slabă pentru capturi de ecran, logouri și grafică plată — acestea au margini clare și nu au zgomot fotografic în care să ascundă artefactele. De asemenea: wp_editor_set_quality este filtrul mai modern și acoperă direct clasele editorului de imagini; setarea ambelor este frecventă.

Stabilește calitatea de ieșire folosită de clasele WP_Image_Editor (GD și Imagick).

Se declanșează

Când o instanță a editorului de imagini își setează calitatea.

Semnătură

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

Adaugă dimensiunile tale de imagine personalizate în lista derulantă de dimensiuni din fereastra media și din editorul de blocuri.

Se declanșează

Când interfața media își construiește selectorul de dimensiuni.

Semnătură

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

Exemplu

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

Capcana

add_image_size() înregistrează dimensiunea, dar NU o face selectabilă în editor. Fiecare întrebare de tipul „dimensiunea mea de imagine personalizată nu apare în lista derulantă” se datorează lipsei acestui filtru.

Inspectează sau respinge un fișier ÎNAINTE de a fi mutat în folderul de încărcări.

Se declanșează

În timpul încărcării, înainte ca fișierul să fie scris.

Semnătură

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

Capcana

Pentru a respinge un fișier, setează $file['error'] la un șir cu un mesaj și returnează $file. Returnarea lui false sau aruncarea unei excepții nu va face ceea ce vrei.

Filtrează tabloul de metadate (inclusiv dimensiunile generate) după ce un atașament este procesat.

Se declanșează

După ce imaginile derivate sunt create la încărcare.

Semnătură

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

Capcana

Acesta este hook-ul pe care îl folosesc pluginurile de optimizare a imaginilor. Poate fi lent — se execută după ce fiecare dimensiune de imagine este scrisă, iar o cerere HTTP aici face ca fiecare încărcare să aștepte după el.

Filtrează candidații srcset pe care WordPress îi generează pentru o imagine responsivă.

Se declanșează

Când o imagine responsivă este randată.

Semnătură

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

Capcana

Eliminarea dimensiunii medium_large (768w) în altă parte degradează în tăcere srcset — acea dimensiune există aproape exclusiv pentru a-l alimenta.

Nu am verificat numărul exact de argumente al acestui hook față de sursa WordPress. Verifică developer.wordpress.org înainte să te bazezi pe el. Preferăm să semnalăm incertitudinea decât să prezentăm pe tăcute o presupunere drept fapt.

Înregistrează paginile din meniul și submeniul de administrare.

Se declanșează

Când meniul de administrare este construit.

Semnătură

add_action( 'admin_menu', 'my_callback' );

Exemplu

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

Capcana

Argumentul capability este o CAPABILITATE, nu un rol. Trecerea lui „administrator” pare să funcționeze (pentru că administratorii au o capabilitate cu acest nume în unele configurări) și apoi acordă în tăcere acces persoanelor greșite. Folosește manage_options.

Afișează o notificare în partea de sus a unui ecran de administrare.

Se declanșează

La randarea paginii de administrare.

Semnătură

add_action( 'admin_notices', 'my_callback' );

Capcana

Se declanșează pe FIECARE ecran de administrare. Un plugin care afișează o notificare necondiționată „mulțumim pentru instalare!” pe toate acestea este cel mai urât tipar din administrarea WordPress. Protejeaz-o și fă-o să poată fi închisă.

Se execută ori de câte ori un articol este creat sau actualizat. Locul obișnuit pentru a salva datele din meta box.

Se declanșează

După ce un articol este scris în baza de date.

Semnătură

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

Exemplu

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 );

Capcana

Se declanșează la SALVĂRILE AUTOMATE și la REVIZII, nu doar la salvările reale. Fără cele trei verificări de mai sus, metadatele tale sunt suprascrise cu valori goale de fiecare dată când editorul salvează automat — o eroare care arată ca și cum datele dispar la întâmplare.

Înregistrează meta box-uri pe ecranul de editare a articolului.

Se declanșează

Când ecranul de editare este construit.

Semnătură

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

Capcana

Meta box-urile clasice nu apar în editorul de blocuri decât dacă acesta revine la modul de compatibilitate. Pentru un site nativ pentru editorul de blocuri, înregistrează metadatele articolului cu show_in_rest și construiește în schimb un panou în bara laterală.

Se execută după ce un utilizator se autentifică cu succes.

Se declanșează

La autentificarea reușită.

Semnătură

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

Se execută imediat după ce un utilizator nou este creat.

Se declanșează

La înregistrare.

Semnătură

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

Filtrează rezultatul autentificării. Returnează un WP_Error pentru a bloca o autentificare.

Se declanșează

În timpul încercării de autentificare.

Semnătură

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

Capcana

Prioritatea contează mult aici. Nucleul WordPress își atașează propriile verificări la prioritățile 20 și 30 — dacă te atașezi prea devreme, te execuți înainte ca parola să fi fost măcar verificată.

Înregistrează rute și câmpuri REST.

Se declanșează

Când API-ul REST se inițializează.

Semnătură

add_action( 'rest_api_init', 'my_callback' );

Exemplu

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
    ) );
} );

Capcana

permission_callback este OBLIGATORIU — de la WP 5.5, omiterea lui generează o notificare, iar setarea lui la __return_true face endpointul complet public. Este în regulă pentru date cu adevărat publice și o breșă serioasă pentru orice altceva. Decide, nu lăsa pe valoarea implicită.

Adaugă un interval de recurență personalizat pentru wp_schedule_event().

Se declanșează

Când WordPress își construiește lista de programări disponibile.

Semnătură

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

Exemplu

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

Capcana

WP-Cron nu este un cron real. Se declanșează doar când cineva vizitează site-ul, așa că un site cu trafic redus nu va executa o programare de cinci minute la fiecare cinci minute. Dacă sincronizarea chiar contează, dezactivează WP-Cron (DISABLE_WP_CRON) și apelează wp-cron.php dintr-un cron de sistem real.

Se execută imediat după ce un comentariu este salvat.

Se declanșează

La trimiterea comentariului.

Semnătură

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

Filtrează datele comentariului înainte de a fi salvate. Folosit pentru verificări de spam și validare.

Se declanșează

Înainte ca comentariul să fie scris.

Semnătură

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

Capcana

Pentru a respinge un comentariu aici, apelează wp_die() cu un mesaj — returnarea lui false nu îl oprește.

Se execută pe pagina de comandă primită după o finalizare reușită a comenzii.

Se declanșează

Când clientul ajunge pe pagina de mulțumire.

Semnătură

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

Capcana

Acesta NU este un loc de încredere pentru a declanșa onorarea comenzii. Se declanșează doar dacă clientul ajunge efectiv pe pagina de mulțumire — dacă închide fila după ce a plătit, nu se execută niciodată. Folosește woocommerce_payment_complete sau un hook de tranziție a stării comenzii pentru orice trebuie neapărat să se întâmple.

Afișează marcaj imediat înainte de butonul de adăugare în coș de pe o pagină de produs.

Se declanșează

În timp ce pagina de produs este randată.

Semnătură

add_action( 'woocommerce_before_add_to_cart_button', 'my_callback' );

Adaugă, elimină sau reordonează câmpuri la finalizarea clasică a comenzii.

Se declanșează

Când formularul de finalizare a comenzii este construit.

Semnătură

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

Capcana

Acesta afectează doar finalizarea comenzii CLASICĂ (bazată pe shortcode). Finalizarea mai nouă, bazată pe blocuri, îl ignoră complet și se personalizează prin Slot & Fill în JavaScript. Asta încurcă aproape pe toată lumea prima dată.