Um guia para ganchos do WordPress

Publicados: 2021-07-19

O sistema de ganchos pode parecer assustador para os não iniciados, mas eles são uma das melhores coisas sobre o WordPress. Este guia o ajudará a entender os fundamentos dos ganchos e como usá-los, fornecendo exemplos de uso e mais conselhos.

Por que você deve usar ganchos?

Caso você ainda não saiba, é realmente uma má ideia alterar os arquivos principais no WordPress (WP). Deixando de lado os riscos de segurança, suas alterações serão substituídas toda vez que você atualizar o WP! O mesmo vale para plug-ins e temas.

Claro, você pode acompanhar todas as atualizações e reimplementar suas alterações. Você também pode perfurar uma colmeia para obter o mel. Pode parecer conveniente, mas é provável que você seja picado mais cedo ou mais tarde.

Simplificando, você deve usar ganchos porque eles compensam os riscos de alterar a funcionalidade principal .

Nesse sentido, a importância dos ganchos não pode ser exagerada . Eles são a chave para a extensibilidade do WP e a base de seu plug-in e ecossistemas de tema. Você evitará muitas dores de cabeça aprendendo o básico e utilizando-o bem.

O que eles são?

Você pode pensar em ganchos como eventos que ocorrem em toda a sequência de carregamento do WP. Quando o WP encontra um gancho, ele dispara todas as funções anexadas a esse gancho antes de continuar.

Você pode, portanto, aproveitar os ganchos para adicionar funcionalidade ou alterar variáveis ​​em todo o WP . Você pode usar ganchos existentes e adicionar novos. Você pode remover os ganchos de que não precisa. Você pode acertar o mesmo gancho mais de uma vez, priorizando cada função como achar melhor. É um sistema muito flexível, limitado apenas pelos ganchos disponíveis e pelos dados que eles expõem.

Como eles funcionam?

Você adiciona uma ou mais funções a um gancho. Outras funções também podem ser adicionadas pelo seu tema, plug-ins ou pelo próprio WP. Quando o WP for carregado, ele encontrará o gancho. Ele verifica uma lista de todas as funções associadas ao gancho. O WP executa todas essas funções em ordem de prioridade . Feito isso, ele retoma o carregamento de tudo após o gancho.

Como eles se parecem?

Adicionar uma função a um gancho tem a seguinte aparência:

add_action ($ hook_name, $ function_name, $ priority, $ arguments);

$ hook_name é o nome do gancho que você deseja atingir

$ function_name é o nome da função que você deseja adicionar a esse gancho

$ prioridade é um número inteiro, indicando o $ function_name de prioridade em $ hook_name da fila. Quanto menor o número, maior a prioridade. A partir de 1, esse número pode ser tão alto quanto você deseja (dentro dos limites do sistema), mas é improvável que você o veja acima de 40. O valor padrão é 10.

$ argumentos é um número inteiro que indica o número de argumentos que você está usando na função. Este deve corresponder ao número de argumentos passados para a função. O valor padrão é 1.

Remover uma função de um gancho é quase o mesmo:

remove_action ($ hook_name, $ function_name, $ priority);

O $ function_name e $ priority devem coincidir com seus valores originais da função add_action correspondente , ou eles não serão removidos!

Tipos de gancho

Existem dois tipos principais de ganchos: ganchos de ação e ganchos de filtro . Eles são semelhantes em muitos aspectos - add_action () e sua contraparte add_filter () são ambos chamados da mesma maneira. A diferença está na função pela qual você passa:



// Execute algum código

add_action ('onde_para_fazer_coisa_coisa', 'fazer_a_coisa');

function do_the_thing () {

// Execute alguma ação necessária para fazer a coisa

}


// Mudar uma variável

add_filter ('the_thing', 'change_the_thing');

function change_the_thing ($ thing) {

// Filtre $ coisa e mude para o que você precisar, então ...
		




return $ thing;

}

Note-se que no segundo exemplo, o primeiro argumento passado para o functio n é o valor ser alterado. Quaisquer argumentos adicionais seriam apenas para utilidade e não seriam passados ​​de volta pelo gancho.

Você deve ter notado que deixei de fora $ priority e $ arguments . Isso ocorre porque os valores padrão são adequados. Se ajudar, o acima exposto é essencialmente o mesmo que:



// Execute algum código

add_action ('onde_para_fazer_coisa_coisa', 'fazer_a_coisa', 10, 1);

// Mudar uma variável

add_filter ('the_thing', 'change_the_thing', 10, 1);

Esses são exemplos inventados, é claro, mas ilustram a principal diferença entre os dois: os filtros são para alterar variáveis, as ações são para adicionar código.

Exemplos menos inventados

Digamos que você queira que o WP envie uma notificação por e-mail quando um novo usuário se registrar em seu site. Referindo-se ao códice WP, você encontra o gancho de ação user_register . Isso fornece uma variável $ user_id , que você pode usar para obter os detalhes do usuário. wp_mail () cuida do resto:



add_action ('user_register', 'notification_on_user_registration');

função notificar_on_usuário_registração ($ user_id) {


// Obtenha o usuário

$ user = get_user_by ('id', $ user_id);


// Prepare o assunto e o corpo do e-mail

$ subject = “Registro de novo usuário”;

$ message = “Um novo usuário {$ user-> first_name} {$ user-> last_name} foi registrado.”;
		




// Envie o email

wp_mail ('você@seudomínio.com', $ assunto, $ mensagem);

}

E se você quiser redirecionar os usuários para a sua página inicial no login? Você consegue isso facilmente com o gancho login_redirect , que fornece a URL para a qual os usuários são redirecionados por padrão:



add_filter ('login_redirect', 'redirect_user_on_login');

function redirect_user_on_login ($ redirect_to) {

return home_url ();

}

Logo depois de adicionar isso, você rapidamente percebe que, como administrador, deseja ser levado diretamente para o painel do WP em vez da página inicial. Não é um problema - você apenas altera o gancho para funcionar apenas para administradores:



add_filter ('login_redirect', 'redirect_user_on_login', 10, 3);

function redirect_user_on_login ($ redirect_to, $ request, $ user) {

// Altere o URL de login, a menos que o usuário seja um administrador

if (isset ($ user-> roles) && is_array ($ user-> roles)) {

if (in_array ('administrador', $ usuário-> funções)) {

return $ redirect_to; // Redirecionar administradores para o padrão (área administrativa)

}

}


return $ redirect_to;

}

Observe que os argumentos $ priority e $ entraram em jogo!

Visto que você precisa acessar o terceiro argumento do gancho para verificar o nível do usuário, você precisa exibir 3 argumentos; você passa um valor de 3.

O valor de $ priority de 10 é o mesmo que o padrão, é claro, mas é especificado para atingir o valor de $ arguments que você precisava acima.

Criando seus próprios ganchos

O poder de criar ganchos personalizados está em suas mãos! As funções fornecidas pelo WP são semelhantes a estas:

do_action ($ hook_name, $ arg_1, $ arg_2… $ arg_n);

filtros_de_plicação ($ hook_name, $ arg_1, $ arg_2… $ arg_n);

Novamente, eles são parecidos. Ambas as funções aceitam um nome - é aqui que você nomeia o gancho. Todos os argumentos a seguir são os mesmos argumentos disponibilizados para as funções que você adiciona a esse gancho. apply_filters () deve ter pelo menos um argumento adicional (o argumento sendo filtrado), mas todos os outros são opcionais.

Por exemplo, se você deseja injetar um script de análise logo antes de sua tag de corpo de abertura, mas não deseja transformar header.php em uma bagunça:



<? php do_action ('before_body_tag'); ?;>

</head>

<body>

Em seguida, você pode adicionar quantos scripts precisar:



add_action ('before_body_tag', 'add_analytics_custom');

function add_analytics_custom () {

// tags <script> e código analítico vão aqui

}

apply_filters () funciona de maneira um pouco diferente. Conforme discutido acima, os filtros são usados ​​para modificar os valores. Como os filtros retornam um valor, você atribui sua chamada apply_filters () a uma variável:



<? php $ text = apply_filters ('call_to_action_text', 'Sobre nós'); ?>

<a href = ”<? php echo get_permalink ('sobre'); ?> ”Classe =” botão cta ”>

<? php echo $ text; ?>

</a>


// Alternativamente, você pode ecoar o resultado de apply_filters () diretamente

<a href = ”<? php echo get_permalink ('sobre'); ?> ”Classe =” botão cta ”>

<? php echo apply_filters ('call_to_action_text', 'Sobre nós'); ?>

</a>

Em seguida, você pode modificar a variável filtrada conforme necessário:



add_filter ('call_to_action_text', 'change_call_to_action_text');

function change_call_to_action_text ($ text) {

if (is_front_page ()) {

$ text = 'Descubra mais';

}


return $ text;

}

As desvantagens

Nenhum sistema é perfeito e os ganchos não são exceção. Quando se trata de ganchos de núcleo, geralmente você tem que se contentar com o que lhe é dado. Muito ocasionalmente, você encontrará situações em que um anzol não é o lugar mais conveniente para você. Não há muito o que fazer quando isso acontece, então veja isso como uma oportunidade para encontrar uma solução criativa!

Além disso, como os ganchos podem existir em qualquer lugar dentro da estrutura de diretório do WP, às vezes é difícil descobrir onde certa lógica está acontecendo. Isso pode ser compensado separando seus ganchos de função em seus próprios arquivos.

Conselhos adicionais

  • Ao criar funções para ganchos, certifique-se de que o nome seja exclusivo, caso contrário, ocorrerá um conflito. O mesmo vale para os nomes de gancho e filtro personalizados!
  • Use ganchos para manter seus modelos organizados. Alguns ganchos do_action () genéricos inseridos em seus modelos podem ajudar a manter a lógica longe da marcação (quase sempre uma boa ideia).
  • Ao instalar um novo plug-in, verifique quais ganchos ele oferece e pense em como você pode utilizá-los. Isso é especialmente útil nos momentos inevitáveis ​​em que um plugin não faz exatamente o que você deseja.
  • Ao adicionar uma ação ou filtro, você pode substituir o nome da função pela própria função. Isso pode ajudar a manter as ações e os filtros independentes. Funções adicionadas desta forma não pode ser removido usando remove_action () ou remove_filter (), por isso tome cuidado!


add_action ('where_to_do_the_thing', function () {

echo 'A coisa está feita.';

}, 10, 1);
  • Verifique as outras funções relacionadas a ganchos disponíveis, como did_action () ou has_action () . Você nunca sabe quando apenas estar ciente deles será útil.

Resumo

Usar ganchos é uma questão de hábito. Tente se fazer duas perguntas simples sempre que trabalhar em seu projeto WP:

  1. “Existe um gancho que tornará isso mais fácil para mim?”
  2. “Posso adicionar um gancho que tornará isso mais fácil para mim no futuro?”

Depois de abordar o desenvolvimento de WP com essa atitude, você encontrará muitas portas se abrindo.

Os exemplos neste guia são a ponta do iceberg. Existem centenas de ganchos apenas no núcleo do WP, para não falar da enorme biblioteca de plug-ins e temas. Dê uma olhada na referência de ação WP e referência de filtro para a lista completa de ganchos WP principais.

Se precisar de ajuda com seu Desenvolvimento Web, não hesite em nos contatar.