WordPress Hooks - Actions i Filters dla developerów

Hooki to mechanizm, dzieki ktoremu modyfikujesz dzialanie WordPressa bez dotykania plikow rdzenia (core). To pojedyncza najwazniejsza koncepcja, jaka odroznia osobe klikajaca w panelu od osoby, ktora naprawde panuje nad strona.

Wyobraz sobie WordPressa jako tasme produkcyjna. W trakcie generowania kazdej strony silnik przechodzi przez setki z gory zdefiniowanych punktow: ladowanie wtyczek, budowanie zapytania do bazy, renderowanie naglowka, wyswietlanie tresci posta, dokladanie stopki. W kazdym z tych punktow WordPress mowi: tu mozesz sie podpiac i dolozyc swoj kod.

Dlaczego to ma znaczenie? Bo edytowanie plikow core albo motywu premium konczy sie tak samo zawsze: przychodzi aktualizacja i Twoje zmiany znikaja. Hooki sa odporne na aktualizacje, bo siedza w osobnym pliku (functions.php motywu potomnego lub wtyczce) i podpinaja sie do WordPressa z zewnatrz.

W praktyce kazda wtyczka, ktora kiedykolwiek zainstalowales, dziala wlasnie na hookach. Yoast SEO dokleja meta tagi przez hook wp_head. WooCommerce przebudowuje strone produktu dziesiatkami wlasnych hookow. To nie jest wiedza dla wybranych - to jezyk, w ktorym mowi cala platforma. Caly ten system jest czescia tak zwanego Plugin API i to wlasnie on sprawia, ze WordPress da sie rozbudowac niemal w nieskonczonosc.

Roznica jest jedna i jest absolutnie kluczowa: action wykonuje kod, filtr modyfikuje i zwraca dane. Action to czasownik (zrob cos), filtr to przeksztalcenie (wez dane, zmien, oddaj).

Action (do_action) odpala sie w okreslonym momencie i niczego nie zwraca. Klasyczny przyklad: wyslij e-mail po publikacji posta. WordPress nie oczekuje od Ciebie zadnej wartosci - po prostu wykona Twoj 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 wartosc, pozwala Ci ja zmienic i MUSI ja zwrocic. Jesli zapomnisz return, WordPress dostanie pusta wartosc i np. zniknie tytul posta. To najczestszy blad poczatkujacych.

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

Prosta heurystyka, ktorej uzywamy w zespole: jesli pytanie brzmi gdzie cos dodac (HTML, e-mail, log), to action. Jesli pytanie brzmi jak zmienic istniejaca dana (tekst, tablice, liczbe), to filtr. Warto wiedziec, ze technicznie filtr jest nadzbiorem akcji - moze zrobic wszystko to co action, a dodatkowo zwrocic wartosc. Mimo to nie naduzywaj tego, bo wybor wlasciwego typu komunikuje innym developerom Twoje intencje.

Ponizej skrocone porownanie, do ktorego warto wracac, gdy nie masz pewnosci, ktorego mechanizmu uzyc.

Skladnia obu funkcji jest niemal identyczna i sklada sie z czterech parametrow. Zrozumienie kazdego 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 ktorego sie podpinasz. Drugi to Twoja funkcja zwrotna (callback) - moze byc nazwana funkcja, funkcja anonimowa albo metoda klasy. Trzeci to priorytet (domyslnie 10). Czwarty to liczba argumentow, jaka Twoja funkcja chce odebrac (domyslnie 1).

Callback to po prostu funkcja, ktora WordPress wywola w odpowiednim momencie. W prostych przypadkach wygodne sa funkcje anonimowe, ale w wiekszym kodzie warto uzywac nazwanych funkcji lub metod klasy - latwiej je potem usunac przez remove_action czy remove_filter.

Najczestsza pulapka dotyczy czwartego parametru. WordPress domyslnie przekaze do Twojej funkcji tylko jeden argument, nawet jesli hook oferuje wiecej. Jesli chcesz odebrac np. trzy, musisz to jawnie zadeklarowac.

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

Wazna zasada kolejnosci: add_action() i add_filter() musza zostac wywolane ZANIM dany hook sie odpali. Jesli zarejestrujesz callback po tym, jak WordPress juz przeszedl przez ten punkt, Twoj kod nie zadziala. Dlatego rejestracje najczesciej umieszcza sie w functions.php lub w pliku glownym wtyczki, ktore ladowane sa bardzo wczesnie.

Priorytet decyduje o kolejnosci, w jakiej wykonuja sie callbacki podpiete do tego samego hooka. Im nizsza liczba, tym wczesniej. Domyslnie wszystko ma priorytet 10.

To nie jest abstrakcja - to narzedzie, ktorego uzywamy regularnie. Gdy chcesz, zeby Twoj filtr zadzialal PO tym, co robi wtyczka (np. nadpisac jej zmiane), ustawiasz wyzszy priorytet, np. 20 lub 99. Gdy chcesz wyprzedzic inny kod, ustawiasz nizszy, np. 5.

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

Kolejnosc przy identycznym priorytecie odpowiada kolejnosci dodania. Jesli dwie wtyczki uzyja priorytetu 10, zadziala najpierw ta zarejestrowana wczesniej.

Liczba argumentow to czeste zrodlo cichych bledow. Hook moze udostepniac kilka danych kontekstowych, ale WordPress poda Ci tylko tyle, ile poprosisz. To pulapka: kod nie wyrzuca bledu, po prostu zmienne sa null i logika sie sypie bez ostrzezenia. Gdy debugujesz dziwne zachowanie callbacku, najpierw sprawdz wlasnie ten parametr.

Choc WordPress oferuje tysiace hookow, w realnych wdrozeniach 90% pracy opiera sie na kilkunastu. Warto znac je na pamiec - reszte znajdziesz w dokumentacji, gdy beda potrzebne.

Do poprawnego ladowania skryptow i styli zawsze uzywaj wp_enqueue_scripts (frontend) lub admin_enqueue_scripts (panel). To jedyny poprawny sposob - wklejanie tagow script bezposrednio w naglowek lamie cache, kolejnosc zaleznosci i dobre praktyki.

Do wstawiania kodu w naglowek i stopke sluza wp_head oraz wp_footer. Tu trafiaja piksele, weryfikacje wlasciciela domeny czy skrypty analityczne (choc te ostatnie lepiej ladowac warunkowo).

Przy operacjach na wpisach najczesciej siegamy po save_post (zapis), init (wczesna inicjalizacja, rejestracja typow postow) oraz pre_get_posts (modyfikacja zapytan, np. zmiana sortowania archiwum). Ten ostatni to jeden z najpotezniejszych filtrow w calym WordPressie - pozwala zmienic to, jakie wpisy i w jakiej kolejnosci pokaze sie na stronie glownej, w archiwum czy w wynikach wyszukiwania.

Tworzenie wlasnych hookow to moment, w ktorym z osoby uzywajacej WordPressa stajesz sie osoba, ktora go rozbudowuje. Wlasne hooki sprawiaja, ze Twoj motyw lub wtyczka staje sie rozszerzalna dla innych.

Wlasna akcje tworzysz przez do_action() w miejscu, gdzie chcesz dac innym mozliwosc podpiecia kodu:

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

Wlasny filtr tworzysz przez apply_filters() wokol wartosci, ktora ma byc modyfikowalna:

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

Przy nazewnictwie obowiazuje jedna zelazna zasada: prefiksuj nazwy wlasnych hookow unikalnym ciagiem (np. kc_), zeby uniknac kolizji z innymi wtyczkami i motywami. Dwa hooki o tej samej nazwie to przepis na trudny do namierzenia konflikt.

Usuwanie istniejacych hookow jest rownie wazne, zwlaszcza gdy chcesz wylaczyc zachowanie wtyczki lub motywu. Sluza do tego remove_action() i remove_filter(). Pulapka: musisz podac dokladnie ta sama nazwe funkcji i ten sam priorytet, z jakim hook zostal dodany, inaczej usuniecie nie zadziala.

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

Gdy callback jest metoda klasy, usuniecie bywa trudne - potrzebujesz referencji do tej samej instancji obiektu. To jeden z najczestszych powodow, dla ktorych usuwanie hookow wtyczek nie dziala za pierwszym razem.

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

Motyw potomny (child theme) to dobre miejsce na modyfikacje zwiazane z wygladem i ukladem - to, co jest scisle powiazane z danym motywem. Plik functions.php motywu potomnego jest odporny na aktualizacje motywu nadrzednego.

Wtyczka funkcjonalna (lub mu-plugin) to lepsze miejsce na logike biznesowa, ktora powinna dzialac niezaleznie od motywu. Jesli jutro zmienisz szablon, Twoje przekierowania, integracje czy typy postow nie powinny zniknac razem z nim. Mu-plugin (must-use plugin) ma dodatkowa zalete: nie da sie go przypadkiem dezaktywowac w panelu, co czyni go idealnym na krytyczna logike.

Wtyczka typu Code Snippets to rozsadny kompromis dla osob nietechnicznych - pozwala dodawac fragmenty kodu z panelu bez dotykania plikow przez FTP, z opcja bezpiecznego wylaczenia blednego snippeta, gdy cos pojdzie nie tak.

Po latach wdrozen widzimy, ze wieksze problemy biora sie nie z trudnych hookow, lecz z kilku powtarzalnych pomylek.

Najczestszy: brak return w filtrze. Filtr bez zwroconej wartosci kasuje dane, ktore mial tylko zmodyfikowac. Drugi: rejestracja hooka po tym, jak juz sie odpalil - callback nie zadziala, a bledu brak. Trzeci: niedopasowana liczba argumentow, przez co zmienne sa null. Czwarty: konflikty nazw wlasnych hookow - zawsze prefiksuj je unikalnym ciagiem (np. kc_), zeby uniknac kolizji.

Osobny temat to wydajnosc. Hook taki jak the_content uruchamia sie przy kazdym wyswietleniu tresci, a save_post potrafi odpalic sie wielokrotnie podczas jednego zapisu (autozapis, rewizje). Ciezka operacja w zlym hooku to prosta droga do wolnej strony. Jesli musisz w save_post wykonac kosztowna logike, warto najpierw odfiltrowac autozapisy i rewizje, by nie powtarzac jej kilka razy na jeden zapis.

Znajomosc hookow to roznica miedzy strona poskladana z wtyczek a strona zaprojektowana swiadomie. Pierwsza dziala, dopoki nic sie nie zmieni. Druga jest przewidywalna, szybka i latwa w utrzymaniu, bo cala logika siedzi w jednym, kontrolowanym miejscu.

Dla wlasciciela firmy oznacza to konkret: mniej awarii po aktualizacjach, szybsze wdrazanie zmian i brak uzaleznienia od konkretnego motywu czy wtyczki. To wlasnie ta warstwa odroznia profesjonalne wykonanie od pracy na skroty.

Jesli planujesz nowy projekt albo chcesz uporzadkowac istniejacy, zaczynamy od architektury - gdzie ma siedziec logika, jakie hooki wykorzystac, jak rozdzielic wyglad od funkcji. Sprawdz nasza oferte strony internetowe, jesli chcesz mie strone zbudowana solidnie od fundamentow, albo umow bezplatna konsultacje - przeanalizujemy Twoja sytuacje i podpowiemy najlepsze rozwiazanie.