WordPress Hooks - Actions i Filters dla developerów

Hooki to punkty rozszerzenia w kodzie WordPressa, motywów i wtyczek. Podczas obsługi żądania aplikacja ładuje komponenty, przygotowuje zapytania i generuje odpowiedź. W wybranych miejscach wywołuje zarejestrowane funkcje. Dzięki temu możesz dołożyć zachowanie albo zmienić dane bez kopiowania całego mechanizmu, który je wytwarza.

Rejestracja callbacka nie oznacza jego natychmiastowego wykonania. Kod zadziała dopiero wtedy, gdy aplikacja dojdzie do właściwego hooka. Nie każdy hook uruchamia się w każdym żądaniu. Panel administracyjny, frontend, REST API i zadanie w tle mogą przechodzić przez inne ścieżki.

Oddzielenie zmian od rdzenia ogranicza ryzyko ich nadpisania podczas aktualizacji. Nie gwarantuje jednak zgodności ze wszystkimi przyszłymi wersjami. Zmieniona sygnatura, usunięty hook lub inna kolejność pracy wtyczki nadal wymagają przeglądu. Dlatego kod korzystający z Plugin API również obejmij procedurą aktualizacji WordPressa.

Action służy wykonaniu działania w określonym momencie. WordPress nie wykorzystuje wartości zwrotnej callbacka akcji. Funkcja może mieć instrukcję return, na przykład aby wcześniej zakończyć działanie, lecz nie przekazuje w ten sposób zmodyfikowanej wartości do kolejnego callbacka.

Poniższy przykład edukacyjny dodaje pusty znacznik pomocniczy w stopce. Nie zapisuje danych ani nie wysyła wiadomości; motyw musi wywoływać wp_footer, aby akcja się wykonała:

add_action( 'wp_footer', function () {
    echo '<span class="kc-footer-marker" hidden></span>';
} );

Filter otrzymuje wartość, może ją zmienić i powinien zwrócić wynik o typie oczekiwanym przez dany hook. Kolejny callback otrzyma ten wynik. Gdy funkcja nie zwróci niczego, przekazuje null, co może usunąć zawartość albo wywołać błąd w dalszym kodzie.

add_filter( 'body_class', function ( $classes ) {
    $classes[] = 'kc-site';
    return $classes;
} );

Ten filtr zachowuje tablicę istniejących klas i dodaje własną. Jest czytelniejszym przykładem kontraktu niż globalne przekształcanie wszystkich tytułów. Nie trzeba przy nim zmieniać wielkości liter ani rozstrzygać obsługi polskich znaków w funkcjach tekstowych.

Przy wyborze mechanizmu sprawdź miejsce jego wywołania w dokumentacji lub kodzie. Nazwa hooka nie zawsze wystarcza do odgadnięcia typu. To aplikacja definiuje, czy oczekuje zwróconej wartości, czy wykonania działania.

Action również może otrzymać dane, a filtr może otrzymać dodatkowy kontekst poza pierwszą wartością. Nie myl więc rozróżnienia action/filter z liczbą argumentów. To dwa niezależne elementy kontraktu hooka.

Obie funkcje rejestrujące przyjmują nazwę hooka, callback, priorytet i liczbę odbieranych argumentów. Domyślny priorytet wynosi 10, a accepted_args ma wartość 1. Callback może być nazwaną funkcją, funkcją anonimową albo metodą klasy. W większym rozszerzeniu nazwana funkcja lub zachowana referencja ułatwia późniejsze usunięcie rejestracji.

Przykład pokazuje trzy argumenty udostępniane przez save_post. Funkcja celowo nie zapisuje danych; jest szkieletem do poznania kontraktu, a nie gotową obsługą formularza:

add_action( 'save_post', 'kc_observe_post', 10, 3 );
function kc_observe_post( $post_id, $post, $update ) {
    // Argumenty sa dostepne do dalszej analizy.
}

Rejestrację wykonaj przed uruchomieniem akcji, którą chcesz obsłużyć. Jeśli dany etap już minął, add_action nie odtworzy wcześniejszego zdarzenia. Sprawdź również, czy callback został rzeczywiście załadowany w danej ścieżce, zamiast od razu zmieniać priorytet.

Dodanie zapisu do tego szkieletu wymaga osobnej kontroli rewizji, autozapisów, uprawnień i powtórzeń operacji. Zasady ról oraz capabilities pozostają istotne także wtedy, gdy kod działa wewnątrz hooka.

Priorytet określa kolejność callbacków tego samego hooka. Niższa liczba oznacza wcześniejsze wykonanie. Przy identycznym priorytecie znaczenie ma kolejność rejestracji. Jeśli znasz priorytet innego callbacka, możesz dobrać własny względem niego, ale nie względem wszystkich operacji wykonywanych przez WordPressa.

accepted_args ogranicza liczbę argumentów przekazywanych callbackowi. Nie tworzy dodatkowych danych, których hook nie oferuje. Gdy funkcja wymaga więcej argumentów, niż otrzyma, wywołanie może zakończyć się ArgumentCountError w PHP. Nie zakładaj, że brakujące wartości zostaną po prostu zastąpione null.

Podczas debugowania porównaj więc trzy elementy: argumenty udostępniane przez hook, accepted_args przy rejestracji i parametry funkcji. Dopiero później szukaj problemu w warunkach biznesowych wewnątrz callbacka.

Do rejestrowania i dołączania zasobów frontendu służy wp_enqueue_scripts, a dla panelu admin_enqueue_scripts. Korzystanie z mechanizmu enqueue pomaga zarządzać zależnościami i kolejnością plików. Własny znacznik w nagłówku czy stopce jest innym zastosowaniem niż bezpośrednie wklejanie całego systemu skryptów.

pre_get_posts jest akcją, mimo że pozwala zmienić zapytanie. Callback otrzymuje obiekt WP_Query i modyfikuje jego ustawienia. Przy zmianie głównego archiwum trzeba ograniczyć działanie do właściwego zapytania i kontekstu, aby nie zmienić przy okazji listy w panelu lub zapytania pomocniczego.

Nie wybieraj hooka wyłącznie dlatego, że jego nazwa brzmi podobnie do zadania. Sprawdź argumenty, moment i częstotliwość wywołania. Dokumentacja konkretnego rozszerzenia ma tu większe znaczenie niż ogólna lista popularnych nazw.

Własną akcję udostępniasz przez do_action, a wartość podatną na zmianę przez apply_filters. Używaj unikalnego prefiksu, aby ograniczyć kolizje. Opisz znaczenie i typ parametrów oraz etap, na którym następuje wywołanie. Te informacje tworzą kontrakt dla innych programistów.

// Przyklad z ustalona wartoscia, bez zapisu danych.
$label = apply_filters( 'kc_demo_label', 'Oferta' );

Do usunięcia callbacka służą remove_action i remove_filter. Potrzebujesz tej samej identyfikacji callbacka oraz priorytetu, z jakimi został dodany. Operację wykonaj po rejestracji, ale przed wywołaniem, które chcesz pominąć.

function kc_demo_classes( $classes ) {
    $classes[] = 'kc-demo';
    return $classes;
}
add_filter( 'body_class', 'kc_demo_classes', 20 );
remove_filter( 'body_class', 'kc_demo_classes', 20 );

W tym przykładzie rejestracja zostaje od razu usunięta, więc klasa nie zostanie dodana. Dla metody obiektu potrzebna jest ta sama instancja, a dla funkcji anonimowej zachowana referencja. Nowa funkcja anonimowa o identycznej treści nie jest tym samym callbackiem.

Motyw potomny jest odpowiednim miejscem na zmiany związane z jego wyglądem. Logika biznesowa powinna pozostać dostępna po zmianie motywu, więc lepiej umieścić ją we wtyczce funkcjonalnej. Mu-plugin ładuje się automatycznie i nie jest zwykle wyłączany na liście standardowych wtyczek; wymaga przez to jasno opisanej procedury awaryjnej.

Edytor snippetów ułatwia zarządzanie drobnymi fragmentami, ale nie zwalnia z przeglądu PHP, kontroli dostępu i testu wyłączenia. Zapisz właściciela kodu oraz miejsce jego przechowywania. Unikaj tego samego callbacka w kilku snippetach, bo diagnoza wielokrotnego uruchomienia będzie trudniejsza.

Pomocnicze czynności administracyjne opisuje poradnik WP-CLI. Sam dostęp do terminala nie oznacza jednak, że można bez przeglądu uruchamiać każdy znaleziony fragment na produkcji.

Brak return w filtrze, zły typ wyniku, spóźniona rejestracja i niedopasowane argumenty to osobne przyczyny usterek. Sprawdzaj je pojedynczo. W logu diagnostycznym zapisuj tylko potrzebny kontekst; nie kopiuj całej treści zamówienia, hasła ani danych osobowych.

Nie zakładaj również, że publish_post znaczy pierwszą publikację. Dokumentacja hooka statusu wskazuje, że może wywołać się ponownie podczas aktualizacji opublikowanego wpisu. Automatyzacja oparta na tym zdarzeniu musi rozpoznawać właściwe przejście i chronić się przed powtórzeniem efektu.

Dla mutującego save_post sprawdź autozapis, rewizję, rodzaj obiektu, uprawnienie i pochodzenie danych. Jeśli callback ponownie zapisuje wpis, może wywołać kolejną rundę hooków. Zaprojektuj idempotencję, czyli taki sposób przetwarzania, aby powtórzenie tego samego zdarzenia nie wykonywało ponownie skutku biznesowego. Ciężką pracę i połączenia zewnętrzne dobieraj do oczekiwanego czasu odpowiedzi oraz mechanizmu ponowień.

Przy odbiorze zmiany sprawdź nie tylko oczekiwany efekt. Zapisz też miejsca, w których callback nie powinien działać, i scenariusze ponownego wywołania. Test powinien objąć używany motyw, wersję WordPressa i rozszerzenia wpływające na ten sam obszar.

Jeśli potrzebujesz uporządkować istniejące snippety lub rozbudować WordPressa, opisz oczekiwane zachowanie. Dobierzemy miejsce kodu, zakres testów i sposób wyłączenia. Przy nowej stronie internetowej te ustalenia warto uwzględnić od początku. Dalsze drobne zmiany możemy objąć pakietem godzinowym, z zakresem opieki i SLA uzgodnionymi indywidualnie.

• Tailwind CSS toggle: jak wdrożyć dostępny przełącznik