WordPress Hooks - Actions i Filters dla developerów

Hooki to mechanizm, dzięki któremu modyfikujesz działanie WordPressa bez dotykania plików rdzenia (core). To pojedyncza najwazniejsza koncepcja, jaka odróżnia osobę klikajaca w panelu od osoby, ktora naprawdę panuje nad strona.

Wyobraź sobie WordPressa jako tasme produkcyjna. W trakcie generowania każdej strony silnik przechodzi przez setki z góry zdefiniowanych punktów: ładowanie wtyczek, budowanie zapytania do bazy, renderowanie nagłówka, wyświetlanie treści posta, dokładanie stopki. W każdym z tych punktów WordPress mówi: tu możesz się podpiąć i dołożyć swój kod.

Dlaczego to ma znaczenie? Bo edytowanie plików core albo motywu premium kończy się tak samo zawsze: przychodzi aktualizacja i Twoje zmiany znikają. Hooki sa odporne na aktualizacje, bo siedzą w osobnym pliku (functions.php motywu potomnego lub wtyczce) i podpinają się do WordPressa z zewnątrz.

W praktyce kazda wtyczka, ktora kiedykolwiek zainstalowałeś, działa właśnie na hookach. Yoast SEO dokleja meta tagi przez hook wp_head. WooCommerce przebudowuje stronę produktu dziesiątkami własnych hooków. To nie jest wiedza dla wybranych - to język, w którym mówi cala platforma. Cały ten system jest częścią tak zwanego Plugin API i to właśnie on sprawia, ze WordPress da się rozbudować niemal w nieskończoność.

Roznica jest jedna i jest absolutnie kluczowa: action wykonuje kod, filtr modyfikuje i zwraca dane. Action to czasownik (zrób coś), filtr to przeksztalcenie (weź dane, zmień, oddaj).

Action (do_action) odpala się w określonym momencie i niczego nie zwraca. Klasyczny przykład: wyślij e-mail po publikacji posta. WordPress nie oczekuje od Ciebie żadnej wartości - po prostu wykona Twój kod i poleci dalej.

add_action('publish_post', function($post_id) {
    wp_mail('admin@twojadomena.pl', 'Nowy post', 'Opublikowano post ID: ' . $post_id);
});

Filtr (apply_filters) dostaje jakas wartość, pozwala Ci ja zmienić i MUSI ja zwrócić. Jeśli zapomnisz return, WordPress dostanie pusta wartość i np. zniknie tytuł posta. To najczęstszy błąd początkujących.

add_filter('the_title', function($title) {
    return strtoupper($title); // zwracamy zmodyfikowana wartosc
});

Prosta heurystyka, której używamy w zespole: jeśli pytanie brzmi gdzie coś dodać (HTML, e-mail, log), to action. Jeśli pytanie brzmi jak zmienić istniejaca dana (tekst, tablice, liczbę), to filtr. Warto wiedzieć, ze technicznie filtr jest nadzbiorem akcji - może zrobić wszystko to co action, a dodatkowo zwrócić wartość. Mimo to nie nadużywaj tego, bo wybór właściwego typu komunikuje innym developerom Twoje intencje.

Poniżej skrócone porównanie, do którego warto wracać, gdy nie masz pewności, którego mechanizmu użyć.

Składnia obu funkcji jest niemal identyczna i składa się z czterech parametrów. Zrozumienie każdego z nich oszczedza godziny debugowania.

add_action('nazwa_hooka', 'nazwa_funkcji', $priorytet, $liczba_argumentow);
add_filter('nazwa_hooka', 'nazwa_funkcji', $priorytet, $liczba_argumentow);

Pierwszy parametr to nazwa hooka, do którego się podpinasz. Drugi to Twoja funkcja zwrotna (callback) - może być nazwana funkcja, funkcja anonimowa albo metoda klasy. Trzeci to priorytet (domyślnie 10). Czwarty to liczba argumentów, jaka Twoja funkcja chce odebrać (domyślnie 1).

Callback to po prostu funkcja, ktora WordPress wywoła w odpowiednim momencie. W prostych przypadkach wygodne sa funkcje anonimowe, ale w większym kodzie warto używać nazwanych funkcji lub metod klasy - łatwiej je potem usunąć przez remove_action czy remove_filter.

Najczestsza pulapka dotyczy czwartego parametru. WordPress domyślnie przekaże do Twojej funkcji tylko jeden argument, nawet jeśli hook oferuje więcej. Jeśli chcesz odebrać np. trzy, musisz to jawnie zadeklarować.

// save_post oferuje 3 argumenty - musimy o nie poprosic
add_action('save_post', 'moj_zapis', 10, 3);
function moj_zapis($post_id, $post, $update) {
    if ($update) {
        // logika tylko dla aktualizacji istniejacego wpisu
    }
}

Ważna zasada kolejności: add_action() i add_filter() muszą zostać wywołane ZANIM dany hook się odpali. Jeśli zarejestrujesz callback po tym, jak WordPress już przeszedł przez ten punkt, Twój kod nie zadziała. Dlatego rejestracje najczęściej umieszcza się w functions.php lub w pliku głównym wtyczki, które ładowane sa bardzo wcześnie.

Priorytet decyduje o kolejności, w jakiej wykonują się callbacki podpięte do tego samego hooka. Im nizsza liczba, tym wcześniej. Domyślnie wszystko ma priorytet 10.

To nie jest abstrakcja - to narzędzie, którego używamy regularnie. Gdy chcesz, żeby Twój filtr zadziałał PO tym, co robi wtyczka (np. nadpisać jej zmianę), ustawiasz wyższy priorytet, np. 20 lub 99. Gdy chcesz wyprzedzić inny kod, ustawiasz niższy, np. 5.

// Ten callback wykona sie pozno - po wiekszosci innych
add_filter('the_content', 'moja_modyfikacja', 99);

Kolejność przy identycznym priorytecie odpowiada kolejności dodania. Jeśli dwie wtyczki użyją priorytetu 10, zadziała najpierw ta zarejestrowana wcześniej.

Liczba argumentów to częste źródło cichych błędów. Hook może udostępniać kilka danych kontekstowych, ale WordPress poda Ci tylko tyle, ile poprosisz. To pulapka: kod nie wyrzuca błędu, po prostu zmienne sa null i logika się sypie bez ostrzeżenia. Gdy debugujesz dziwne zachowanie callbacku, najpierw sprawdź właśnie ten parametr.

Choć WordPress oferuje tysiące hooków, w realnych wdrożeniach 90% pracy opiera się na kilkunastu. Warto znać je na pamięć - resztę znajdziesz w dokumentacji, gdy będą potrzebne.

Do poprawnego ładowania skryptów i styli zawsze używaj wp_enqueue_scripts (frontend) lub admin_enqueue_scripts (panel). To jedyny poprawny sposób - wklejanie tagów script bezpośrednio w nagłówek łamie cache, kolejność zależności i dobre praktyki.

Do wstawiania kodu w nagłówek i stopkę służą wp_head oraz wp_footer. Tu trafiają piksele, weryfikację właściciela domeny czy skrypty analityczne (choć te ostatnie lepiej ładować warunkowo).

Przy operacjach na wpisach najczęściej sięgamy po save_post (zapis), init (wczesna inicjalizacja, rejestracja typów postów) oraz pre_get_posts (modyfikacja zapytań, np. zmiana sortowania archiwum). Ten ostatni to jeden z najpotezniejszych filtrów w całym WordPressie - pozwala zmienić to, jakie wpisy i w jakiej kolejności pokaze się na stronie głównej, w archiwum czy w wynikach wyszukiwania.

Tworzenie własnych hooków to moment, w którym z osoby uzywajacej WordPressa stajesz się osoba, ktora go rozbudowuje. Własne hooki sprawiają, ze Twój motyw lub wtyczka staje się rozszerzalna dla innych.

Wlasna akcje tworzysz przez do_action() w miejscu, gdzie chcesz dać innym możliwość podpięcia kodu:

// w szablonie motywu, np. pod naglowkiem produktu
do_action('kc_po_naglowku_produktu', $produkt_id);

Własny filtr tworzysz przez apply_filters() wokół wartości, ktora ma być modyfikowalna:

$prowizja = apply_filters('kc_stawka_prowizji', 0.10, $zamowienie);

Przy nazewnictwie obowiązuje jedna zelazna zasada: prefiksuj nazwy własnych hooków unikalnym ciągiem (np. kc_), żeby uniknąć kolizji z innymi wtyczkami i motywami. Dwa hooki o tej samej nazwie to przepis na trudny do namierzenia konflikt.

Usuwanie istniejących hooków jest równie ważne, zwłaszcza gdy chcesz wyłączyć zachowanie wtyczki lub motywu. Służą do tego remove_action() i remove_filter(). Pułapka: musisz podać dokładnie ta sama nazwę funkcji i ten sam priorytet, z jakim hook został dodany, inaczej usunięcie nie zadziała.

remove_action('wp_head', 'wp_generator'); // ukrywa wersje WP w naglowku

Gdy callback jest metoda klasy, usunięcie bywa trudne - potrzebujesz referencji do tej samej instancji obiektu. To jeden z najczęstszych powodów, dla których usuwanie hooków wtyczek nie działa za pierwszym razem.

To pytanie decyduje o tym, czy Twoja praca przetrwa nastepna aktualizacje. Mamy trzy sensowne miejsca i jasna hierarchię, ktora stosujemy w projektach.

Motyw potomny (child theme) to dobre miejsce na modyfikacje związane z wyglądem i układem - to, co jest scisle powiązane z danym motywem. Plik functions.php motywu potomnego jest odporny na aktualizacje motywu nadrzędnego.

Wtyczka funkcjonalna (lub mu-plugin) to lepsze miejsce na logikę biznesowa, ktora powinna działać niezależnie od motywu. Jeśli jutro zmienisz szablon, Twoje przekierowania, integracje czy typy postów nie powinny zniknąć razem z nim. Mu-plugin (must-use plugin) ma dodatkowa zaletę: nie da się go przypadkiem dezaktywować w panelu, co czyni go idealnym na krytyczna logikę.

Wtyczka typu Code Snippets to rozsądny kompromis dla osób nietechnicznych - pozwala dodawać fragmenty kodu z panelu bez dotykania plików przez FTP, z opcja bezpiecznego wyłączenia błędnego snippeta, gdy coś pójdzie nie tak.

Po latach wdrożeń widzimy, ze większe problemy biorą się nie z trudnych hooków, lecz z kilku powtarzalnych pomyłek.

Najczęstszy: brak return w filtrze. Filtr bez zwroconej wartości kasuje dane, które miał tylko zmodyfikować. Drugi: rejestracja hooka po tym, jak już się odpalił - callback nie zadziała, a błędu brak. Trzeci: niedopasowana liczba argumentów, przez co zmienne sa null. Czwarty: konflikty nazw własnych hooków - zawsze prefiksuj je unikalnym ciągiem (np. kc_), żeby uniknąć kolizji.

Osobny temat to wydajność. Hook taki jak the_content uruchamia się przy każdym wyświetleniu treści, a save_post potrafi odpalić się wielokrotnie podczas jednego zapisu (autozapis, rewizje). Ciezka operacja w złym hooku to prosta droga do wolnej strony. Jeśli musisz w save_post wykonać kosztowna logikę, warto najpierw odfiltrować autozapisy i rewizje, by nie powtarzać jej kilka razy na jeden zapis.

Znajomość hooków to roznica między strona poskladana z wtyczek a strona zaprojektowana świadomie. Pierwsza działa, dopóki nic się nie zmieni. Druga jest przewidywalna, szybka i latwa w utrzymaniu, bo cala logika siedzi w jednym, kontrolowanym miejscu.

Dla właściciela firmy oznacza to konkret: mniej awarii po aktualizacjach, szybsze wdrażanie zmian i brak uzależnienia od konkretnego motywu czy wtyczki. To właśnie ta warstwa odróżnia profesjonalne wykonanie od pracy na skróty.

Jeśli planujesz nowy projekt albo chcesz uporządkować istniejący, zaczynamy od architektury - gdzie ma siedzieć logika, jakie hooki wykorzystać, jak rozdzielić wygląd od funkcji. Sprawdź naszą ofertę strony internetowe, jeśli chcesz mie stronę zbudowana solidnie od fundamentów, albo umów bezplatna konsultację - przeanalizujemy Twoja sytuację i podpowiemy najlepsze rozwiązanie.