Hooks WordPress

Hooks WordPress são pontos de extensão do CMS que permitem desenvolvedores adicionar ou modificar comportamentos sem editar o código fonte do WordPress. Existem duas categorias: actions, que executam código em momentos específicos do ciclo de vida (salvar post, exibir rodapé, fazer login), e filters, que modificam dados antes de serem usados (alterar título, modificar conteúdo do post, mudar preço de produto). Hooks são a base de praticamente toda customização avançada do WordPress.

O que são hooks no WordPress

O modelo de hooks foi introduzido no WordPress em 2003, ainda nas primeiras versões. A ideia: o core expõe “ganchos” durante sua execução. Em cada gancho, qualquer plugin ou tema pode anexar funções próprias para executar lógica adicional ou modificar o comportamento padrão. Isso desacopla o core das extensões — o WordPress nunca precisa conhecer seu plugin, mas seu plugin pode interceptar tudo o que o WordPress faz.

O que são hooks na prática: imagine que o WordPress está renderizando uma página. Em vários pontos desse processo, ele “avisa” quem estiver ouvindo: “agora estou prestes a renderizar o footer”, “agora terminei de salvar o post”, “agora vou enviar este email”. Plugins e temas se inscrevem para ouvir esses avisos e executam código quando eles acontecem. Cada um desses pontos de aviso é um hook.

Tecnicamente, hooks são implementados via funções PHP do WordPress: do_action() dispara um action, apply_filters() aplica um filter. No lado do plugin, add_action() e add_filter() registram funções para serem chamadas quando o action ou filter for disparado. É um padrão observer simples, mas extremamente poderoso quando aplicado em escala.

O modelo de hooks é o que torna o WordPress extensível. Mais de 60 mil plugins no repositório oficial dependem dele. Sem hooks, qualquer customização exigiria editar o core do WordPress — o que quebraria nas atualizações. Com hooks, plugins coexistem e estendem o sistema sem conflitar com o core ou entre si na maior parte do tempo.

Diferença entre actions e filters

Actions wordpress são hooks que executam código em momentos específicos. Não retornam valor, não modificam dados — só fazem algo. Exemplos clássicos: enviar email quando alguém comenta, registrar evento quando post é publicado, adicionar markup customizado no header, limpar cache quando configuração muda. A função recebe parâmetros (se o hook fornecer), executa lógica, e termina.

A sintaxe é direta: add_action(‘save_post’, ‘minha_funcao’, 10, 3). O primeiro parâmetro é o nome do hook, o segundo é a função a executar, o terceiro é a prioridade (padrão 10, menor número executa primeiro), o quarto é quantos argumentos a função aceita do hook. Quando alguém salva um post, o WordPress chama minha_funcao com os argumentos que save_post passa.

Filters wordpress são hooks que recebem dados, modificam, e devolvem os dados modificados. O WordPress aplica todos os filters registrados para um filter, em ordem de prioridade, e usa o resultado final. Exemplos clássicos: modificar o título do post antes de exibir, alterar conteúdo do post para adicionar texto, modificar URL de imagem para servir via CDN.

A sintaxe é parecida: add_filter(‘the_title’, ‘minha_funcao’, 10, 2). Mas a função registrada precisa receber o dado como primeiro parâmetro e retornar o dado (modificado ou não): function minha_funcao($title, $post_id) abre chave, return $title . ‘ – extra’, fecha chave. Se a função não retorna, o título vira null e o site quebra.

A regra para distinguir: action é “faça algo”, filter é “modifique algo”. Se você não precisa devolver nada, é action. Se você precisa receber dado, modificar e devolver, é filter. Tecnicamente, actions são implementados como filters internamente — mas o pattern conceitual é diferente.

Como usar hooks no functions.php

O lugar mais comum para registrar hooks customizados é o functions.php do tema (ou child theme), ou um plugin próprio. Você define a função com a lógica desejada, e logo depois chama add_action ou add_filter para registrá-la no hook apropriado. O WordPress gerencia o resto.

Exemplo prático: você quer adicionar um aviso de cookie no rodapé. No functions.php: function meu_aviso_cookie() abre chave, echo paragrafo com texto, fecha chave. add_action(‘wp_footer’, ‘meu_aviso_cookie’). Pronto. Toda página do site agora exibe o aviso no footer, sem precisar editar arquivo de tema.

Outro exemplo: você quer adicionar “- Site” ao final do título de cada post nos resultados de busca. function meu_titulo_busca($title) abre chave, if is_search return $title . ‘ – Site’, return $title, fecha chave. add_filter(‘the_title’, ‘meu_titulo_busca’). Filter aplicado, títulos modificados condicionalmente.

Hooks de plugin próprio seguem mesma lógica, mas dentro de um arquivo PHP de plugin. A vantagem do plugin é portabilidade: ao trocar de tema, customizações do functions.php somem, mas as do plugin continuam. Para customizações duradouras, sempre prefira plugin.

Combine isso com child theme bem estruturado e shortcodes registrados via hook init. Esse é o conjunto que permite construir customizações WordPress profissionais sem mexer em nada do core ou plugins de terceiros.

Hooks mais usados

O hook init é o ponto de entrada padrão para registrar funcionalidades. Custom post types, taxonomias, shortcodes, opções, suporte a recursos — quase tudo é registrado dentro de função anexada a init. É o primeiro hook que dispara depois que WordPress termina de carregar plugins e tema, então é seguro chamar qualquer função do CMS a partir dele.

O hook wp_enqueue_scripts é onde você registra CSS e JavaScript para o frontend do site. Funções wp_enqueue_style e wp_enqueue_script chamadas dentro de função anexada a wp_enqueue_scripts garantem que o WordPress gerencie ordem de carregamento, dependências e versões. Nunca inclua scripts diretamente no header.php — sempre via esse hook.

O hook the_content é o filter mais importante para conteúdo. Modifica o conteúdo do post antes de exibir. Plugins de SEO usam para adicionar markup, plugins de cache para inserir lazy load em imagens, plugins de afiliados para adicionar disclosure. Cuidado com performance — função pesada nesse hook executa em toda exibição de post.

O hook save_post dispara quando qualquer post (ou page, ou custom post type) é salvo. Útil para invalidar cache, sincronizar com sistemas externos, validar dados, registrar eventos. Sempre verifique se não é autosave ou revision com wp_is_post_autosave e wp_is_post_revision para evitar execuções desnecessárias.

Outros hooks essenciais: wp_head (adicionar tags ao head), wp_footer (adicionar markup antes do /body), admin_init (configurações de painel), admin_menu (adicionar páginas no menu admin), template_redirect (redirecionamentos baseados em condições), wp_mail (modificar emails do WordPress). A documentação oficial em developer.wordpress.org/reference/hooks lista todos.

Para projetos profissionais que precisam organizar dezenas de hooks e customizações de forma estruturada, com integração entre tema, plugins customizados e campos personalizados, a FULL Services entrega o ACF (Advanced Custom Fields) já licenciado e configurado dentro da stack profissional, junto com estrutura de plugins customizados e child theme prontos para receber lógica baseada em hooks. Em vez de espalhar add_action por dezenas de arquivos sem organização, você roda em uma estrutura modular que escala junto com a complexidade do projeto.