Guia dos WordPress Hooks: Actions e Filters

O que são os WordPress hooks

O sistema de hooks do WordPress é a base que lhe permite estender e modificar o sistema WordPress sem alterar diretamente o código-fonte. Os hooks são pontos no código do WordPress onde pode ligar as suas funções, que serão executadas num momento específico ou modificarão os dados que passam pelo sistema. Sem os hooks, cada personalização exigiria a modificação direta dos ficheiros do core do WordPress, que se perderiam a cada atualização.

Existem dois tipos de hooks — as actions e os filters. As actions permitem-lhe executar código num momento específico do ciclo de vida do WordPress, enquanto os filters lhe permitem modificar dados antes de serem apresentados ou guardados. Compreender estes dois conceitos é fundamental para qualquer programador WordPress, porque são a base para criar temas, plugins e funcionalidades personalizadas.

Actions — executar código no momento certo

Como funcionam as actions

Um action hook é um local no código do WordPress onde é colocada uma chamada à função do_action. Quando o WordPress chega a esse ponto durante a execução, verifica se há funções ligadas a esse hook e executa-as por ordem de prioridade. Por exemplo, a action wp_head dispara dentro da tag head de cada página, a wp_footer dispara antes da tag de fecho body e a init dispara no início de cada carregamento do WordPress, depois de todos os plugins estarem carregados.

Utilizar o add_action

A função add_action recebe quatro parâmetros — nome do hook, função de callback, prioridade e número de argumentos. A prioridade determina a ordem de execução quando há várias funções ligadas ao mesmo hook, sendo o valor predefinido 10, em que um número mais baixo significa execução mais cedo. Por exemplo, se quiser adicionar o código do Google Analytics ao cabeçalho do site, ligue a função ao hook wp_head com a prioridade 1 para que seja executada entre as primeiras. Se quiser adicionar CSS depois de todos os plugins, use a prioridade 99.

Action hooks mais comuns

• init: Dispara no início de cada pedido, depois de os plugins carregarem. Ideal para registar custom post types, taxonomias e shortcodes.
• wp_enqueue_scripts: A forma correta de adicionar ficheiros CSS e JavaScript no frontend. Usa as funções wp_enqueue_style e wp_enqueue_script para gerir dependências e evitar duplicados.
• admin_init: Dispara no início de cada página de administração. Use para registar definições do plugin, verificações de permissões ou redirecionamentos.
• save_post: Dispara quando um post é guardado ou atualizado. Ideal para guardar meta dados personalizados, validar conteúdo ou enviar notificações.
• wp_login e wp_logout: Disparam no login e logout do utilizador. Use para registo de atividade, redirecionamentos ou limpeza de cache.
• template_redirect: Dispara antes do carregamento do template. Ideal para redirecionamentos personalizados ou verificações de acesso à página.

Filters — modificação de dados

Como funcionam os filters

Um filter hook funciona de forma semelhante a um action hook, mas com uma diferença essencial — o filter recebe dados, modifica-os e devolve os dados modificados. O WordPress usa a função apply_filters para passar os dados por todas as funções de filter ligadas. Cada função de filter tem de devolver um valor, porque caso contrário os dados ficam vazios. Por exemplo, o filter the_content passa o conteúdo do post por todas as funções ligadas antes da apresentação, permitindo que os plugins adicionem botões de partilha em redes sociais, posts relacionados ou anúncios dentro do conteúdo.

Utilizar o add_filter

A função add_filter tem uma sintaxe idêntica à do add_action — nome do hook, função de callback, prioridade e número de argumentos. A diferença essencial é que a função de callback tem de receber pelo menos um argumento que representa os dados a filtrar e tem de devolver os dados modificados ou originais. Se a sua função de filter não devolver um valor, os dados serão perdidos, o que pode quebrar o site. Teste sempre as funções de filter para garantir que devolvem o valor correto mesmo em casos extremos.

Filter hooks mais comuns

• the_content: Filtra o conteúdo do post antes da apresentação. Plugins de formatação, shortcodes e modificações de conteúdo usam este filter.
• the_title: Filtra o título do post. Use para adicionar prefixos, sufixos ou formatar títulos de forma programática.
• wp_mail: Filtra os parâmetros do e-mail antes do envio. Pode modificar os destinatários, o assunto, o conteúdo ou os cabeçalhos do e-mail.
• login_redirect: Filtra o URL para onde o utilizador é redirecionado após o login. Use para redirecionamentos personalizados com base no papel do utilizador.
• excerpt_length: Filtra o comprimento do excerto gerado automaticamente. O valor predefinido é de 55 palavras.
• upload_mimes: Filtra os tipos de ficheiro permitidos para upload. Use para adicionar suporte a SVG ou outros formatos.

Criar os seus próprios hooks

Action hooks personalizados

Ao desenvolver um plugin ou tema, criar os seus próprios hooks permite que outros programadores estendam a sua funcionalidade sem alterar o seu código. Coloque chamadas do_action em locais onde queira permitir extensões — por exemplo, antes e depois da apresentação de um formulário, antes de guardar dados ou depois de processar uma encomenda. Nomeie os hooks com o prefixo do seu plugin para evitar conflitos com outros plugins, por exemplo myplugin_pre_save_data. Documente os hooks disponíveis com uma descrição de quando disparam e que argumentos passam.

Filter hooks personalizados

Use o apply_filters em locais onde queira permitir a modificação de dados. Por exemplo, se o seu plugin gera uma lista de itens, passe o array de itens por um filter antes da apresentação. Outros programadores podem ligar um filter para adicionar, remover ou modificar itens. Para cada filter, documente claramente o tipo de dados que está a ser filtrado, o formato esperado do valor de retorno e o contexto em que o filter é usado. Isto torna o seu plugin agradável de estender e reduz a necessidade de modificações diretas.

Desenvolvimento de plugins com hooks

Estrutura do plugin

Cada plugin WordPress começa com um comentário de cabeçalho que contém o nome do plugin, a descrição, a versão, o autor e a licença. O ficheiro principal do plugin normalmente regista os hooks no construtor da classe ou numa função de inicialização. Organize o código em classes com métodos para cada funcionalidade e use o construtor para registar todos os hooks num único local. Isto torna o código legível e mais fácil de manter, porque consegue ver todos os hooks num só lugar.

Ativação e desativação

O WordPress disponibiliza hooks especiais, register_activation_hook e register_deactivation_hook, que disparam na ativação e desativação do plugin. Use o hook de ativação para criar tabelas na base de dados, definir opções predefinidas e agendar tarefas cron. Use o hook de desativação para limpar tarefas cron agendadas e dados temporários. Para a remoção completa dos dados ao eliminar o plugin, crie um ficheiro uninstall.php que apague as opções da base de dados, as tabelas personalizadas e os ficheiros carregados.

Boas práticas

Use sempre prefixos para os nomes de funções e classes, de modo a evitar conflitos com outros plugins. Verifique se um hook existe antes de o registar para evitar erros. Use o has_action e o has_filter para verificar se alguém já está ligado a um hook específico. Remova hooks com o remove_action e o remove_filter quando precisar de modificar o comportamento de outro plugin ou tema. A prioridade é fundamental ao remover — tem de usar a mesma prioridade usada ao adicionar.

Depuração de hooks

Ferramentas de depuração

O plugin Query Monitor é uma ferramenta indispensável para a depuração de hooks, que apresenta todos os hooks registados, a ordem de execução e o tempo que cada hook consome. A constante WP_DEBUG no wp-config.php permite a apresentação de erros e avisos PHP que ajudam a identificar problemas com os hooks. O plugin Debug Bar adiciona um painel na barra de administração com informações sobre hooks, consultas à base de dados e utilização de memória. Para depuração avançada, o Xdebug com o VS Code permite definir breakpoints dentro das funções de callback dos hooks.

Erros comuns

O erro mais comum é uma função de filter que não devolve um valor, resultando em conteúdo vazio. Outro erro comum é um número de argumentos incompatível entre o registo do hook e a função de callback. Um loop infinito ocorre quando um filter modifica os dados de uma forma que volta a acionar o mesmo filter. Use uma variável estática ou uma flag para evitar a recursão. Uma prioridade errada pode fazer com que a sua função não funcione, porque um hook anterior alterou os dados de forma inesperada. Nos planos de alojamento WordPress da BeoHosting temos um ambiente otimizado para o desenvolvimento de plugins, com suporte para ferramentas de depuração e memória PHP suficiente para cadeias de hooks complexas.

Conclusão

O sistema de hooks do WordPress é um mecanismo poderoso e elegante que permite uma extensão sem limites do WordPress. As actions dão-lhe a capacidade de executar código no momento certo, enquanto os filters permitem a modificação de dados em qualquer ponto do sistema. Compreender os hooks é fundamental para a transição de utilizador para programador e abre a porta à criação de plugins e temas profissionais. Comece pelos hooks mais utilizados, experimente a personalização e construa gradualmente funcionalidades mais complexas. Se está apenas a instalar o WordPress, consulte o nosso guia de instalação.