add_filter în WordPress

add_filter( string $hook_name, callable $callback, int $priority = 10, int $accepted_args = 1 ): true

Ce face add_filter

Un filtru este un punct în care WordPress trece o valoare prin apply_filters() înainte s-o folosească: titlul, conținutul, lista de clase CSS, lungimea rezumatului. Cu add_filter() înregistrezi o funcție care primește valoarea, o poate schimba și trebuie să o întoarcă cu return.

Doar primul argument (valoarea filtrată) poate fi modificat. Celelalte argumente trimise de apply_filters() sunt doar context (de exemplu ID-ul articolului) și le primești doar dacă ceri mai multe prin $accepted_args.

WordPress are funcții gata făcute pentru filtrele simple: __return_true, __return_false, __return_zero, __return_empty_array, __return_empty_string, __return_null.

Parametri

Parametru	Descriere
$hook_name	Numele filtrului, de exemplu 'the_content', 'body_class', 'excerpt_length'.
$callback	Funcția care primește valoarea și o întoarce (modificată sau nu).
$priority	Opțional, implicit 10. Valorile mai mici rulează primele; fiecare funcție primește rezultatul celei dinainte.
$accepted_args	Opțional, implicit 1. Câte argumente primește funcția din cele trimise de apply_filters().

Ce returnează

Întotdeauna true, chiar dacă $callback nu este valid.

Exemple

Exemplul 1: Rezumate mai scurte

Filtrul excerpt_length primește numărul de cuvinte din rezumatele generate automat (implicit 55). Funcția întoarce 30.

add_filter( 'excerpt_length', 'dex_lungime_rezumat' );

function dex_lungime_rezumat( $lungime ) {
    return 30;
}

Exemplul 2: O clasă CSS în plus pe <body>

body_class primește un tablou de clase. Adăugăm una pe prima pagină și întoarcem tabloul întreg; tema afișează lista în eticheta <body> prin body_class(), iar dex-cafenea-iasi apare alături de celelalte clase (home, blog etc.).

add_filter( 'body_class', 'dex_clasa_body' );

function dex_clasa_body( $clase ) {
    if ( is_front_page() ) {
        $clase[] = 'dex-cafenea-iasi';
    }
    return $clase;
}

Exemplul 3: Editorul clasic cu __return_false

Filtrul use_block_editor_for_post decide dacă un articol se deschide în editorul de blocuri. __return_false întoarce mereu false, deci nu mai e nevoie de o funcție proprie.

add_filter( 'use_block_editor_for_post', '__return_false' );

Greșeli frecvente

• Lipsește return: funcția întoarce null, iar valoarea filtrată dispare (de exemplu, conținutul articolului apare gol).
• echo într-un filtru: textul apare în locul greșit din pagină, de obicei deasupra conținutului. Construiește textul și întoarce-l.
• Ai cerut un argument în plus (de exemplu $post_id la the_title), dar ai lăsat $accepted_args la 1: scrie add_filter( 'the_title', 'dex_titlu', 10, 2 ).

Comenzi înrudite

• apply_filters: Trece o valoare prin toate funcțiile legate de un filtru și întoarce rezultatul final; cu un nume nou, creează un filtru propriu.
• add_action: Leagă o funcție de o acțiune WordPress, ca să ruleze automat când WordPress ajunge în acel punct.
• remove_action: Scoate o funcție legată de o acțiune sau de un filtru; callback-ul și prioritatea trebuie să fie identice cu cele de la adăugare.
• the_content: Filtrul prin care trece conținutul unui articol după ce este citit din baza de date și înainte de a fi afișat.