{"id":233532,"date":"2023-02-15T19:46:00","date_gmt":"2023-02-15T16:46:00","guid":{"rendered":"https:\/\/wordpress.mediadoma.com\/?p=233532"},"modified":"2022-11-11T00:12:01","modified_gmt":"2022-11-10T21:12:01","slug":"guia-tudo-sobre-hooks-no-wordpress","status":"publish","type":"post","link":"https:\/\/wordpress.mediadoma.com\/pt-pt\/guia-tudo-sobre-hooks-no-wordpress\/","title":{"rendered":"Guia: Tudo sobre Hooks no WordPress"},"content":{"rendered":"\n

J\u00e1 foi dito que a solu\u00e7\u00e3o para o seu problema \u00e9 que voc\u00ea precisa "ligar" algo para fazer sua coisa ou usar add_filter<\/code>sem realmente entender por que isso bagun\u00e7a as coisas? Os ganchos s\u00e3o a base do WordPress e fornecem temas e plugins uma maneira de interagir ou Neste post vamos detalhar o que s\u00e3o hooks, como eles funcionam e como podemos us\u00e1-los.<\/p>\n

O que s\u00e3o ganchos?<\/h2>\n

\u00c0 medida que o WordPress percorre seu c\u00f3digo (desde o in\u00edcio de carregar classes, carregar plugins, carregar o tema, fazer a consulta para a solicita\u00e7\u00e3o atual e, finalmente, renderizar o HTML), ele passa por v\u00e1rios “pontos de verifica\u00e7\u00e3o"; ganchos. Quando um gancho \u00e9 encontrado, o WordPress ir\u00e1 parar o que est\u00e1 fazendo \u2013 e verificar se h\u00e1 alguma fun\u00e7\u00e3o (no tema, plugin ou no pr\u00f3prio WordPress) que est\u00e1 registrada para ser executada neste gancho. Se houver, o WordPress executar\u00e1 todas essas fun\u00e7\u00f5es e continuar\u00e1 de onde parou.<\/p>\n

Isso torna poss\u00edvel para plugins, temas e o pr\u00f3prio WordPress “ligar” certos pontos para adicionar, por exemplo, folhas de estilo na <head><\/code>tag do tema, modificar como o WordPress consulta as postagens ou simplesmente alterar o conte\u00fado da postagem, se desejar.<\/p>\n

Existem dois tipos de ganchos; a\u00e7\u00f5es e filtros. Eles funcionam de maneira bastante semelhante entre si, mas com uma exce\u00e7\u00e3o que veremos mais detalhadamente abaixo.<\/p>\n

A\u00e7\u00f5es e filtros<\/h2>\n

Para se conectar a uma a\u00e7\u00e3o ou filtro, voc\u00ea precisa definir qual gancho (pelo seu nome) deseja usar e definir um retorno de chamada \u2013 que \u00e9 o nome da fun\u00e7\u00e3o que deseja executar. Na maioria dos casos, os ganchos fornecem par\u00e2metros ou vari\u00e1veis \u200b\u200brelevantes para o gancho.<\/p>\n

As a\u00e7\u00f5es s\u00e3o simplesmente “pontos de verifica\u00e7\u00e3o” na execu\u00e7\u00e3o do WordPress, onde voc\u00ea pode executar uma tarefa ou ecoar algo. Em alguns casos raros, voc\u00ea pode modificar um objeto (fornecido em par\u00e2metros), para que todas as execu\u00e7\u00f5es seguintes funcionem com esse objeto alterado.<\/p>\n

Os filtros s\u00e3o para alterar uma vari\u00e1vel ou sa\u00edda. Todos os hooks de filtro fornecer\u00e3o a vari\u00e1vel que voc\u00ea pode alterar como primeiro par\u00e2metro e permitir\u00e3o que voc\u00ea a modifique ou retorne algo diferente.<\/p>\n

O WordPress executa muitos ganchos, mas voc\u00ea pode criar o seu pr\u00f3prio em seu plugin ou tema. Isso permite que os desenvolvedores estendam e modifiquem seu c\u00f3digo; por exemplo, modificar um plugin por meio de um tema ou modificar o tema pai por meio do tema filho.<\/p>\n

Muitas fun\u00e7\u00f5es do WordPress, normalmente usadas para imprimir posts, tamb\u00e9m s\u00e3o filtros ou a\u00e7\u00f5es. Por exemplo, a fun\u00e7\u00e3o the_title()<\/code>imprime o t\u00edtulo do post, mas tamb\u00e9m \u00e9 um filtro.<\/p>\n

Vamos ver como nos ligamos a isso na pr\u00e1tica.<\/p>\n

Conectando-se a a\u00e7\u00f5es<\/h2>\n

Para se conectar a uma a\u00e7\u00e3o, voc\u00ea usa o m\u00e9todo add_action()<\/code>. No m\u00ednimo, requer dois par\u00e2metros; o nome do gancho e o retorno de chamada; o nome da fun\u00e7\u00e3o que voc\u00ea deseja executar. Opcionalmente, voc\u00ea pode fornecer prioridade como terceiro par\u00e2metro e definir o n\u00famero de argumentos que ser\u00e3o passados \u200b\u200bpara sua fun\u00e7\u00e3o de retorno de chamada. Veremos os dois par\u00e2metros opcionais mais tarde, mas por enquanto, aqui est\u00e1 um exemplo de add_action<\/code>:<\/p>\n

add_action('init', 'my_function_name');\nfunction my_function_name() {\n    \/\/ Do your stuff\n}<\/code><\/pre>\n
O primeiro par\u00e2metro add_action<\/code>\u00e9 o nome da a\u00e7\u00e3o; neste caso init<\/code>, que \u00e9 um gancho WordPress bastante comum que acontece durante a inicializa\u00e7\u00e3o. O segundo par\u00e2metro \u00e9 seu retorno de chamada, neste caso o nome da fun\u00e7\u00e3o que desejamos executar. Ent\u00e3o tudo que voc\u00ea precisa fazer \u00e9 definir uma fun\u00e7\u00e3o com esse nome e adicionar seu c\u00f3digo dentro dela.<\/p>\n
Voc\u00ea tamb\u00e9m pode usar fun\u00e7\u00f5es an\u00f4nimas que s\u00e3o onde voc\u00ea define a fun\u00e7\u00e3o dentro add_action<\/code>em vez de fornecer um nome de fun\u00e7\u00e3o, assim;<\/p>\n
add_action('init', function() {\n    \/\/ Do your stuff\n});<\/code><\/pre>\n
Muitos desenvolvedores preferem esse m\u00e9todo, pois isso evita o risco de redefinir uma fun\u00e7\u00e3o PHP com o mesmo nome.<\/p>\n
Se voc\u00ea precisar executar uma fun\u00e7\u00e3o definida dentro de uma classe PHP, precisar\u00e1 fornecer um array como par\u00e2metro de retorno de chamada; onde o primeiro elemento \u00e9 o objeto de classe e o segundo elemento \u00e9 o nome da fun\u00e7\u00e3o:<\/p>\n
class MyClass {\n    public function __construct() {\n        add_action('init', [$this, 'myFunctionName']);\n    }\n\u00a0\n    public function myFunctionName() {\n        \/\/ Do your stuff\n    }\n}<\/code><\/pre>\n
Encaixando em filtros<\/h2>\n
Para se conectar a um filtro, voc\u00ea usa a fun\u00e7\u00e3o add_filter()<\/code>. Da mesma forma que as a\u00e7\u00f5es acima, o primeiro par\u00e2metro \u00e9 o nome do filtro e o segundo \u00e9 seu retorno de chamada. Opcionalmente, voc\u00ea pode fornecer prioridade como terceiro par\u00e2metro e o n\u00famero de argumentos como quarto. Aqui est\u00e1 um exemplo de add_filter<\/code>:<\/p>\n
add_filter('the_title', 'my_function_name');\nfunction my_function_name($title) {\n    \/\/ Do your stuff\n    return $title;\n}<\/code><\/pre>\n
No exemplo acima, nos conectamos ao filtro the_title<\/code>(que imprime o t\u00edtulo do post) e informamos ao WordPress para executar nossa fun\u00e7\u00e3o. Todos os filtros sempre fornecer\u00e3o um argumento; a vari\u00e1vel a ser alterada. Na minha fun\u00e7\u00e3o dei o nome $title<\/code>porque sei que cont\u00e9m o t\u00edtulo do post. Dentro da fun\u00e7\u00e3o eu posso modific\u00e1-la ou substituir completamente a vari\u00e1vel. \u00c9 importante lembrar que nos filtros voc\u00ea sempre precisa retornar a vari\u00e1vel<\/strong>. Se voc\u00ea n\u00e3o retornar algo em sua fun\u00e7\u00e3o de retorno de chamada, a vari\u00e1vel ser\u00e1 esvaziada. Se eu pular a instru\u00e7\u00e3o de retorno no exemplo acima, nenhum t\u00edtulo de postagem ecoaria em qualquer lugar.<\/p>\n
O argumento vari\u00e1vel e a regra de retornar algo em sua fun\u00e7\u00e3o de retorno de chamada \u00e9 praticamente a \u00fanica diferen\u00e7a entre filtros e a\u00e7\u00f5es. Todo o resto funciona igual. Voc\u00ea pode seguir os exemplos de fun\u00e7\u00f5es e classes an\u00f4nimas mostradas para a\u00e7\u00f5es acima para filtros, bem como os par\u00e2metros opcionais prioridade e n\u00famero de argumentos; que veremos a seguir.<\/p>\n
Prioridade<\/h2>\n
O terceiro par\u00e2metro (opcional) para add_action<\/code>e add_filter<\/code>\u00e9 um inteiro que define a prioridade de sua fun\u00e7\u00e3o de retorno de chamada. Isso \u00e9 \u00fatil nos casos em que existem v\u00e1rias fun\u00e7\u00f5es (n\u00e3o necessariamente de voc\u00ea em seu tema ou plugin, lembre-se que o pr\u00f3prio WordPress usa seus pr\u00f3prios ganchos), e voc\u00ea precisa decidir qual executar primeiro.<\/p>\n
Se nenhuma prioridade for fornecida, o padr\u00e3o ser\u00e1 10. Quanto menor a prioridade, mais cedo ela \u00e9 executada e quanto maior a prioridade, mais tarde ela \u00e9 executada. Voc\u00ea n\u00e3o pode fornecer uma prioridade negativa.<\/p>\n
Imagine v\u00e1rias fun\u00e7\u00f5es de retorno de chamada registradas em init<\/code>. Se nenhuma prioridade for fornecida para v\u00e1rios retornos de chamada, o WordPress os executar\u00e1 na ordem em que foram encontrados (por exemplo, em functions.php<\/code>ou no c\u00f3digo do seu plug-in).<\/p>\n
add_action('init', 'my_function_name');\nadd_action('init', 'my_second_function_name');\nadd_action('init', 'my_third_function_name', 12);\nadd_action('init', 'my_fourth_function_name', 1);<\/code><\/pre>\n
Esta seria a ordem em que o WordPress executar\u00e1 os retornos de chamada acima:<\/p>\n
    \n
  1. my_fourth_function_name<\/code>(prioridade 1)<\/li>\n
  2. my_function_name<\/code>(prioridade 10)<\/li>\n
  3. my_second_function_name<\/code>(prioridade 10, mas aparece mais tarde no c\u00f3digo)<\/li>\n
  4. my_third_function_name<\/code>(prioridade 12)<\/li>\n<\/ol>\n
    N\u00famero de argumentos<\/h2>\n
    Normalmente, os ganchos fornecem alguns dados adicionais que s\u00e3o relevantes e \u00fateis para as fun\u00e7\u00f5es de retorno de chamada. Por exemplo, a a\u00e7\u00e3o save_post<\/code>(executada sempre que uma postagem \u00e9 atualizada) fornece dois argumentos poss\u00edveis; o ID da postagem e o objeto da postagem. Eles s\u00e3o \u00fateis para opera\u00e7\u00f5es que voc\u00ea normalmente precisa executar neste gancho (por exemplo, se voc\u00ea deseja salvar uma meta de postagem, precisa do ID da postagem).<\/p>\n
    Se nenhum n\u00famero de argumentos foi fornecido para uma a\u00e7\u00e3o ou filtro, o padr\u00e3o \u00e9 1. \u00c9 por isso que voc\u00ea n\u00e3o precisa definir 1 on add_filter<\/code>para acessar a vari\u00e1vel na qual o filtro est\u00e1 conectado. As a\u00e7\u00f5es, no entanto, n\u00e3o podem passar argumentos, mesmo que o n\u00famero de argumentos seja definido como 1 como padr\u00e3o.<\/p>\n
    Vejamos um exemplo de defini\u00e7\u00e3o do n\u00famero de argumentos e como os acessamos em nossa fun\u00e7\u00e3o de retorno de chamada:<\/p>\n
    add_action('save_post', 'my_function_name', 10, 2);\nfunction my_function_name($post_id, $post) {\n    \/\/ Do your stuff\n}<\/code><\/pre>\n
    No exemplo acima, dizemos ao WordPress para passar dois argumentos para nossa fun\u00e7\u00e3o de retorno de chamada. Lembre-se que precisamos definir a prioridade como terceiro par\u00e2metro, ent\u00e3o geralmente definimos o padr\u00e3o, que \u00e9 10. Quanto \u00e0 nossa fun\u00e7\u00e3o de retorno de chamada, agora podemos definir os mesmos argumentos de n\u00famero que pedimos, no exemplo acima era 2.<\/p>\n
    Se tiv\u00e9ssemos no exemplo acima definido o n\u00famero de argumentos como 1, apenas o primeiro argumento em nossa fun\u00e7\u00e3o de retorno de chamada seria preenchido. O segundo, $post<\/code>, seria indefinido.<\/p>\n
    E se precisarmos de dados que n\u00e3o foram passados \u200b\u200bno gancho?<\/h2>\n
    Cabe inteiramente ao desenvolvedor que criou o gancho definir quais argumentos podem ser passados. Isso significa que voc\u00ea n\u00e3o pode simplesmente for\u00e7ar os argumentos que deseja ou precisa em seu add_action<\/code>ou add_filter<\/code>. Felizmente, na maioria dos casos, temos alternativas para obter as vari\u00e1veis \u200b\u200bque precisamos. Se voc\u00ea estiver se conectando a uma a\u00e7\u00e3o ou filtro onde sabe que certas vari\u00e1veis \u200b\u200bglobais devem ser definidas, voc\u00ea pode acessar essas vari\u00e1veis \u200b\u200bglobais em sua fun\u00e7\u00e3o de retorno de chamada. Al\u00e9m disso, o WordPress tem toda uma gama de tags condicionais<\/a> que voc\u00ea pode usar em suas fun\u00e7\u00f5es de hooked (com exce\u00e7\u00e3o dos hooks muito antigos que ocorrem antes que o WordPress defina essas tags condicionais)<\/p>\n
    Vejamos um exemplo de acesso a vari\u00e1veis \u200b\u200bglobais. O filtro the_title<\/code>fornece o ID do post como argumento opcional, que podemos acessar definindo-o como argumento aceit\u00e1vel;<\/p>\n
    add_filter('the_title', 'my_function_name', 10, 2);\nfunction my_function_name($title, $post_id) {\n    if ($post_id == 1) {\n        return 'First post ever!';\n    }\n    return $title;\n}<\/code><\/pre>\n
    No entanto, podemos alcan\u00e7ar o mesmo resultado por;<\/p>\n
    add_filter('the_title', 'my_function_name');\nfunction my_function_name($title) {\n    global $post;\n    if ($post->ID == 1) {\n        return 'First post ever!';\n    }\n    return $title;\n}<\/code><\/pre>\n
    Se voc\u00ea sabe que uma vari\u00e1vel global \u00e9 definida pelo ponto em que o gancho \u00e9 executado, voc\u00ea pode defini-las como globais em sua fun\u00e7\u00e3o de retorno de chamada e acessar os dados de l\u00e1. Por exemplo, definir global $wp_query<\/code>no exemplo acima tamb\u00e9m lhe daria acesso ao objeto wp_query completo dentro de seu retorno de chamada de fun\u00e7\u00e3o.<\/p>\n
    As tags condicionais do WordPress<\/a> s\u00e3o extremamente \u00fateis. A menos que voc\u00ea esteja preso a um gancho que ocorre muito cedo na execu\u00e7\u00e3o do WordPress, eles est\u00e3o dispon\u00edveis. Existem tags condicionais para verificar em qual p\u00e1gina (template) voc\u00ea est\u00e1, se voc\u00ea est\u00e1 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<\/code>, \u00e9 muito \u00fatil garantir que seu c\u00f3digo seja executado apenas em determinados casos. Por exemplo;<\/p>\n
    add_action('pre_get_posts', 'my_function_name');\nfunction my_function_name($query) {\n    if (!is_admin()) {\n        \/\/ Do your stuff\n    }\n}<\/code><\/pre>\n
    Como o gancho pre_get_posts<\/code>\u00e9 executado tanto no admin quanto no frontend, podemos usar uma tag condicional para garantir que nosso c\u00f3digo afete apenas a consulta do frontend.<\/p>\n
    Criando seus pr\u00f3prios ganchos<\/h2>\n
    Voc\u00ea pode definir suas pr\u00f3prias a\u00e7\u00f5es e filtros. Se voc\u00ea \u00e9 um desenvolvedor de temas ou plugins, \u00e9 encorajado a faz\u00ea-lo, para permitir que outras pessoas modifiquem seu c\u00f3digo sem alterar o c\u00f3digo-fonte.<\/p>\n
    Registre uma a\u00e7\u00e3o com do_action()<\/code>e registre um filtro com apply_filters()<\/code>.<\/p>\n
    O do_action()<\/code>requer um m\u00ednimo de 1 par\u00e2metro; o nome do gancho. Tenha em mente que o nome do gancho deve ser \u00fanico (n\u00e3o o chame, por exemplo, init<\/code>pois este \u00e9 um gancho central do WordPress). Coloque o do_action()<\/code>onde voc\u00ea quer que o gancho apare\u00e7a. Por exemplo, voc\u00ea pode colocar o gancho no seu tema header.php<\/code>, logo ap\u00f3s o corpo, para definir um gancho onde os desenvolvedores possam gerar scripts ou outro conte\u00fado.<\/p>\n
    ...\n<body>\n    <?php do_action('mytheme_after_body'); ?><\/code><\/pre>\n
    Voc\u00ea pode adicionar quantos par\u00e2metros do_action<\/code>quiser ap\u00f3s o nome do gancho. Tente ter em mente o que os desenvolvedores de dados precisariam em seus ganchos, que n\u00e3o s\u00e3o facilmente acess\u00edveis de outra forma.<\/p>\n
    O apply_filters()<\/code>requer um m\u00ednimo de 2 par\u00e2metros; o nome do gancho e a vari\u00e1vel na qual voc\u00ea est\u00e1 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:<\/p>\n
    <section class=\"<?php echo apply_filters('mytheme_section_classes', 'section default-class'); ?>\">\n    ...\n<\/section><\/code><\/pre>\n
    Assim como nas a\u00e7\u00f5es, voc\u00ea pode adicionar quantos par\u00e2metros apply_filters<\/code>desejar ap\u00f3s os dois par\u00e2metros obrigat\u00f3rios.<\/p>\n
    Conclus\u00e3o e recursos \u00fateis<\/h2>\n
    Com isso, espero que voc\u00ea tenha alcan\u00e7ado um s\u00f3lido entendimento de como o WordPress executa a maior parte de seu c\u00f3digo, como voc\u00ea pode modificar o c\u00f3digo e como voc\u00ea, como desenvolvedor, pode permitir que outros desenvolvedores tamb\u00e9m fa\u00e7am modifica\u00e7\u00f5es em seu c\u00f3digo.<\/p>\n