Como tornar um plugin WordPress extensível

Publicados: 2022-03-10

Resumo rápido ↬ Quando você pensa que finalmente encontrou um plugin que faz tudo o que você precisa, ainda há aquela pequena coisa importante que ele não pode fazer. Descubra como tornar seu plugin extensível e reduzir a dor de cabeça.

Você já usou um plugin e desejou que ele fizesse algo um pouco diferente? Talvez você precisasse de algo único que estivesse além do escopo da página de configurações do plugin.

Eu pessoalmente encontrei isso, e aposto que você também. Se você é um desenvolvedor de plug-ins do WordPress, provavelmente alguns de seus usuários também encontraram isso ao usar seu plug-in.

Aqui está um cenário típico: você finalmente encontrou aquele plugin que faz tudo que você precisa – exceto por uma pequena coisa importante. Não há configuração ou opção para habilitar essa pequena coisa, então você navega na documentação e descobre que não pode fazer nada a respeito. Você solicita o recurso no fórum de suporte do plugin WordPress - mas sem dados. No final, você desinstala e continua sua pesquisa.

Imagine se você fosse o desenvolvedor deste plugin. O que você faria se um usuário solicitasse alguma funcionalidade específica?

O ideal seria implementá-lo. Mas se o recurso fosse para um caso de uso muito especial, adicioná-lo seria impraticável. Não seria bom ter uma configuração de plug-in que apenas 0,1% de seus usuários pudesse usar.

Você só deseja implementar recursos que afetam a maioria de seus usuários. Na realidade, 80% dos usuários usam 20% dos recursos (a regra 80/20). Portanto, certifique-se de que qualquer novo recurso seja altamente solicitado e que 80% de seus usuários se beneficiem dele antes de implementá-lo. Se você criasse uma configuração para cada recurso solicitado, seu plug-in ficaria complicado e inchado - e ninguém quer isso.

Sua melhor aposta é tornar o plugin extensível, em termos de código, para que outras pessoas possam aprimorá-lo ou modificá-lo para suas próprias necessidades.

Neste artigo, você aprenderá por que tornar seu plug-in extensível é uma boa ideia. Também vou compartilhar algumas dicas de como aprendi a fazer isso.

Mais depois do salto! Continue lendo abaixo ↓

O que torna um plug-in extensível?

Em poucas palavras, um plug-in extensível significa que ele adere à parte "O" dos princípios SOLID da programação orientada a objetos - ou seja, o princípio aberto/fechado.

Se você não estiver familiarizado com o princípio aberto/fechado, isso basicamente significa que outras pessoas não deveriam ter que editar seu código para modificar algo .

Aplicando este princípio a um plugin WordPress, significaria que um plugin é extensível se tiver provisões que permitam que outras pessoas modifiquem seu comportamento. É como o WordPress permite que as pessoas "se conectem" a diferentes áreas do WordPress, mas no nível do plugin.

Um exemplo típico de um plugin

Vamos ver como podemos criar um plug-in extensível, começando com um plug-in de exemplo que não é.

Suponha que temos um plugin que gera um widget de barra lateral que exibe os títulos das três últimas postagens. No coração do plugin está uma função que simplesmente envolve os títulos desses três posts em tags de lista:

 function get_some_post_titles() { $args = array( 'posts_per_page' => 3, ); $posts = get_posts( $args ); $output = ' ';
  foreach ( $posts as $post ) {
      $saída .= ' ' . $post->post_title . ' ';
  }
  $saída .= ' ';

  retorno $ saída;
}

Embora esse código funcione e faça o trabalho, não é muito extensível.

Por quê? Como a função é definida de maneira própria, não há como alterar seu comportamento sem modificar o código diretamente.

E se um usuário quiser exibir mais de três postagens ou talvez incluir links com os títulos das postagens? Não há como fazer isso com o código acima. O usuário está preso à forma como o plug-in funciona e não pode alterá-lo.

Incluir cem configurações não é a resposta

Existem várias maneiras de aprimorar o plug-in acima para permitir que os usuários o personalizem.

Uma dessas maneiras seria adicionar muitas opções nas configurações, mas mesmo isso pode não satisfazer todas as possibilidades que os usuários desejam do plug-in.

E se o usuário quisesse fazer o seguinte (cenários que revisitaremos mais tarde):

exibir produtos ou postagens do WooCommerce de uma categoria específica;
exibir os itens em um carrossel fornecido por outro plugin, em vez de uma simples lista;
execute uma consulta de banco de dados personalizada e, em seguida, use as postagens dessa consulta na lista.

Se adicionarmos uma centena de configurações ao nosso widget, poderemos cobrir os casos de uso acima. Mas e se um desses cenários mudar e agora o usuário quiser exibir apenas os produtos WooCommerce que estão atualmente em estoque? O widget precisaria de ainda mais configurações para acomodar isso. Muito em breve, teríamos um zilhão de configurações.

Além disso, um plugin com uma lista enorme de configurações não é exatamente fácil de usar. Afaste-se desta rota, se possível.

Então, como faríamos para resolver esse problema? Nós tornaríamos o plugin extensível.

Adicionando nossos próprios ganchos para torná-lo extensível

Ao estudar o código do plugin acima, vemos algumas operações que a função main realiza:

Ele obtém postagens usando get_posts .
Ele gera uma lista de títulos de postagem.
Ele retorna a lista gerada.

Se outras pessoas modificassem o comportamento deste plugin, seu trabalho provavelmente envolveria essas três operações. Para tornar nosso plugin extensível, teríamos que adicionar ganchos em torno deles para abri-los para outros desenvolvedores.

Em geral, estas são boas áreas para adicionar ganchos a um plugin:

ao redor e dentro dos principais processos,
ao construir HTML de saída,
para alterar consultas de postagem ou banco de dados,
antes de retornar valores de uma função.

Um exemplo típico de um plug-in extensível

Tomando essas regras básicas, podemos adicionar os seguintes filtros para tornar nosso plugin extensível:

adicione myplugin_get_posts_args para modificar os argumentos de get_posts ,
adicione myplugin_get_posts para substituir os resultados de get_posts ,
adicione myplugin_list_item para personalizar a geração de uma entrada de lista,
adicione myplugin_get_some_post_titles para substituir a lista gerada retornada.

Aqui está o código novamente com todos os ganchos adicionados:

 function get_some_post_titles() { $args = array( 'posts_per_page' => 3, ); // Let other people modify the arguments. $posts = get_posts( apply_filters( 'myplugin_get_posts_args', $args ) ); // Let other people modify the post array, which will be used for display. $posts = apply_filters( 'myplugin_get_posts', $posts, $args ); $output = ' ';
  foreach ( $posts as $post ) {

      // Permitir que outras pessoas modifiquem a entrada da lista.
      $saída .= ' ' . apply_filters( 'myplugin_list_item', $post->post_title, $post) . ' ';
  }
  $saída .= ' ';

  // Permitir que outras pessoas modifiquem nossa lista de saída.
  return apply_filters( 'myplugin_get_some_post_titles', $output, $args );
}

Você também pode obter o código acima no arquivo do GitHub.

Estou adicionando muitos ganchos aqui, o que pode parecer impraticável porque o código de exemplo é bastante simples e pequeno, mas ilustra meu ponto: adicionando apenas quatro ganchos, outros desenvolvedores agora podem personalizar o comportamento do plug-in de várias maneiras.

Namespace e contexto para ganchos

Antes de prosseguir, observe duas coisas importantes sobre os ganchos que implementamos:

Estamos colocando namespaces nos ganchos com myplugin_ .
Isso garante que o nome do gancho não entre em conflito com o gancho de algum outro plugin. Esta é apenas uma boa prática, porque se outro gancho com o mesmo nome for chamado, isso poderá levar a efeitos indesejados.
Também estamos passando uma referência a $args em todos os ganchos para contextualizar.
Faço isso para que, se outros usarem esse filtro para alterar algo no fluxo do código, eles possam usar esse parâmetro $args como referência para ter uma ideia de porque o gancho foi chamado, para que possam realizar seus ajustes de acordo.

Os efeitos de nossos ganchos

Lembre-se dos cenários únicos sobre os quais falei anteriormente? Vamos revisitá-los e ver como nossos ganchos os tornaram possíveis:

Se o usuário quiser exibir produtos ou postagens do WooCommerce de uma categoria específica , poderá usar o filtro myplugin_get_posts_args para adicionar seus próprios argumentos para quando o plug-in consultar postagens ou usar myplugin_get_posts para substituir completamente as postagens com sua própria lista.
Se o usuário quiser exibir os itens em um carrossel fornecido por outro plugin , em vez de uma lista simples, ele poderá substituir toda a saída da função com myplugin_get_some_post_titles e, em vez disso, gerar um carrossel a partir daí.
Se o usuário quiser realizar uma consulta de banco de dados personalizada e, em seguida, usar as postagens dessa consulta na lista, então, semelhante ao primeiro cenário, ele poderá usar myplugin_get_posts para usar sua própria consulta de banco de dados e alterar a matriz de postagem.

Muito melhor!

Um exemplo rápido de como usar nossos filtros

Os desenvolvedores podem usar add_filter para se conectar aos nossos filtros acima (ou usar add_action para ações).

Tomando nosso primeiro cenário acima, um desenvolvedor pode fazer o seguinte para exibir produtos WooCommerce usando o filtro myplugin_get_posts_args que criamos:

 add_filter( 'myplugin_get_posts_args', 'show_only_woocommerce_products' ); function show_only_woocommerce_products( $args ) { $args['post_type'] = 'product'; return $args; }

Também podemos usar ganchos de ação

Além de usar apply_filters , também podemos usar do_action para tornar nosso código extensível. A diferença entre os dois é que o primeiro permite que outros alterem uma variável, enquanto o último permite que outros executem funcionalidades adicionais em várias partes do nosso código.

Ao usar ações, estamos essencialmente expondo o fluxo do plug-in a outros desenvolvedores e permitindo que eles executem outras coisas em conjunto.

Pode não ser útil em nosso exemplo (porque estamos exibindo apenas um shortcode), mas seria útil em outros. Por exemplo, dado um plug-in de backup extensível, poderíamos criar um plug-in que também carrega o arquivo de backup para um serviço de terceiros, como o Dropbox.

"Excelente! Mas por que devo me preocupar em tornar meu plug-in extensível?”

Bem, se você ainda não está convencido da ideia, aqui estão alguns pensamentos sobre por que permitir que outras pessoas modifiquem o comportamento do seu plugin é uma boa ideia.

Ele abre o plug-in para mais possibilidades de personalização

Todo mundo tem necessidades diferentes. E há uma grande chance de seu plugin não satisfazer todos eles, nem você pode antecipá-los. Abrir seu plug-in para permitir modificações em áreas-chave do comportamento do plug-in pode fazer maravilhas.

Permite que as pessoas introduzam modificações sem tocar no código do plug-in

Outros desenvolvedores não serão forçados a alterar os arquivos do seu plugin diretamente. Este é um grande benefício porque modificar diretamente o arquivo de um plugin geralmente é uma prática ruim. Se o plugin for atualizado, todas as suas modificações serão apagadas.

Se adicionarmos nossos próprios ganchos para outras pessoas usarem, as modificações do plug-in poderão ser colocadas em um local externo — digamos, em outro plug-in. Feito desta forma, o plugin original não será tocado e poderá ser atualizado livremente sem quebrar nada, e todas as modificações no outro plugin permanecerão intactas.

Conclusão

Plugins extensíveis são realmente incríveis e nos dão espaço para muitas possibilidades de personalização. Se você tornar seu plugin extensível, seus usuários e outros desenvolvedores vão adorar você por isso.

Dê uma olhada em plugins como WooCommerce, Easy Digital Downloads e ACF. Esses plugins são extensíveis e você pode dizer facilmente porque vários outros plugins no diretório de plugins do WordPress adicionam funcionalidade a eles. Eles também fornecem uma ampla gama de ganchos de ação e filtro que modificam vários aspectos dos plugins. As regras práticas que enumerei acima surgiram em meu estudo sobre elas.

Aqui estão algumas dicas para tornar seu plugin extensível:

Siga o princípio aberto/fechado. Outras pessoas não deveriam ter que editar seu código para modificar algo.
Para tornar seu plug-in extensível, adicione ganchos nestes locais:
- ao redor e dentro dos principais processos,
- ao construir o HTML de saída,
- para alterar consultas de postagem ou banco de dados,
- antes de retornar valores de uma função.
Namespace os nomes dos seus ganchos com o nome do seu plugin para evitar conflitos de nomenclatura.
Tente passar outras variáveis relacionadas ao gancho, para que outras pessoas tenham algum contexto do que está acontecendo no gancho.
Não se esqueça de documentar os hooks do seu plugin, para que outras pessoas possam aprender sobre eles.

Leitura adicional

Aqui estão alguns recursos se você quiser saber mais sobre extensão de plugins:

Como tornar seu plugin WordPress extensível, GitHub
Todo o código de exemplo neste artigo.
"Dicas úteis para começar com WordPress Hooks", Thomas Maier, Smashing Magazine
"Como criar um plugin WordPress", Daniel Pataki, Smashing Magazine
"Hooks," Manual do Plugin, WordPress.org