Indeks haków WordPressa

Przeszukiwalny indeks akcji i filtrów WordPressa, których deweloperzy naprawdę używają — z dokładną sygnaturą add_action/add_filter, informacją, kiedy się uruchamia, działającym przykładem i tym, co potrafi zaskoczyć.

39 hooków — każdy z dokładną sygnaturą add_action / add_filter, momentem wywołania, działającym przykładem i pułapką, w którą najłatwiej wpaść. 1 oznaczono jako niezweryfikowane — nie sprawdziliśmy liczby ich argumentów w źródłach WordPress i wolimy to zaznaczyć, niż podawać domysł jako fakt.

To nie jest pełna lista i nie udaje takiej — WordPress ma tysiące hooków. Zebraliśmy te, po które ludzie faktycznie sięgają.

39 z 39

Uruchamia się po zakończeniu ładowania WordPressa, ale przed wysłaniem jakichkolwiek nagłówków. Standardowe miejsce do rejestrowania własnych typów treści, taksonomii i reguł przepisywania.

Wywoływany

Przy każdym żądaniu, na frontendzie i w panelu, po załadowaniu rdzenia, wtyczek i motywu.

Sygnatura

add_action( 'init', 'my_callback' );

Przykład

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

Pułapka

init uruchamia się przy KAŻDYM żądaniu, w tym AJAX, REST i cron. Robienie tu czegokolwiek wolnego (żądanie HTTP, ciężkie zapytanie) obciąża każde wczytanie strony. Ponadto: bieżący użytkownik jest tu dostępny, ale nie możesz niczego wypisać — nagłówki jeszcze nie zostały wysłane, ale zaraz zostaną.

Uruchamia się po załadowaniu motywu. Właściwe miejsce na add_theme_support(), add_image_size() i rejestrowanie menu nawigacyjnych.

Wywoływany

Po załadowaniu pliku functions.php motywu, PRZED init.

Sygnatura

add_action( 'after_setup_theme', 'my_callback' );

Przykład

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

Pułapka

Rejestrowanie rozmiarów obrazów na init zamiast tutaj w większości przypadków działa przypadkiem, a w niektórych zawodzi w tajemniczy sposób. Używaj after_setup_theme — właśnie od tego jest.

Uruchamia się po załadowaniu wszystkich aktywnych wtyczek. Najwcześniejszy bezpieczny moment na interakcję z inną wtyczką.

Wywoływany

Po dołączeniu każdego pliku wtyczki, przed załadowaniem motywu.

Sygnatura

add_action( 'plugins_loaded', 'my_callback' );

Pułapka

Bieżący użytkownik NIE jest tu jeszcze dostępny — wp_get_current_user() nie zadziała niezawodnie. Jeśli potrzebujesz użytkownika, użyj init.

Uruchamia się po pełnym załadowaniu WordPressa — wtyczki, motyw, init i użytkownik są już gotowe.

Wywoływany

Po init i po skonfigurowaniu bieżącego użytkownika.

Sygnatura

add_action( 'wp_loaded', 'my_callback' );

Uruchamia się na początku każdego żądania w panelu. Używany do register_setting(), sprawdzania uprawnień i przekierowań w panelu.

Wywoływany

Przy każdym żądaniu po stronie panelu.

Sygnatura

add_action( 'admin_init', 'my_callback' );

Pułapka

Uruchamia się też przy żądaniach admin-ajax.php, które tak naprawdę nie są „ekranami panelu”. Jeśli twój callback zakłada, że istnieje ekran, zabezpiecz go przez wp_doing_ajax().

Jedyne właściwe miejsce do kolejkowania CSS i JavaScriptu na frontendzie.

Wywoływany

Przy wczytywaniu stron na frontendzie, przed wyrenderowaniem sekcji head.

Sygnatura

add_action( 'wp_enqueue_scripts', 'my_callback' );

Przykład

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

Pułapka

Mimo nazwy obsługuje STYLE tak samo jak skrypty — nie ma haka wp_enqueue_styles, a ludzie tracą sporo czasu na jego szukanie. Ponadto: nie uruchamia się w panelu (użyj admin_enqueue_scripts) ani w edytorze bloków (użyj enqueue_block_editor_assets).

Kolejkowanie CSS/JS w panelu. Otrzymuje sufiks haka bieżącego ekranu, dzięki czemu możesz ładować zasoby tylko na jednym ekranie.

Wywoływany

Przy wczytywaniu stron panelu.

Sygnatura

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

Przykład

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

Pułapka

Brak zabezpieczenia na $hook to najczęstsza pojedyncza przyczyna, dla której wtyczka psuje niepowiązane ekrany panelu. Ładuj zasoby tam, gdzie są potrzebne, i nigdzie indziej.

Kolejkowanie zasobów wyłącznie w edytorze bloków (Gutenberg) — nie na frontendzie i nie w reszcie panelu.

Wywoływany

Gdy ładuje się edytor bloków.

Sygnatura

add_action( 'enqueue_block_editor_assets', 'my_callback' );

Wypisuje treść do sekcji <head>. Używany do metatagów i wbudowanego krytycznego CSS.

Wywoływany

Wewnątrz <head>, na frontendzie.

Sygnatura

add_action( 'wp_head', 'my_callback' );

Pułapka

NIE kolejkuj tu skryptów ani stylów — użyj wp_enqueue_scripts, który pozwala WordPressowi obsłużyć zależności i eliminację duplikatów. Wypisanie znacznika <script> do wp_head omija to wszystko i dlatego tyle witryn ładuje jQuery trzy razy.

Wypisuje treść tuż przed </body>. Właściwe miejsce na fragmenty kodu analitycznego i odroczone znaczniki.

Wywoływany

Na końcu strony na frontendzie.

Sygnatura

add_action( 'wp_footer', 'my_callback' );

Pułapka

Motyw, który zapomni wywołać wp_footer(), psuje pasek administracyjny, psuje każdą wtyczkę kolejkującą skrypt w stopce i jest automatycznie odrzucany w recenzji motywów na wordpress.org.

Filtruje treść wpisu tuż przed jej wyświetleniem. Typowe miejsce, by dodać znaczniki na początku lub końcu wpisu.

Wywoływany

Za każdym razem, gdy wywoływane jest the_content().

Sygnatura

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

Przykład

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

Pułapka

Uruchamia się znacznie częściej, niż myślisz — w widżetach, w odpowiedziach REST, przy generowaniu zajawek przez niektóre wtyczki i raz na wpis w pętli na stronie archiwum. Bez zabezpieczenia is_singular / in_the_loop / is_main_query twoje wezwanie do działania pojawia się piętnaście razy na stronie głównej bloga i w kanale RSS. To najczęściej nadużywany filtr w WordPressie.

Filtruje tytuł wpisu przed wyświetleniem.

Wywoływany

Za każdym razem, gdy wywoływane jest the_title() lub get_the_title().

Sygnatura

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

Pułapka

Uruchamia się też dla tytułów w menu panelu, w menu nawigacyjnych i w znaczniku <title> dokumentu. Filtrowanie go bezwarunkowo zmieni nazwy w miejscach, których nie zamierzałeś.

Ustawia, ile SŁÓW zawiera automatycznie generowana zajawka. Domyślnie 55.

Wywoływany

Gdy WordPress generuje zajawkę dla wpisu, który nie ma ręcznie ustawionej zajawki.

Sygnatura

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

Przykład

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

Pułapka

Nie ma wpływu na wpisy z RĘCZNIE ustawioną zajawką — te są używane dosłownie. Wiele motywów samo ustawia ten filtr, więc często potrzebujesz wysokiego numeru priorytetu, aby wygrać.

Zmienia ciąg znaków dołączany do skróconej zajawki. Domyślnie „ […]”.

Wywoływany

Gdy automatycznie generowana zajawka jest skracana.

Sygnatura

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

Modyfikuje zapytanie PRZED jego uruchomieniem. Właściwy sposób na zmianę tego, co pojawia się na archiwum — znacznie lepszy niż drugie WP_Query.

Wywoływany

Po sparsowaniu zmiennych zapytania, przed zbudowaniem SQL.

Sygnatura

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

Przykład

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

Pułapka

Uruchamia się też w PANELU i przy KAŻDYM zapytaniu, w tym w menu, widżetach i bibliotece mediów. Pomiń zabezpieczenia is_admin() i is_main_query(), a po cichu zmienisz to, co pokazuje lista wpisów w panelu — błąd, który naprawdę trudno wytropić. Zwróć też uwagę: modyfikuj $query, niczego nie zwracaj.

Filtruje surową klauzulę SQL WHERE zapytania.

Wywoływany

Podczas składania SQL zapytania.

Sygnatura

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

Pułapka

Piszesz surowy SQL. Zawsze zabezpieczaj przez $query->is_main_query() i zawsze używaj $wpdb->prepare() dla wszelkich danych od użytkownika. To najszybszy sposób na wprowadzenie SQL injection do witryny WordPress.

Filtruje łączną liczbę wpisów znalezionych przez zapytanie — z niej wyliczana jest paginacja.

Wywoływany

Po uruchomieniu zapytania, przed wyliczeniem paginacji.

Sygnatura

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

Ustawia rozmiar w pikselach, powyżej którego WordPress zmniejsza przesłany plik i serwuje kopię „-scaled” zamiast oryginału. Domyślnie 2560.

Wywoływany

Przy przesyłaniu, gdy WordPress decyduje, czy obraz jest „duży”.

Sygnatura

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

Przykład

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

Pułapka

To najczęstsza pojedyncza przyczyna „mój obraz jest rozmyty po przesłaniu do WordPressa”, a niemal nikt nie wie, że to istnieje. Twój oryginał wciąż jest na dysku — po prostu nigdy nie jest serwowany. Uwaga: dotyczy NAJDŁUŻSZEJ krawędzi i wpływa tylko na obrazy przesłane po aktywacji filtra.

Filtruje tablicę rozmiarów obrazów, które WordPress ma wygenerować dla przesłanego pliku. Usuń rozmiar (unset), aby przestać go generować.

Wywoływany

Przy przesyłaniu, przed utworzeniem plików pochodnych.

Sygnatura

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

Przykład

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

Pułapka

Usunięcie rozmiaru, którego twój motyw faktycznie UŻYWA, oznacza, że WordPress wraca do oryginału w pełnym rozmiarze — co jest gorsze niż zaoszczędzone miejsce na dysku. Poza tym powstrzymuje to tylko tworzenie NOWYCH plików; istniejące pozostają do czasu ponownego wygenerowania.

Ustawia jakość JPEG, z jaką WordPress ponownie koduje przesłane obrazy. Domyślnie 82.

Wywoływany

Za każdym razem, gdy WordPress zapisuje plik JPEG.

Sygnatura

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

Pułapka

Jakość 82 jest w porządku dla fotografii, a widocznie słaba dla zrzutów ekranu, logo i płaskiej grafiki — te mają ostre krawędzie i brak fotograficznego szumu, w którym można ukryć artefakty. Ponadto: wp_editor_set_quality to nowocześniejszy filtr, który obejmuje bezpośrednio klasy edytora obrazów; ustawianie obu jest częste.

Ustawia jakość wyjściową używaną przez klasy WP_Image_Editor (GD i Imagick).

Wywoływany

Gdy instancja edytora obrazów ustawia swoją jakość.

Sygnatura

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

Dodaje twoje własne rozmiary obrazów do listy rozwijanej rozmiarów w oknie mediów i edytorze bloków.

Wywoływany

Gdy interfejs mediów buduje selektor rozmiaru.

Sygnatura

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

Przykład

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

Pułapka

add_image_size() rejestruje rozmiar, ale NIE sprawia, że da się go wybrać w edytorze. Każde pytanie „mój własny rozmiar obrazu nie pojawia się na liście rozwijanej” wynika z braku tego filtra.

Sprawdza lub odrzuca plik PRZED przeniesieniem go do folderu przesłanych plików.

Wywoływany

Podczas przesyłania, przed zapisaniem pliku.

Sygnatura

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

Pułapka

Aby odrzucić plik, ustaw $file['error'] na ciąg z komunikatem i zwróć $file. Zwrócenie false lub rzucenie wyjątku nie zrobi tego, czego chcesz.

Filtruje tablicę metadanych (w tym wygenerowane rozmiary) po przetworzeniu załącznika.

Wywoływany

Po utworzeniu obrazów pochodnych przy przesyłaniu.

Sygnatura

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

Pułapka

To hak, którego używają wtyczki do optymalizacji obrazów. Potrafi być wolny — uruchamia się po zapisaniu każdego rozmiaru obrazu, a wykonanie tu żądania HTTP sprawia, że każde przesyłanie na nie czeka.

Filtruje kandydatów do srcset, których WordPress generuje dla obrazu responsywnego.

Wywoływany

Gdy renderowany jest obraz responsywny.

Sygnatura

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

Pułapka

Usunięcie gdzie indziej rozmiaru medium_large (768w) po cichu pogarsza srcset — ten rozmiar istnieje niemal wyłącznie po to, by go obsługiwać.

Nie zweryfikowaliśmy dokładnej liczby argumentów tego hooka ze źródłami WordPress. Sprawdź developer.wordpress.org, zanim zaczniesz na nim polegać. Wolimy zaznaczyć tę niepewność, niż po cichu podawać domysł jako fakt.

Rejestruje strony menu i podmenu w panelu.

Wywoływany

Gdy budowane jest menu panelu.

Sygnatura

add_action( 'admin_menu', 'my_callback' );

Przykład

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

Pułapka

Argument uprawnienia to UPRAWNIENIE (capability), a nie rola. Przekazanie „administrator” pozornie działa (bo w niektórych konfiguracjach administratorzy mają uprawnienie o tej nazwie), a potem po cichu daje dostęp niewłaściwym osobom. Używaj manage_options.

Wypisuje powiadomienie u góry ekranu panelu.

Wywoływany

Przy renderowaniu strony panelu.

Sygnatura

add_action( 'admin_notices', 'my_callback' );

Pułapka

Uruchamia się na KAŻDYM ekranie panelu. Wtyczka, która na wszystkich pokazuje bezwarunkowe powiadomienie „dziękujemy za instalację!”, to najbardziej znienawidzony pojedynczy wzorzec w panelu WordPressa. Zabezpiecz je i pozwól je zamknąć.

Uruchamia się za każdym razem, gdy wpis jest tworzony lub aktualizowany. Typowe miejsce na zapisywanie danych z meta boksów.

Wywoływany

Po zapisaniu wpisu do bazy danych.

Sygnatura

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

Przykład

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

Pułapka

Uruchamia się przy AUTOZAPISACH i WERSJACH, tak samo jak przy prawdziwych zapisach. Bez trzech powyższych zabezpieczeń twoje meta są nadpisywane pustymi wartościami za każdym razem, gdy edytor autozapisuje — błąd, który wygląda jak losowo znikające dane.

Rejestruje meta boksy na ekranie edycji wpisu.

Wywoływany

Gdy budowany jest ekran edycji.

Sygnatura

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

Pułapka

Klasyczne meta boksy nie pojawiają się w edytorze bloków, chyba że edytor przełączy się w tryb zgodności. Dla witryny natywnej dla edytora bloków zamiast tego zarejestruj meta wpisu z show_in_rest i zbuduj panel boczny.

Uruchamia się po pomyślnym zalogowaniu użytkownika.

Wywoływany

Po pomyślnym uwierzytelnieniu.

Sygnatura

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

Uruchamia się natychmiast po utworzeniu nowego użytkownika.

Wywoływany

Przy rejestracji.

Sygnatura

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

Filtruje wynik uwierzytelniania. Zwróć WP_Error, aby zablokować logowanie.

Wywoływany

Podczas próby logowania.

Sygnatura

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

Pułapka

Priorytet ma tu duże znaczenie. Rdzeń WordPressa podpina własne kontrole na priorytetach 20 i 30 — podepniesz się zbyt wcześnie, a uruchomisz się, zanim hasło w ogóle zostanie sprawdzone.

Rejestruje trasy i pola REST.

Wywoływany

Gdy inicjalizuje się REST API.

Sygnatura

add_action( 'rest_api_init', 'my_callback' );

Przykład

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

Pułapka

permission_callback jest WYMAGANY — od WP 5.5 jego pominięcie generuje ostrzeżenie, a ustawienie go na __return_true czyni punkt końcowy w pełni publicznym. To w porządku dla naprawdę publicznych danych i poważna dziura dla wszystkiego innego. Zdecyduj, nie zostawiaj domyślnie.

Dodaje własny interwał powtarzania dla wp_schedule_event().

Wywoływany

Gdy WordPress buduje listę dostępnych harmonogramów.

Sygnatura

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

Przykład

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

Pułapka

WP-Cron to nie prawdziwy cron. Uruchamia się tylko, gdy ktoś odwiedza witrynę, więc witryna o niskim ruchu nie uruchomi pięciominutowego harmonogramu co pięć minut. Jeśli czas naprawdę ma znaczenie, wyłącz WP-Cron (DISABLE_WP_CRON) i wywołuj wp-cron.php z prawdziwego systemowego crona.

Uruchamia się natychmiast po zapisaniu komentarza.

Wywoływany

Przy przesłaniu komentarza.

Sygnatura

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

Filtruje dane komentarza przed jego zapisaniem. Używany do kontroli spamu i walidacji.

Wywoływany

Przed zapisaniem komentarza.

Sygnatura

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

Pułapka

Aby odrzucić tu komentarz, wywołaj wp_die() z komunikatem — zwrócenie false go nie zatrzyma.

Uruchamia się na stronie potwierdzenia zamówienia po pomyślnej finalizacji zamówienia.

Wywoływany

Gdy klient trafia na stronę podziękowania.

Sygnatura

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

Pułapka

To NIE jest niezawodne miejsce do wyzwalania realizacji zamówienia. Uruchamia się tylko, jeśli klient faktycznie dotrze na stronę podziękowania — jeśli zamknie kartę po zapłacie, nigdy się nie wykona. Do wszystkiego, co musi się wydarzyć, użyj woocommerce_payment_complete lub haka przejścia statusu zamówienia.

Wypisuje znaczniki tuż przed przyciskiem dodania do koszyka na stronie produktu.

Wywoływany

Podczas renderowania strony produktu.

Sygnatura

add_action( 'woocommerce_before_add_to_cart_button', 'my_callback' );

Dodaje, usuwa lub zmienia kolejność pól w klasycznej finalizacji zamówienia.

Wywoływany

Gdy budowany jest formularz zamówienia.

Sygnatura

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

Pułapka

Wpływa tylko na KLASYCZNĄ finalizację zamówienia (na shortcode). Nowsza finalizacja oparta na blokach całkowicie go ignoruje i jest dostosowywana przez Slot & Fill w JavaScripcie. Za pierwszym razem podkłada nogę niemal każdemu.