Aproveite o poder dos ganchos do WordPress: Ações e filtros explicados

Como qualquer CMS, o WordPress nem sempre atende a todas as suas necessidades imediatamente. Como é de código aberto, você pode hackeá-lo para adequá-lo às suas necessidades de negócios, mas, em vez disso, você pode usar os ganchos do WordPress para atingir seus objetivos. Construir com ganchos é uma estratégia vencedora que libera os desenvolvedores do WordPress para criar praticamente qualquer recurso de site imaginável.

Ganchos do WordPress: Ações e Filtros

Os ganchos do WordPress não são apenas ferramentas de personalização poderosas, são como os componentes do WordPress interagem uns com os outros. As funções de hooked gerenciam muitas das tarefas de rotina que consideramos parte integrante do WordPress, como adicionar estilos ou scripts a uma página ou envolver o texto do rodapé com elementos HTML. Uma pesquisa na base de código do WordPress Core revela milhares de ganchos em mais de 700 locais. Temas e plugins do WordPress contêm ainda mais ganchos.

Antes de entrarmos nos ganchos e explorarmos a diferença entre ganchos de ação e ganchos de filtro, vamos entender onde eles se encaixam na arquitetura do WordPress.

Infraestrutura WordPress

Os elementos modulares do WordPress se integram prontamente uns aos outros, para que possamos facilmente misturar, combinar e combinar:

1. WordPress Core: Estes são os arquivos necessários para o WordPress funcionar. O WordPress Core fornece arquitetura generalizada, painel WP Admin, consultas de banco de dados, segurança e muito mais. O WordPress Core é escrito em PHP e usa um banco de dados MySQL.
2. Tema (ou Tema Pai): Um tema define o layout básico e o design de um site. Alimentado por arquivos PHP, HTML, JavaScript e CSS, um tema funciona lendo o banco de dados MySQL do WordPress para gerar o código HTML que é renderizado em um navegador. Ganchos em um tema podem adicionar folhas de estilo, scripts, fontes ou tipos de postagem personalizados, por exemplo.
3. Tema filho: nós mesmos criamos temas filho para ajustar o layout básico e o design que os temas pai fornecem. Os temas filhos podem definir folhas de estilo e scripts para modificar recursos herdados ou adicionar ou remover tipos de postagem. As instruções do tema filho sempre substituem as do tema pai.
4. Plugin(es): Para estender a funcionalidade de back-end do WordPress, podemos escolher entre milhares de plugins de terceiros. Hooks em um plug-in podem, por exemplo, nos notificar por e-mail quando uma postagem for publicada ou ocultar comentários enviados por usuários que contenham linguagem proibida.
5. Plugin(es) personalizado(s): Quando um plug-in de terceiros não atende totalmente às necessidades de negócios, podemos turbina-lo escrevendo um plug-in personalizado em PHP. Ou podemos escrever um novo plugin do zero. Em ambos os casos, adicionaríamos gancho(s) para estender a funcionalidade existente.

Dado que temos acesso à fonte de todas as cinco camadas, por que os ganchos são necessários no WordPress?

Segurança do código

Para acompanhar as tecnologias em evolução, os colaboradores do WordPress Core, temas pai e plugins frequentemente lançam atualizações para mitigar vulnerabilidades de segurança, corrigir bugs, resolver incompatibilidades ou oferecer novos recursos. Como qualquer consultor com experiência em emergências sabe em primeira mão, a falha em manter os componentes do WordPress atualizados pode comprometer ou até mesmo desabilitar um site.

Se modificarmos diretamente as cópias locais dos componentes upstream do WordPress, encontraremos um problema: as atualizações substituem nossas personalizações. Como podemos contornar isso ao personalizar o WordPress? Por meio de ganchos, no tema filho e no(s) plugin(s) personalizado(s).

Codificação em nosso tema filho

Um tema filho é um espaço seguro onde podemos personalizar a aparência do nosso tema instalado. Qualquer código adicionado aqui substituirá o código comparável no pai sem o risco de ser substituído por uma atualização.

Quando um tema filho é ativado, ele se vincula a um pai desativado, herdando e exibindo as características do pai enquanto permanece inalterado pelas atualizações do pai. Para não cair na tentação de modificar um tema, as melhores práticas sugerem que um tema filho seja ativado como parte de nossa configuração.

Escrevendo plugin(s) personalizado(s)

Quando um plugin é ativado, seu arquivo functions.php é executado com cada chamada no servidor. O WordPress, por sua vez, carrega e classifica hooks de todos os plugins ativos de acordo com sua prioridade e os executa sequencialmente. Para estender a funcionalidade de um plug-in de terceiros, podemos escrever nosso próprio plug-in personalizado do WordPress.

Onde colocar nossos ganchos no WordPress

Preparação Pré-mergulho: Definições

Para evitar confundir termos, vamos nos ater a esta terminologia:

• Um gancho é um ponto ideal no WordPress onde as funções são registradas para serem executadas. Podemos conectar nossas funções a um dos muitos ganchos no WordPress e seus componentes ou criar nossas próprias.
  • Um gancho de ação executa ações.
  • Um gancho de filtro executa filtros.
• Uma função hooked é uma função de retorno de chamada PHP personalizada que “ligamos” em um local de hook do WordPress. O tipo a ser usado depende se o gancho deve permitir alterações fora da função - por exemplo, adicionar diretamente à saída da página da Web, modificar um banco de dados ou enviar um e-mail. Estes são conhecidos como efeitos colaterais .
  • Um filtro (ou função de filtro ) deve evitar efeitos colaterais trabalhando apenas e retornando uma cópia modificada dos dados passados ​​a ele.
  • Uma ação (ou função de ação), por outro lado, destina-se a causar efeitos colaterais. Não tem valor de retorno.

Com essas distinções em mente, podemos começar nossa exploração de ganchos.

Abstração e Código Limpo

Quando uma ação ou filtro é incorporado a um gancho, conforme necessário, cumprimos os objetivos de escrever apenas uma função por tarefa e evitar a duplicação de código dentro de um projeto. Por exemplo, digamos que queremos adicionar a mesma folha de estilo a três modelos de página (arquivo, página única e postagem personalizada) em nosso tema. Em vez de substituir cada modelo no pai, recriar cada um em nosso tema filho e adicionar folhas de estilo a seções de cabeçalho individuais, podemos escrever código em uma única função e anexá-lo com o gancho wp_head .

Nomenclatura pensativa

Evite conflitos proativamente nomeando um tema filho ou ganchos de plug-in personalizados de forma exclusiva. Ter ganchos com o mesmo nome em um único site é uma receita para o comportamento não intencional do código. As práticas recomendadas prescrevem que comecemos o nome de nosso gancho com um prefixo único e curto (por exemplo, iniciais do autor, projeto ou empresa), seguido por um nome de gancho descritivo. Por exemplo, usando o padrão “iniciais do projeto mais o nome do gancho”, para o projeto Tahir's Fabulous Plugin, poderíamos nomear nossos ganchos tfp-upload-document ou tfp-create-post-news .

Desenvolvimento e depuração simultâneos

Um único gancho pode acionar mais de uma ação ou filtro. Por exemplo, poderíamos escrever uma página da web que contém vários scripts, todos os quais usam o gancho de ação wp_head para imprimir HTML (por exemplo, uma seção <style> ou <script> ) dentro da seção <head> no front end da página.

Assim, vários desenvolvedores de plug-ins podem avançar vários objetivos em paralelo em um único plug-in ou dividir o plug-in em vários plug-ins individuais mais simples. Se um recurso não funcionar corretamente, podemos investigar e depurar diretamente sua função de gancho sem precisar pesquisar todo o projeto.

Ações

Uma ação executa o código quando ocorre um evento no WordPress. As ações podem realizar operações como:

• Criando dados.
• Lendo dados.
• Modificando dados.
• Excluindo dados.
• Gravando as permissões de usuários logados.
• Rastrear locais e armazená-los no banco de dados.

Exemplos de eventos em que as ações podem ser acionadas incluem:

• init , após o carregamento do WordPress, mas antes de enviar os cabeçalhos para o fluxo de saída.
• save_post , quando um post foi salvo.
• wp_create_nav_menu , logo após um menu de navegação ser criado com sucesso.

Uma ação pode interagir com uma API para transmitir dados (por exemplo, um link para uma postagem na mídia social), mas não retornará dados ao gancho de chamada.

Digamos que gostaríamos de automatizar o compartilhamento de todas as novas postagens em nosso site via mídia social. Comece procurando na documentação do WordPress um gancho que possa ser acionado sempre que um post for publicado.

Não há atalhos para encontrar nosso gancho: aprenderíamos com a experiência ou examinaríamos as ações listadas para encontrar candidatos prováveis. Podemos considerar save_post um candidato, mas rapidamente o descartamos, pois seria acionado várias vezes durante uma única sessão de edição. Uma escolha melhor é transition_post_status , que aciona apenas quando o status de um post é alterado (por exemplo, de draft para publish , de publish para trash ).

Iremos com transition_post_status , mas também refinaremos nossa ação para ser executada somente quando o status de nossa postagem passar para publish . Além disso, seguindo a documentação oficial e as APIs das várias plataformas de mídia social, podemos integrar e publicar o conteúdo do nosso post, juntamente com uma imagem em destaque:

 <?php function publish_post_on_social_media ( $new_status = NULL, $old_status = NULL, $post_ID = NULL ) { if ( 'publish' == $new_status && 'publish' != $old_status ) { // build the logic to share on social media } } add_action( 'transition_post_status', 'publish_post_on_social_media', 10, 3 ); ?>

Agora que sabemos como usar ganchos de ação, há um que é particularmente útil, especialmente quando se trata de CSS.

Designando prioridades com wp_enqueue_scripts

Digamos que queremos adicionar a folha de estilo do nosso tema filho por último, depois que todos os outros forem carregados, para garantir que qualquer classe com o mesmo nome originada em outro lugar seja substituída pelas classes do nosso tema filho.

O WordPress carrega folhas de estilo em uma ordem padrão:

1. Tema pai
2. Tema infantil
3. Qualquer plug-in

Nesta construção:

 add_action( string $hook_name, callable $callback, int $priority = 10, int $accepted_args = 1)

…o valor de priority da ação adicionada determina sua ordem de execução:

• O valor de priority padrão para wp_enqueue_scripts (ou qualquer ação) é “10”.
• Uma função é executada mais cedo se redefinirmos sua priority para um número menor.
• Uma função é executada mais tarde se redefinirmos sua priority para um número maior.

Para carregar a folha de estilo do nosso tema filho por último, use wp_enqueue_scripts , uma ação que é comumente usada por temas e plugins do WordPress. Precisamos apenas alterar a prioridade da ação wp_enqueue_scripts do nosso tema filho para um número maior que o padrão de “10”, digamos “99”:

 add_action( 'wp_enqueue_scripts', 'child_theme_styles', 99 );

Em geral, usamos ações quando não estamos procurando por valores de retorno. Para retornar dados ao gancho de chamada, precisamos examinar os filtros.

Filtros

Um filtro nos permite modificar os dados antes de serem processados ​​para exibição em um navegador. Para isso, um filtro aceita variável(eis), modifica o(s) valor(es) passado(s) e retorna dados para processamento posterior.

O WordPress verifica e executa todos os filtros registrados antes de preparar o conteúdo para os navegadores. Dessa forma, podemos manipular os dados antes de enviá-los ao navegador ou banco de dados, conforme apropriado.

Um dos meus clientes personaliza os produtos que vende, imprimindo-os com imagens que os clientes fornecem. Este cliente usa o plugin WooCommerce para gerenciar e-commerce. O WooCommerce não suporta essa funcionalidade pronta para uso. Portanto, adicionei dois bits de código ao functions.php do meu cliente:

1. woocommerce_checkout_cart_item_quantity , listado na documentação do WooCommerce, é um gancho de filtro que permite aos clientes adicionar elementos externos aos seus carrinhos, antes do checkout.
2. my_customer_image_data_in_cart é um filtro que nós mesmos escreveremos e usaremos para acionar woocommerce_checkout_cart_item_quantity sempre que o WooCommerce preparar um carrinho para exibição.

Usando o modelo a seguir, podemos adicionar adicionar nosso filtro e modificar o comportamento padrão do carrinho:

 add_filter( 'woocommerce_checkout_cart_item_quantity', 'my_customer_image_data_in_cart', 1, 3 ); function my_customer_image_data_in_cart( $html, $cart_item, $cart_item_key ) { if ( !empty( $cart_item['images_data'] ) ) { // Store image // Get image URL // Modify $html } return $html; }

Adicionamos filtros da mesma forma que adicionamos ações. Os filtros funcionam de maneira semelhante às ações, incluindo como as prioridades são processadas. A principal diferença entre filtros e ações é que uma ação não retornará dados ao gancho de chamada, mas um filtro retornará.

Ganchos de ação personalizados e ganchos de filtro

Escrever ganchos de ação personalizados não estende o Wordpress Core, mas apenas cria novos pontos de gatilho dentro de nosso próprio código.

Criando ganchos de ação personalizados

Adicionar um gancho personalizado em nosso tema ou plugin permite que outros desenvolvedores estendam a funcionalidade sem modificar nossa base de código. Para adicionar um gancho personalizado, use a mesma técnica que a própria base de código do WordPress Core usa: em nosso ponto de gatilho desejado, simplesmente chamamos do_action com o nome de nosso novo gancho, opcionalmente adicionando tantos argumentos quanto nossos retornos de chamada possam ser úteis:

 do_action( 'myorg_hello_action', $arg1, $arg2 );

Esse código simplesmente executa qualquer função de retorno de chamada que tenha sido conectada ao nosso gancho personalizado. Observe que o namespace é global, portanto, como sugerido anteriormente, seria uma boa ideia prefaciar nossos nomes de gancho personalizados com uma forma abreviada do nome de nossa organização (e possivelmente de nosso projeto também), daí o myorg_ aqui.

Agora que definimos myorg_hello_action , está disponível para os desenvolvedores se conectarem exatamente da mesma maneira que abordamos anteriormente para ganchos internos: Defina uma função e chame add_action() .

A menos que queiramos usar um novo gancho puramente internamente - afinal, é uma maneira útil de estruturar nosso código - teremos que comunicar sua disponibilidade downstream, para outros membros de nossa equipe ou para usuários externos de nosso plugin, por meio de documentação clara .

Criando ganchos de filtro personalizados

O padrão do WordPress para ganchos de filtro personalizados é o mesmo dos ganchos de ação, exceto que chamamos apply_filters() em vez de do_action() .

Vamos analisar um exemplo mais concreto desta vez. Suponha que nosso plugin crie um menu de barra lateral, que normalmente consiste em quatro itens. Adicionaremos um gancho de filtro personalizado para que nós (e desenvolvedores downstream) possamos modificar essa lista de itens em outro lugar:

 // Text labels of sidebar menu $sidebar_menu = array( "Page One", "Page Two", "Page Three", "Page Four" ); $sidebar_menu = apply_filters( 'myorg_sidebar_menu', $sidebar_menu );

É isso — nosso gancho de filtro personalizado myorg_sidebar_menu agora está pronto para ser usado em um plug-in que pode ser carregado posteriormente ou em outro lugar neste. Isso permite que qualquer pessoa que escreva código downstream personalize nossa barra lateral.

Nós ou outros desenvolvedores seguiremos o mesmo padrão ao usar um gancho interno do WordPress. Em outras palavras, começaremos definindo algumas funções de retorno de chamada que retornam uma versão modificada dos dados que são passados:

 function lowercase_sidebar_menu( $menu ) { $menu = array_map( 'strtolower', $menu ); return $menu; } function add_donate_item( $menu ) { $menu = array_push( $menu, 'Donate' ); return $menu; }

Assim como em nossos exemplos anteriores, agora estamos prontos para vincular nossas funções de retorno de chamada de filtro ao nosso gancho personalizado:

 add_filter( 'myorg_sidebar_menu', 'add_donate_item', 100 ); add_filter( 'myorg_sidebar_menu', 'lowercase_sidebar_menu' );

Com isso, conectamos nossas duas funções de retorno de chamada de exemplo em nosso gancho de filtro personalizado. Ambos agora modificam o conteúdo original de $the_sidebar_menu . Como demos um valor de priority mais alto para add_donate_item , ele é executado mais tarde, após a execução de lowercase_sidebar_menu .

Desenvolvedores downstream estão sempre livres para conectar mais funções de callback ao myorg_sidebar_menu . Ao fazê-lo, eles podem usar o parâmetro de priority para fazer seus ganchos serem executados antes, depois ou entre nossas duas funções de retorno de chamada de exemplo.

O céu é o limite com ações e filtros

Com ações, filtros e ganchos, a funcionalidade do WordPress pode crescer aos trancos e barrancos. Podemos desenvolver recursos personalizados para nosso site, deixando nossas próprias contribuições tão extensíveis quanto o WordPress. Hooks nos permitem aderir à segurança e às melhores práticas à medida que levamos nosso site WordPress para o próximo nível.

O Toptal Engineering Blog agradece a Fahad Murtaza por sua experiência, testes beta e revisão técnica deste artigo.