Action WordPress

Action WordPress é um tipo de hook que permite executar código PHP em momentos específicos do ciclo de vida do core, sem precisar editar arquivos originais. Quando o WordPress salva um post, envia um e-mail ou monta o cabeçalho de uma página, ele dispara actions. Plugins e temas se conectam a esses pontos via add_action e injetam comportamento próprio. É o mecanismo central de extensão do CMS desde a versão 1.2.

O que é uma Action no WordPress

Uma action é um ponto nomeado dentro do código do WordPress onde o sistema chama a função do_action e permite que outros desenvolvedores executem código naquele momento. Existem mais de 500 actions registradas no core, mais centenas adicionadas por plugins populares como WooCommerce, Yoast e Elementor.

O conceito vem do padrão observer: o core publica eventos e quem quiser reagir se inscreve. Em vez de modificar o arquivo wp-includes/post.php para mandar um Slack quando um post é publicado, você se conecta à action publish_post via um plugin. O core atualiza, seu código continua funcionando, e a separação fica limpa.

A action wordpress mais conhecida é init, disparada logo após o WordPress carregar todos os plugins. Boa parte do registro de custom post types, taxonomias e shortcodes acontece nela. Outras frequentes são wp_enqueue_scripts, save_post, admin_menu e template_redirect, cada uma marcando um momento crítico de execução.

Diferente de funções comuns, actions não retornam valor. Elas existem apenas para disparar efeitos colaterais: salvar dados, enviar requisições, escrever no log. Quem precisa modificar dados em trânsito usa filters, o outro tipo de hook do WordPress.

Como Actions funcionam

O fluxo é simples e segue sempre o mesmo padrão. O core (ou um plugin) define um ponto de extensão chamando do_action(‘nome_da_action’). Em outro lugar, seu código registra uma função usando add_action(‘nome_da_action’, ‘sua_funcao’). Quando o WordPress chega no do_action, ele executa todas as funções inscritas na ordem definida pela prioridade.

O add_action aceita quatro parâmetros: o nome da action, o callback que será executado, a prioridade (padrão 10) e o número de argumentos aceitos. Prioridades menores rodam primeiro. Se dois plugins se inscrevem na mesma action com prioridade igual, a ordem segue o registro.

Algumas actions passam parâmetros. publish_post, por exemplo, entrega o ID do post recém-publicado para qualquer função inscrita. Outras como wp_footer não passam nada, são apenas marcadores temporais. Antes de inscrever um callback, consulte a referência oficial em developer.wordpress.org/reference/hooks para saber o que cada action oferece.

Ordem de execução

Durante uma requisição típica do front-end, o WordPress dispara dezenas de actions em sequência fixa: muplugins_loaded, plugins_loaded, init, wp_loaded, parse_request, send_headers, wp, template_redirect, wp_head, wp_footer, shutdown. Conhecer essa ordem é o que diferencia um desenvolvedor júnior de um sênior. Inscrever um callback na action errada gera bugs sutis, como tentar acessar o objeto $post antes de ele existir.

Como criar uma Action customizada

Plugins maduros expõem suas próprias actions para que outros desenvolvedores estendam o comportamento. WooCommerce, por exemplo, dispara woocommerce_before_checkout_form, woocommerce_thankyou e dezenas de outras durante o fluxo de compra. Você pode criar suas próprias seguindo o mesmo padrão.

Para registrar uma action customizada, basta chamar do_action(‘minha_acao’) no ponto certo do seu código. Se quiser passar dados, adicione argumentos: do_action(‘minha_acao’, $usuario, $pedido). A partir daí, qualquer plugin pode se conectar com add_action(‘minha_acao’, ‘callback’, 10, 2).

Exemplo prático: você desenvolve um plugin de gestão de assinaturas e quer permitir que outros plugins reajam quando uma assinatura é renovada. Dentro da função de renovação, dispare do_action(‘assinatura_renovada’, $assinatura_id). Outro plugin pode se inscrever para enviar notificação no Telegram, atualizar planilha no Google Sheets ou disparar tag no GA4. Você não conhece esses outros plugins, mas a action já está pronta para eles.

O nome da action deve ser único e descritivo, com prefixo do seu plugin para evitar conflitos. Em vez de renovou, use meuplugin_assinatura_renovada. Para entender melhor o ecossistema completo de pontos de extensão, vale revisar como hooks WordPress se dividem em actions e filters e como ambos compõem a base de qualquer plugin WordPress.

Actions vs Filters: diferenças

Actions e filters são os dois tipos de hooks do WordPress, mas servem propósitos opostos. Actions executam código em momentos específicos sem precisar retornar nada. Filters interceptam dados, modificam e devolvem valor alterado. Saber qual usar é decisão diária no desenvolvimento WordPress profissional.

Use action quando o objetivo é fazer algo: registrar uma rota REST, agendar um cron, enviar e-mail, gravar log. O resultado da função inscrita é descartado. Use filter WordPress quando precisar transformar um dado: alterar o título de um post antes de exibir, adicionar campos ao usuário, modificar o conteúdo do feed RSS. Filters sempre exigem return.

O confronto actions wordpress hooks vs filters aparece na pergunta clássica: quero adicionar um banner depois do conteúdo do post. Action ou filter? A resposta depende. Se quiser exibir HTML solto via wp_footer ou similar, é action. Se quiser concatenar o banner ao conteúdo retornado por the_content, é filter. Cada caso pede o hook certo.

Misturar os dois é comum em plugins reais. WooCommerce dispara woocommerce_thankyou (action) na página de obrigado e também filtra woocommerce_email_subject (filter) para alterar o assunto do e-mail. Você usa add_action e add_filter de forma intercalada conforme a necessidade. Tudo apoiado por código bem organizado em arquivos como functions.php ou plugins dedicados.

Para times que mantêm sites WordPress complexos com muitos hooks customizados, a FULL Services entrega o ACF (Advanced Custom Fields) já licenciado dentro da stack profissional, junto com a curadoria de ferramentas de desenvolvimento que aceleram o trabalho com actions e filters. Em vez de configurar o ambiente do zero, você roda em uma base validada com tudo que precisa para estender o WordPress de forma estável.