Como adicionar suporte WP-CLI a qualquer plug-in do WordPress

Ajustar um plugin às necessidades do usuário é uma das principais agendas que todo dono de plugin deve seguir. Para um controle deslizante de primeira página que significa mais seletores de cores, fontes e opções visuais semelhantes. No entanto, se você estiver atendendo desenvolvedores, administradores e outros usuários avançados, mais cedo ou mais tarde, eles vão querer suporte CLI. Eles vão querer abandonar o mouse e trabalhar apenas com o teclado. Graças ao projeto WP-CLI, adicionar suporte CLI ao seu plugin é muito fácil.

A eterna batalha GUI vs CLI

Vamos tirar algo do caminho: GUI (Graphical User Interface) não é melhor que CLI (Command Line Interface) e vice-versa: CLI não é melhor que GUI. As pessoas preferem um ao outro. É uma questão de preferência pessoal ou hábito. “Eles são os mesmos, eles são intercambiáveis?” Com alguns compromissos, sim, eles podem ser, mas ninguém gosta de escolher cores em uma interface de linha de comando em preto e branco. Isso é simplesmente contraproducente. Cada um deles serve a um propósito especializado.

“Então, por que precisamos de ambos? O WP não é mais orientado a GUI?” É, o WP é mais orientado a GUI. Mas não para todos os usuários. Algumas pessoas usam o WP de uma maneira mais adequada para CLI e permite que trabalhem muito mais rápido com ele. Além disso, por que não ter os dois? Não incha nada nem atrapalha.

Então, WP-CLI é um plugin, certo?

Não, não é um plugin. Você não precisa adicionar nada a uma instalação do WordPress para que o WP-CLI funcione. Você só precisa do WP-CLI no seu sistema operacional. WP-CLI é escrito em PHP e empacotado em um phar. É uma maneira de colocar um aplicativo PHP inteiro em um único arquivo, um “phar” (PHP Archive) para fácil distribuição e instalação em vários sistemas operacionais. O processo de instalação depende do seu sistema operacional, mas é fácil e bem documentado no manual do WP-CLI – ou se você gosta mais de vídeos, aqui está um de instalação do WP-CLI no Windows.

Não vou repetir nenhum dos materiais acima. É detalhado o suficiente e deve levá-lo a usar o WP-CLI em questão de minutos. Quando você o tiver em execução, altere seu diretório de trabalho para a instalação do WP com a qual planeja trabalhar e execute a wp option get home para ter certeza de que está na instalação correta do WP e que o WP-CLI funciona.

É mais simples do que parece

Primeiro, precisamos de uma função para nos dizer se o usuário está interagindo com o WP via CLI ou não. É útil para muitas coisas, como não enviar nenhum cabeçalho HTTP enquanto estiver na CLI e não incluir funções da CLI em chamadas “regulares”. Também nos dá a oportunidade de reutilizar funções antigas originalmente escritas para GUI com apenas algumas pequenas alterações.

function is_cli_running() {
  return defined( 'WP_CLI' ) && WP_CLI;
}

O próximo passo é descobrir um nome para seu comando CLI. Existem cerca de 40 comandos embutidos. Portanto, você não pode usar nenhum desses nomes e deve ficar longe de qualquer nome de marca, como “google”, pois provavelmente você não possui o Google. Idealmente, deve ser o nome do seu plugin ou um nome abrangente para um conjunto de funções que ele faz para que você possa colocar todos os comandos sob aquele em um esforço para não poluir o namespace principal. É senso comum, como com qualquer pedaço de código. Vamos usar o site-info e faremos algumas funções que retornam várias informações sobre o site.

Para manter as coisas limpas e organizadas, coloque todo o código relacionado ao WP-CLI em um novo arquivo – custom-wp-cli-commands.php . Incluiremos esse arquivo apenas quando for necessário e quando todo o código relacionado à CLI estiver disponível. Para isso, usaremos a função que acabamos de construir. Para testar e aprender, coloque o arquivo na pasta do seu tema ativo e adicione-o ao arquivo functions.php do tema.

if ( is_cli_running() ) {
  require_once 'custom-wp-cli-commands.php';
}

Em seguida, coloque isso em custom-wp-cli-commands.php ;

/**
 * Just a few sample commands to learn how WP-CLI works
 */
class cli_site_info extends WP_CLI_Command {
  /**
   * Display version information.
   * ## OPTIONS
   *
   * [--wponly]
   * : Shows only WP version info, omitting the plugin one.
   */
  function version( $args, $assoc_args ) {
    if ( !empty( $assoc_args['wponly'] ) ) {
      WP_CLI::line( 'Version of WordPress is ' . get_bloginfo( 'version' ) . '.' );
    } else {
      WP_CLI::line( 'Version of this plugin is 0.1-beta, and version of WordPress ' . get_bloginfo( 'version' ) . '.' );
    }
  }
    
    
  /**
   * Display the number of plugins.
   */
  function plugins() {
    WP_CLI::line( 'There are a total of ' . sizeof( get_plugins() ) . ' plugins on this site.' );
  }
}

WP_CLI::add_command( 'site-info', 'cli_site_info' );

Se você abrir o site, página inicial ou administrador, em um navegador nada acontecerá. Isso é bom. Para testar o novo comando CLI, volte para sua janela de linha de comando, execute wp site-info version e você obterá o plugin e a versão do site. Ou execute wp site-info plugins e você obterá o número total de plugins no site. Fácil, certo? Vamos repassar o código.

Tão fácil quanto estender uma classe PHP

Nossa classe cli_site_info estende a classe WP_CLI_Command ; nada extravagante lá. Você pode chamar a classe como quiser. O importante é o código na última linha do arquivo – WP_CLI::add_command( 'site-info', 'cli_site_info' ) . Ele registra nosso comando de nível superior e vincula nossa classe a ele. Se você quiser alterar o comando site-info para outra coisa, este é o lugar para fazê-lo.

Cada método público (função) na classe é um subcomando no WP-CLI. Certifique-se de verificar a anatomia de um comando para aprender a linguagem WP-CLI adequada. Não há necessidade de “registrar” o método em qualquer lugar ou fazer qualquer coisa extra. Como fizemos para plugins() e version() – crie uma função padrão e pronto. O WP-CLI saberá o que fazer com ele.

Quando estiver no método, você poderá executar qualquer código que precisar. Interagir com a CLI, no entanto, exigirá algumas funções personalizadas, pois coisas como echo não funcionarão conforme o esperado. Em vez de echo , há WP_CLI::line() . A API WP-CLI interna cobre tudo o que você precisa e todas as funções são bem documentadas, bem como separadas em entrada, saída, misc, sistema e outras categorias, o que as torna super fáceis de encontrar.

Além de imprimir texto, você provavelmente desejará usar argumentos de comando (associativos) para poder chamar coisas como wp site-info version --wponly (experimente) que gera apenas as informações da versão do WP. Os argumentos associativos são armazenados no segundo argumento da função do método. No nosso caso chama-se $assoc_args . A única coisa que resta é testar a chave do array para um valor específico e ajustar o código de acordo, como fizemos na function version( $args, $assoc_args ) .

Documentação e ajuda na CLI

O WP-CLI possui um sistema de ajuda integrado. É bastante útil. Nunca há necessidade de qualquer documentação externa para um comando se o desenvolvedor investir um pouco de tempo para descrever o comando em seu código. A documentação não será escrita sozinha (infelizmente), mas se você investir o mínimo necessário ao criar seus comandos, os usuários ficarão eternamente gratos, pois você colocará todos os documentos sob o mesmo teto.

Você escreve os documentos em sua classe como comentários, usando o formato PHPDoc. Para aprofundar, consulte o Manual da CLI. Ao executar o wp help site-info você obterá uma lista e descrição de nossos subcomandos e, se examinar o código, verá de onde ele vem. Muito auto-explicativo. Para obter mais detalhes sobre o subcomando version, execute wp help site-info version e você também obterá detalhes sobre as opções.

Deixe seus usuários felizes

Claro, se você estiver desenvolvendo um widget de clima, adicionar suporte a WP-CLI não soa como a jogada certa. No entanto, qualquer ferramenta usada por desenvolvedores e administradores obstinados, como o WP Reset, se beneficiará muito do WP-CLI. Os usuários poderão encadear comandos, escrever scripts bash e geralmente fazer mais coisas de maneira mais rápida e fácil. Isso leva a melhores avaliações, usuários mais felizes, mais usuários e, no final, mais dinheiro para você, independentemente do modelo de monetização que você tem em vigor.