Akcje vs filtry

W WordPressie wyróżniamy dwa rodzaje hooków: akcje i filtry. Technicznie są bardzo podobne, ale mają inne przeznaczenie.

Akcje (actions)

Akcja to moment w trakcie wykonywania WordPressa, w którym możesz wykonać własny kod — coś wypisać, zapisać, wysłać e-mail. Callback akcji nie musi niczego zwracać.

do_action( 'init' );

do_action( 'save_post', $post_id, $post, $update );

Użycie:

add_action( 'save_post', 'wyslij_powiadomienie', 10, 3 );

function wyslij_powiadomienie( $post_id, $post, $update ) {
    // wykonaj coś po zapisaniu wpisu
}

Kiedy używać akcji: rejestracja typów treści, ładowanie skryptów, wysyłka powiadomień, rejestracja tras REST, zapisywanie metadanych.

Filtry (filters)

Filtr przekształca wartość — otrzymuje dane, modyfikuje je i zwraca. Wartość płynie dalej przez łańcuch filtrów do momentu użycia.

$content = apply_filters( 'the_content', $content );

Użycie:

add_filter( 'the_content', 'dodaj_notke' );

function dodaj_notke( $content ) {
    return $content . '<p>Źródło: nasza witryna</p>';
}

Kiedy używać filtrów: zmiana treści, tytułów, atrybutów, argumentów zapytań, adresów URL, nagłówków HTTP — wszystkiego, co jest zwracane.

Różnice w praktyce

	Akcja (do_action)	Filtr (apply_filters)
Cel	wykonanie kodu w danym momencie	zmiana wartości
Callback zwraca	nie musi nic zwracać	musi zwrócić wartość
Rejestracja	add_action()	add_filter()
Warianty	do_action_ref_array()	apply_filters_ref_array()

Czy to naprawdę różni się technicznie?

Nie. add_action() to alias add_filter() — oba trafiają do tej samej kolejki. Różnica to konwencja i czytelność: filtr z niezwróconą wartością „gubi” dane, a akcja, która coś zwraca, i tak to marnuje.

Pozycja wywołania ma znaczenie

Kolejność do_action / apply_filters w kodzie rdzenia decyduje o tym, co callback może zrobić:

// zapis metadanych po zapisaniu wpisu — dobry moment, bo wpis już istnieje
do_action( 'save_post', $post_id, $post, $update );

// filtr przed renderowaniem — możesz jeszcze zmienić wynik
$html = apply_filters( 'render_block', $html, $block );

Jeśli nie wiesz, gdzie hook jest wywoływany, zajrzyj na jego stronę w tej dokumentacji — sekcja Plik źródłowy wskazuje dokładną lokalizację w kodzie WordPressa.