Atualizado em 19/06/2026
Quase tudo que você customiza no WordPress sem editar o núcleo passa por hooks. São pontos de extensão que o WordPress (e plugins como o WooCommerce) expõe ao longo da execução, onde o seu código pode "se pendurar". Existem dois tipos — actions e filters — e entender a diferença entre eles resolve a maior parte das dúvidas de quem está começando a programar para WordPress.
Action × Filter: a diferença essencial
A distinção é simples e vale memorizar:
- Action: executa código em um momento específico. Não recebe um valor para devolver — você apenas faz algo (enfileirar um script, registrar um menu, enviar um e-mail).
- Filter: recebe um valor, deixa você modificá-lo e exige que você o retorne. Serve para alterar dados antes de serem salvos ou exibidos.
| Action | Filter | |
|---|---|---|
| Para que serve | Executar um efeito | Modificar e devolver um valor |
| Registra com | add_action() | add_filter() |
| Dispara com | do_action() | apply_filters() |
Precisa dar return? | Não | Sim, sempre |
Actions: executando código no momento certo
Você "pendura" uma função em um hook com add_action( $hook, $callback ). O exemplo clássico é enfileirar CSS/JS no hook wp_enqueue_scripts:
<?php
add_action( 'wp_enqueue_scripts', 'meu_tema_assets' );
function meu_tema_assets() {
wp_enqueue_style( 'meu-estilo', get_stylesheet_uri(), array(), '1.0.0' );
wp_enqueue_script( 'meu-script', get_template_directory_uri() . '/js/app.js', array( 'jquery' ), '1.0.0', true );
}Aqui, meu_tema_assets() roda quando o WordPress chega ao momento de carregar scripts e estilos — nem antes, nem depois. Usar o hook certo é o que garante que as funções (wp_enqueue_style, etc.) já existam e funcionem.
Filters: modificando valores
Um filter recebe um valor e precisa devolvê-lo. Este exemplo encurta o resumo (excerpt) para 20 palavras:
<?php
add_filter( 'excerpt_length', 'meu_tamanho_resumo' );
function meu_tamanho_resumo( $length ) {
return 20; // sempre retorne um valor
}O erro mais comum em filters é não retornar. Veja o contraste:
<?php
// ERRADO: não retorna nada -> o conteúdo some
add_filter( 'the_content', function ( $content ) {
$content .= '<p>Texto extra.</p>';
// faltou o return!
} );
// CERTO
add_filter( 'the_content', function ( $content ) {
return $content . '<p>Texto extra.</p>';
} );Prioridade e número de argumentos
As assinaturas completas são add_action( $hook, $callback, $priority = 10, $accepted_args = 1 ) e add_filter( ... ) com os mesmos parâmetros. Dois detalhes que causam muito bug:
- Prioridade (padrão
10): menor roda primeiro. Para sobrescrever algo de um plugin, use prioridade maior. $accepted_args: se o hook passa mais de um argumento e você quer recebê-los, precisa declarar quantos. Por padrão, o callback recebe só o primeiro.
<?php
// Queremos os 2 argumentos que o hook 'save_post' passa: $post_id e $post
add_action( 'save_post', 'minha_acao_ao_salvar', 10, 2 );
function minha_acao_ao_salvar( $post_id, $post ) {
if ( wp_is_post_revision( $post_id ) ) {
return; // ignora revisões
}
// ... seu código aqui, usando $post_id e $post
}Criando os seus próprios hooks
Você não só consome hooks — pode expô-los no seu plugin ou tema, deixando que outros estendam o seu código. Use do_action() para actions e apply_filters() para filters:
<?php
// Um action: avisa que algo aconteceu (sem esperar retorno)
do_action( 'meu_plugin_apos_pedido', $pedido_id );
// Um filter: deixa terceiros ajustarem um valor antes de usá-lo
$preco_final = apply_filters( 'meu_plugin_preco_final', $preco, $produto_id );É exatamente assim que o WooCommerce permite, por exemplo, alterar o texto do botão "comprar" ou injetar campos no checkout — tema do artigo sobre hooks do WooCommerce.
Removendo hooks
Para desligar algo adicionado pelo núcleo, por um tema ou plugin, use remove_action() / remove_filter() com o mesmo callback e a mesma prioridade do registro original:
<?php
// Remove a meta tag <meta name="generator"> com a versão do WordPress
remove_action( 'wp_head', 'wp_generator' );Se a prioridade não bater com a usada no add_action original, a remoção silenciosamente não acontece. E callbacks registrados como funções anônimas (closures) são difíceis de remover, porque você não tem a referência ao objeto — por isso, em código que talvez precise ser desfeito, prefira funções nomeadas ou métodos de classe.
Erros comuns (e como evitar)
| Sintoma | Causa provável | Correção |
|---|---|---|
| Conteúdo some ao usar um filter | Função não deu return | Sempre retorne o valor (mesmo sem alterá-lo) |
| Callback recebe só 1 argumento | $accepted_args não declarado | Informe o nº de argumentos no add_* |
| Seu código não roda | Hook registrado tarde demais | Registre cedo (ex.: em plugins_loaded/init) |
remove_action não faz efeito | Prioridade diferente do original | Use a mesma prioridade e rode depois do add |
Hooks são também a forma correta de manter customizações fora do tema (que pode ser atualizado) — geralmente em um plugin próprio. E lembre-se da segurança: dados que entram em um callback devem ser sanitizados, e o que sai deve ser escapado.
Perguntas frequentes
Qual a diferença entre action e filter?
Um action dispara código em um determinado momento da execução e não espera retorno — você executa um efeito (enfileirar um script, enviar um e-mail, registrar algo). Um filter recebe um valor, permite modificá-lo e obrigatoriamente o retorna — serve para alterar dados antes de serem usados ou exibidos. Regra prática: se você precisa mudar e devolver um valor, é filter; se precisa apenas fazer algo, é action.
Por que meu filter "não funciona"?
A causa nº 1 é esquecer de retornar o valor. Uma função de filter que não dá return devolve null e quebra o conteúdo. A nº 2 é não declarar $accepted_args quando o hook passa mais de um argumento: por padrão o callback recebe só o primeiro. A nº 3 é registrar o hook tarde demais (depois do momento em que ele já disparou).
O que é a prioridade de um hook?
É o número (padrão 10) que define a ordem de execução quando várias funções usam o mesmo hook: menor roda antes, maior roda depois. Para sobrescrever algo adicionado por um plugin, registre seu callback com prioridade maior (ex.: 99). Prioridades iguais executam na ordem em que foram adicionadas.
Como remover um hook adicionado por um plugin ou tema?
Com remove_action() / remove_filter(), informando o mesmo nome de hook, o mesmo callback e a mesma prioridade usados no add_* original — se a prioridade não bater, a remoção não acontece. Além disso, a remoção precisa rodar depois de o hook ter sido adicionado. Callbacks registrados como funções anônimas (closures) são difíceis de remover, pois você não tem a referência.
Hooks deixam o site lento?
O sistema de hooks em si é leve. O que pesa é o que você coloca dentro deles: uma consulta pesada no hook init roda em toda requisição. Use o hook certo para o contexto (admin, front-end, cron) e evite trabalho caro em hooks que disparam sempre. Veja também cache de objeto.