Architektura Hooków WordPress: Akcje kontra Filtry Wyjaśnione

Każda wtyczka WordPress robi jedną z dwóch rzeczy: wykonuje kod w określonym momencie (akcja) lub modyfikuje wartość przed jej użyciem (filtr). To wszystko. Cały ekosystem wtyczek WordPress jest zbudowany na tym rozróżnieniu.

Zrozumienie różnicy — i kiedy której użyć — oddziela wtyczki działające od tych, które powodują problemy.

Akcje: zrób coś w danym momencie

Hook akcji to sygnał, który WordPress (lub inna wtyczka) wysyła w określonym momencie. Do tego sygnału dołączasz funkcję, a Twoja funkcja jest uruchamiana, gdy sygnał zostanie wyemitowany.

add_action( 'wp_enqueue_scripts', 'my_plugin_load_assets' );

function my_plugin_load_assets() {
    wp_enqueue_style( 'my-plugin', plugin_dir_url( __FILE__ ) . 'style.css' );
    wp_enqueue_script( 'my-plugin', plugin_dir_url( __FILE__ ) . 'script.js', ['jquery'], '1.0', true );
}

wp_enqueue_scripts jest wywoływany, gdy WordPress przygotowuje się do ładowania zasobów dla frontendu. Podłączenie się do niego to właściwy sposób ładowania CSS i JS — a nie wstawianie tagów <script> bezpośrednio do szablonów.

Często używane hooki akcji:

• init — uruchamiany wcześnie, dobry do rejestrowania typów postów i taksonomii
• wp_enqueue_scripts — ładuje zasoby frontendu
• admin_enqueue_scripts — ładuje zasoby panelu administracyjnego
• save_post — uruchamiany podczas zapisywania posta, dobry do przetwarzania pól niestandardowych
• wp_ajax_{action} — obsługuje żądania AJAX od uwierzytelnionych użytkowników
• wp_ajax_nopriv_{action} — obsługuje żądania AJAX od niezalogowanych użytkowników

Filtry: modyfikuj wartość przed jej użyciem

Hook filtru daje Ci wartość, pozwala ją zmodyfikować i oczekuje, że zwrócisz zmodyfikowaną wersję. WordPress następnie używa Twojej zmodyfikowanej wartości zamiast oryginalnej.

add_filter( 'the_content', 'my_plugin_append_cta' );

function my_plugin_append_cta( $content ) {
    if ( ! is_single() ) {
        return $content;
    }
    $cta = '<div class="post-cta">Gotowy wypróbować PAGEnza? <a href="#">Rozpocznij za darmo →</a></div>';
    return $content . $cta;
}

Kluczowa zasada: zawsze coś zwracaj z filtra. Jeśli zapomnisz o return, wartość stanie się null i zepsujesz wszystko, co z niej korzystało.

Często używane hooki filtrów:

• the_content — zawartość posta przed wyświetleniem

• the_title — tytuł posta

• wp_nav_menu_items — kod HTML menu nawigacyjnego

• upload_mimes — dozwolone typy przesyłanych plików

• plugin_action_links_{plugin-file} — linki wyświetlane na stronie listy wtyczek

Jak PAGEnza AI wykorzystuje hooki

Kiedy Plugin Builder generuje wtyczkę, strukturyzuje kod wokół klasy z metodami podłączonymi do hooków w konstruktorze. Ten wzorzec unika kolizji nazw funkcji globalnych i utrzymuje kod w porządku.

class My_Plugin {
    public function __construct() {
        add_action( 'init', [ $this, 'register_post_type' ] );
        add_action( 'wp_enqueue_scripts', [ $this, 'load_assets' ] );
        add_filter( 'the_content', [ $this, 'append_content' ] );
    }

    public function register_post_type() { /* ... */ }
    public function load_assets() { /* ... */ }
    public function append_content( $content ) {
        // zawsze zwracaj
        return $content;
    }
}

new My_Plugin();

Skanowanie bezpieczeństwa sprawdza, czy handlery AJAX zawierają zarówno sprawdzenie nonce, jak i sprawdzenie uprawnień przed wykonaniem jakichkolwiek działań:

add_action( 'wp_ajax_my_action', [ $this, 'handle_ajax' ] );

public function handle_ajax() {
    // Bezpieczeństwo: weryfikuj nonce
    check_ajax_referer( 'my_nonce_action', 'nonce' );

    // Bezpieczeństwo: weryfikuj uprawnienia
    if ( ! current_user_can( 'manage_options' ) ) {
        wp_send_json_error( 'Niewystarczające uprawnienia', 403 );
    }

    // Teraz bezpieczne do przetworzenia
    $data = sanitize_text_field( $_POST['data'] ?? '' );
    wp_send_json_success( [ 'result' => $data ] );
}

Brak któregokolwiek z nich jest oznaczany jako problem bezpieczeństwa i blokuje wydanie wtyczki.

Priorytet i kolejka hooków

Gdy wiele funkcji jest podłączonych do tego samego hooka, są one uruchamiane w kolejności priorytetu (niższa liczba = uruchamia się najpierw). Domyślny priorytet to 10.

add_action( 'init', 'runs_first', 5 );
add_action( 'init', 'runs_second', 10 );   // domyślny
add_action( 'init', 'runs_last', 20 );

Ma to znaczenie, gdy Twoja wtyczka musi działać przed lub po kodzie innej wtyczki. Jeśli modyfikujesz coś, co inna wtyczka również modyfikuje, priorytet kontroluje, kto wygrywa.

Częsty wzorzec: jeśli zastępujesz filtr motywu, użyj priorytetu 20 lub wyższego, aby upewnić się, że uruchomisz się po kodzie motywu.

Usuwanie hooków

Możesz usunąć hook, który ktoś inny dodał — w tym hooki motywów i wtyczek:

remove_action( 'wp_head', 'wp_generator' );  // usuwa wersję WP z <head>
remove_filter( 'the_content', 'wpautop' );   // usuwa automatyczne zawijanie akapitów

Pułapka: możesz usunąć hook tylko wtedy, gdy wywołasz remove_action/remove_filter po uruchomieniu oryginalnego add_action/add_filter. Zazwyczaj oznacza to podłączenie usuwania do późniejszej akcji.