Já foi dito que a solução para o seu problema é que você precisa "ligar" algo para fazer sua coisa ou usar add_filtersem realmente entender por que isso bagunça as coisas? Os ganchos são a base do WordPress e fornecem temas e plugins uma maneira de interagir ou Neste post vamos detalhar o que são hooks, como eles funcionam e como podemos usá-los.
O que são ganchos?
À medida que o WordPress percorre seu código (desde o início de carregar classes, carregar plugins, carregar o tema, fazer a consulta para a solicitação atual e, finalmente, renderizar o HTML), ele passa por vários “pontos de verificação"; ganchos. Quando um gancho é encontrado, o WordPress irá parar o que está fazendo – e verificar se há alguma função (no tema, plugin ou no próprio WordPress) que está registrada para ser executada neste gancho. Se houver, o WordPress executará todas essas funções e continuará de onde parou.
Isso torna possível para plugins, temas e o próprio WordPress “ligar” certos pontos para adicionar, por exemplo, folhas de estilo na <head>tag do tema, modificar como o WordPress consulta as postagens ou simplesmente alterar o conteúdo da postagem, se desejar.
Existem dois tipos de ganchos; ações e filtros. Eles funcionam de maneira bastante semelhante entre si, mas com uma exceção que veremos mais detalhadamente abaixo.
Ações e filtros
Para se conectar a uma ação ou filtro, você precisa definir qual gancho (pelo seu nome) deseja usar e definir um retorno de chamada – que é o nome da função que deseja executar. Na maioria dos casos, os ganchos fornecem parâmetros ou variáveis relevantes para o gancho.
As ações são simplesmente “pontos de verificação” na execução do WordPress, onde você pode executar uma tarefa ou ecoar algo. Em alguns casos raros, você pode modificar um objeto (fornecido em parâmetros), para que todas as execuções seguintes funcionem com esse objeto alterado.
Os filtros são para alterar uma variável ou saída. Todos os hooks de filtro fornecerão a variável que você pode alterar como primeiro parâmetro e permitirão que você a modifique ou retorne algo diferente.
O WordPress executa muitos ganchos, mas você pode criar o seu próprio em seu plugin ou tema. Isso permite que os desenvolvedores estendam e modifiquem seu código; por exemplo, modificar um plugin por meio de um tema ou modificar o tema pai por meio do tema filho.
Muitas funções do WordPress, normalmente usadas para imprimir posts, também são filtros ou ações. Por exemplo, a função the_title()imprime o título do post, mas também é um filtro.
Vamos ver como nos ligamos a isso na prática.
Conectando-se a ações
Para se conectar a uma ação, você usa o método add_action(). No mínimo, requer dois parâmetros; o nome do gancho e o retorno de chamada; o nome da função que você deseja executar. Opcionalmente, você pode fornecer prioridade como terceiro parâmetro e definir o número de argumentos que serão passados para sua função de retorno de chamada. Veremos os dois parâmetros opcionais mais tarde, mas por enquanto, aqui está um exemplo de add_action:
add_action('init', 'my_function_name');
function my_function_name() {
// Do your stuff
}O primeiro parâmetro add_actioné o nome da ação; neste caso init, que é um gancho WordPress bastante comum que acontece durante a inicialização. O segundo parâmetro é seu retorno de chamada, neste caso o nome da função que desejamos executar. Então tudo que você precisa fazer é definir uma função com esse nome e adicionar seu código dentro dela.
Você também pode usar funções anônimas que são onde você define a função dentro add_actionem vez de fornecer um nome de função, assim;
add_action('init', function() {
// Do your stuff
});Muitos desenvolvedores preferem esse método, pois isso evita o risco de redefinir uma função PHP com o mesmo nome.
Se você precisar executar uma função definida dentro de uma classe PHP, precisará fornecer um array como parâmetro de retorno de chamada; onde o primeiro elemento é o objeto de classe e o segundo elemento é o nome da função:
class MyClass {
public function __construct() {
add_action('init', [$this, 'myFunctionName']);
}
public function myFunctionName() {
// Do your stuff
}
}Encaixando em filtros
Para se conectar a um filtro, você usa a função add_filter(). Da mesma forma que as ações acima, o primeiro parâmetro é o nome do filtro e o segundo é seu retorno de chamada. Opcionalmente, você pode fornecer prioridade como terceiro parâmetro e o número de argumentos como quarto. Aqui está um exemplo de add_filter:
add_filter('the_title', 'my_function_name');
function my_function_name($title) {
// Do your stuff
return $title;
}No exemplo acima, nos conectamos ao filtro the_title(que imprime o título do post) e informamos ao WordPress para executar nossa função. Todos os filtros sempre fornecerão um argumento; a variável a ser alterada. Na minha função dei o nome $titleporque sei que contém o título do post. Dentro da função eu posso modificá-la ou substituir completamente a variável. É importante lembrar que nos filtros você sempre precisa retornar a variável. Se você não retornar algo em sua função de retorno de chamada, a variável será esvaziada. Se eu pular a instrução de retorno no exemplo acima, nenhum título de postagem ecoaria em qualquer lugar.
O argumento variável e a regra de retornar algo em sua função de retorno de chamada é praticamente a única diferença entre filtros e ações. Todo o resto funciona igual. Você pode seguir os exemplos de funções e classes anônimas mostradas para ações acima para filtros, bem como os parâmetros opcionais prioridade e número de argumentos; que veremos a seguir.
Prioridade
O terceiro parâmetro (opcional) para add_actione add_filteré um inteiro que define a prioridade de sua função de retorno de chamada. Isso é útil nos casos em que existem várias funções (não necessariamente de você em seu tema ou plugin, lembre-se que o próprio WordPress usa seus próprios ganchos), e você precisa decidir qual executar primeiro.
Se nenhuma prioridade for fornecida, o padrão será 10. Quanto menor a prioridade, mais cedo ela é executada e quanto maior a prioridade, mais tarde ela é executada. Você não pode fornecer uma prioridade negativa.
Imagine várias funções de retorno de chamada registradas em init. Se nenhuma prioridade for fornecida para vários retornos de chamada, o WordPress os executará na ordem em que foram encontrados (por exemplo, em functions.phpou no código do seu plug-in).
add_action('init', 'my_function_name');
add_action('init', 'my_second_function_name');
add_action('init', 'my_third_function_name', 12);
add_action('init', 'my_fourth_function_name', 1);Esta seria a ordem em que o WordPress executará os retornos de chamada acima:
my_fourth_function_name(prioridade 1)my_function_name(prioridade 10)my_second_function_name(prioridade 10, mas aparece mais tarde no código)my_third_function_name(prioridade 12)
Número de argumentos
Normalmente, os ganchos fornecem alguns dados adicionais que são relevantes e úteis para as funções de retorno de chamada. Por exemplo, a ação save_post(executada sempre que uma postagem é atualizada) fornece dois argumentos possíveis; o ID da postagem e o objeto da postagem. Eles são úteis para operações que você normalmente precisa executar neste gancho (por exemplo, se você deseja salvar uma meta de postagem, precisa do ID da postagem).
Se nenhum número de argumentos foi fornecido para uma ação ou filtro, o padrão é 1. É por isso que você não precisa definir 1 on add_filterpara acessar a variável na qual o filtro está conectado. As ações, no entanto, não podem passar argumentos, mesmo que o número de argumentos seja definido como 1 como padrão.
Vejamos um exemplo de definição do número de argumentos e como os acessamos em nossa função de retorno de chamada:
add_action('save_post', 'my_function_name', 10, 2);
function my_function_name($post_id, $post) {
// Do your stuff
}No exemplo acima, dizemos ao WordPress para passar dois argumentos para nossa função de retorno de chamada. Lembre-se que precisamos definir a prioridade como terceiro parâmetro, então geralmente definimos o padrão, que é 10. Quanto à nossa função de retorno de chamada, agora podemos definir os mesmos argumentos de número que pedimos, no exemplo acima era 2.
Se tivéssemos no exemplo acima definido o número de argumentos como 1, apenas o primeiro argumento em nossa função de retorno de chamada seria preenchido. O segundo, $post, seria indefinido.
E se precisarmos de dados que não foram passados no gancho?
Cabe inteiramente ao desenvolvedor que criou o gancho definir quais argumentos podem ser passados. Isso significa que você não pode simplesmente forçar os argumentos que deseja ou precisa em seu add_actionou add_filter. Felizmente, na maioria dos casos, temos alternativas para obter as variáveis que precisamos. Se você estiver se conectando a uma ação ou filtro onde sabe que certas variáveis globais devem ser definidas, você pode acessar essas variáveis globais em sua função de retorno de chamada. Além disso, o WordPress tem toda uma gama de tags condicionais que você pode usar em suas funções de hooked (com exceção dos hooks muito antigos que ocorrem antes que o WordPress defina essas tags condicionais)
Vejamos um exemplo de acesso a variáveis globais. O filtro the_titlefornece o ID do post como argumento opcional, que podemos acessar definindo-o como argumento aceitável;
add_filter('the_title', 'my_function_name', 10, 2);
function my_function_name($title, $post_id) {
if ($post_id == 1) {
return 'First post ever!';
}
return $title;
}No entanto, podemos alcançar o mesmo resultado por;
Se você sabe que uma variável global é definida pelo ponto em que o gancho é executado, você pode defini-las como globais em sua função de retorno de chamada e acessar os dados de lá. Por exemplo, definir global $wp_queryno exemplo acima também lhe daria acesso ao objeto wp_query completo dentro de seu retorno de chamada de função.
As tags condicionais do WordPress são extremamente úteis. A menos que você esteja preso a um gancho que ocorre muito cedo na execução do WordPress, eles estão disponíveis. Existem tags condicionais para verificar em qual página (template) você está, se você está dentro de um menu ou de um post loop e muito mais. Por exemplo, ao modificar a consulta post usando o gancho pre_get_posts, é muito útil garantir que seu código seja executado apenas em determinados casos. Por exemplo;
add_action('pre_get_posts', 'my_function_name');
function my_function_name($query) {
if (!is_admin()) {
// Do your stuff
}
}Como o gancho pre_get_postsé executado tanto no admin quanto no frontend, podemos usar uma tag condicional para garantir que nosso código afete apenas a consulta do frontend.
Criando seus próprios ganchos
Você pode definir suas próprias ações e filtros. Se você é um desenvolvedor de temas ou plugins, é encorajado a fazê-lo, para permitir que outras pessoas modifiquem seu código sem alterar o código-fonte.
Registre uma ação com do_action()e registre um filtro com apply_filters().
O do_action()requer um mínimo de 1 parâmetro; o nome do gancho. Tenha em mente que o nome do gancho deve ser único (não o chame, por exemplo, initpois este é um gancho central do WordPress). Coloque o do_action()onde você quer que o gancho apareça. Por exemplo, você pode colocar o gancho no seu tema header.php, logo após o corpo, para definir um gancho onde os desenvolvedores possam gerar scripts ou outro conteúdo.
Você pode adicionar quantos parâmetros do_actionquiser após o nome do gancho. Tente ter em mente o que os desenvolvedores de dados precisariam em seus ganchos, que não são facilmente acessíveis de outra forma.
O apply_filters()requer um mínimo de 2 parâmetros; o nome do gancho e a variável na qual você está registrando o filtro. Por exemplo, seu tema pode registrar um filtro em torno de algumas classes HTML para permitir que os desenvolvedores modifiquem ou adicionem a elas:
Assim como nas ações, você pode adicionar quantos parâmetros apply_filtersdesejar após os dois parâmetros obrigatórios.
Conclusão e recursos úteis
Com isso, espero que você tenha alcançado um sólido entendimento de como o WordPress executa a maior parte de seu código, como você pode modificar o código e como você, como desenvolvedor, pode permitir que outros desenvolvedores também façam modificações em seu código.