Filter WordPress

Filter WordPress é um tipo de hook que intercepta valores durante a execução do CMS para modificá-los antes que sejam usados ou exibidos. Diferente das actions, que disparam código em momentos específicos, os filters sempre recebem um dado, processam e retornam uma versão alterada. É um dos pilares de extensibilidade do WordPress: permite que plugins e temas mudem comportamento do core sem editar arquivos do core.

O que é um Filter no WordPress

Um filter é um ponto de extensão definido pelo core, por temas ou por plugins onde um valor é “oferecido” para modificação. Quando o WordPress chega a esse ponto, ele chama todas as funções registradas para aquele filter, passa o valor original e usa o valor retornado pela última função da fila. Se nenhum filter foi registrado, o valor passa intacto.

O conceito é antigo na arquitetura WordPress, presente desde a versão 0.71 de 2003. A ideia foi inspirada no padrão de hooks do qual o sistema todo depende. Em 2026, o core registra mais de 2 mil filters diferentes, espalhados por todas as áreas funcionais: queries, conteúdo, login, REST API, mídia, comentários, taxonomias.

Filters são executados em ordem de prioridade, definida pelo terceiro parâmetro de add_filter. Prioridade padrão é 10. Valores menores rodam antes, valores maiores rodam depois. Esse controle fino permite que plugins se acomodem entre si sem se sobrescreverem, desde que cada um use prioridade coerente com sua função.

Os filters wordpress não substituem o core. Eles complementam. O fluxo padrão sempre roda; o que muda é o valor final consumido após o filter aplicar. Isso preserva a compatibilidade entre versões e evita o desastre de plugins que reescrevem partes do CMS.

Como Filters funcionam

Internamente, todo filter é registrado em um array global gerenciado pela classe WP_Hook. Quando o core chama apply_filters(‘nome_do_filter’, $valor, $arg1, $arg2), o WordPress procura no array todas as funções vinculadas àquele nome, ordena por prioridade e executa em sequência, passando o $valor de uma para a próxima.

Cada função registrada precisa retornar o valor recebido (ou uma versão modificada). Se esquecer o return, o valor vira null e quebra a saída do que vinha depois. É o erro mais comum em quem aprende a usar filters: tratar como action e simplesmente alterar variáveis sem devolver o resultado.

Exemplo simples. O filter the_title passa o título do post antes de ser exibido. Para adicionar um prefixo em títulos da home, você escreve uma função que recebe o título, concatena com o prefixo e retorna o novo valor. Em três linhas em functions.php, todo título da home muda, sem tocar no template do tema.

Filters podem aceitar múltiplos argumentos além do valor principal. O quarto parâmetro de add_filter define quantos argumentos a função aceita. Em filters como wp_insert_post_data, isso é fundamental: você recebe o array de dados do post e o array original, e pode validar antes de salvar. É a base de plugins de auditoria e validação editorial.

Como criar um Filter customizado

Tema ou plugin pode declarar seus próprios filters para abrir pontos de extensão. A sintaxe é idêntica: apply_filters(‘meu_filter’, $valor_original) onde quer que outros desenvolvedores possam interceptar. Esse padrão é o que diferencia plugins extensíveis de plugins fechados.

Para criar, basta inserir a chamada no ponto certo do código. Plugins maduros como WooCommerce expõem dezenas de filters por arquivo, com nomes prefixados e documentação inline. Isso permite que extensões e temas se conectem sem precisar editar o plugin principal. É também base do que se chama de “plugin friendly architecture”.

Para registrar uma função no filter, use add_filter(‘nome’, ‘minha_funcao’, 10, 1). Os parâmetros são: nome do filter, callback, prioridade e número de argumentos. O hook “hooks” cobre tanto actions quanto filters. Em hooks WordPress, a diferença é exatamente que action não retorna valor e filter sempre retorna.

Boas práticas em add_filter incluem: nomear o filter com prefixo único do plugin (ex: minhaempresa_post_title), documentar o tipo do valor recebido e retornado, evitar lógica pesada dentro do callback (rode em ação separada), e remover o filter com remove_filter quando o efeito for temporário.

Filters mais usados

the_content é provavelmente o filter mais usado de todos. Modifica o conteúdo do post antes da exibição. Plugins de SEO injetam disclaimer, plugins de share adicionam botões e plugins de related posts incluem o bloco no fim do texto. Tudo via the_content.

the_title modifica o título de qualquer post na hora da exibição. Útil para adicionar tags, ícones ou contadores em listagens. Mais barato que tocar nos templates, e funciona em qualquer tema sem dependência.

wp_nav_menu_items altera o HTML do menu de navegação. Permite injetar itens dinâmicos como link de carrinho, botão de login condicional ou itens diferentes para usuários logados. É filtro essencial em e-commerces e áreas de membros.

excerpt_length e excerpt_more controlam o resumo automático em listagens. Combinar os dois personaliza o comportamento do trecho exibido em arquivos e busca. Essa dupla cobre o caso onde o tema gera resumos curtos demais ou com reticências indesejadas.

posts_where e posts_join entram em queries customizadas, permitindo modificar a cláusula SQL antes do banco ser consultado. São poderosos e perigosos: usar errado quebra paginação, ordem e indexação. Boas functions.php isolam esses filters em condições restritas para evitar efeitos colaterais.

Filters relacionados a action WordPress compartilham infraestrutura e padrões. Quem entende um, entende o outro. A diferença prática é apenas o tipo de retorno e o uso conceitual.

Para projetos que dependem de manipular dados antes de exibir ao visitante, criar campos customizados ou expor pontos de extensão para outros plugins, a FULL Services entrega o ACF já licenciado dentro da stack profissional. Combinado com filters personalizados em apply_filters, o ACF permite construir lógica editorial avançada sem reinventar fluxos manuais para cada caso.