Comment ajouter la prise en charge de WP-CLI à n'importe quel plugin WordPress

Ajuster un plugin aux besoins de l'utilisateur est l'un des principaux programmes que chaque propriétaire de plugin doit suivre. Pour un curseur de première page, cela signifie plus de sélecteurs de couleurs, de polices et d'options visuelles similaires. Cependant, si vous vous adressez tôt ou tard à des développeurs, des administrateurs et d'autres utilisateurs expérimentés, ils voudront un support CLI. Ils voudront abandonner la souris et travailler uniquement avec le clavier. Grâce au projet WP-CLI, ajouter le support CLI à votre plugin est un jeu d'enfant.

L'éternelle bataille GUI vs CLI

Mettons quelque chose de côté : GUI (Graphical User Interface) n'est pas meilleur que CLI (Command Line Interface) et vice-versa : CLI n'est pas meilleur que GUI. Les gens préfèrent l'un à l'autre. C'est une question de préférence ou d'habitude personnelle. « Sont-ils identiques, sont-ils interchangeables ? » Avec quelques compromis, oui, ils peuvent l'être, mais personne n'aime choisir des couleurs dans une interface de ligne de commande en noir et blanc. C'est tout simplement contre-productif. Ils servent chacun un objectif spécialisé.

« Alors pourquoi avons-nous besoin des deux ? WP n'est-il pas plus orienté GUI ? C'est vrai, WP est plus orienté GUI. Mais pas pour tous les utilisateurs. Certaines personnes utilisent WP d'une manière plus adaptée à la CLI, et cela leur permet de travailler beaucoup plus rapidement avec. D'ailleurs, pourquoi ne pas avoir les deux ? Il ne gonfle rien et ne gêne pas.

Donc, WP-CLI est un plugin, n'est-ce pas ?

Non, ce n'est pas un plugin. Vous n'avez rien besoin d'ajouter à une installation WordPress pour que WP-CLI fonctionne. Vous n'avez besoin que de WP-CLI sur votre système d'exploitation. WP-CLI est écrit en PHP et emballé dans un phar. C'est un moyen de mettre une application PHP entière dans un seul fichier, un "phar" (archive PHP) pour une distribution et une installation faciles sur différents systèmes d'exploitation. Le processus d'installation dépend de votre système d'exploitation, mais il est simple et bien documenté dans le manuel WP-CLI - ou si vous préférez les vidéos, voici l'installation de WP-CLI sous Windows.

Je ne vais pas répéter le matériel ci-dessus. Il est suffisamment détaillé et devrait vous permettre de démarrer avec WP-CLI en quelques minutes. Lorsque vous l'exécutez, remplacez votre répertoire de travail par l'installation WP avec laquelle vous prévoyez de travailler et exécutez wp option get home pour vous assurer que vous êtes sur la bonne installation WP et que WP-CLI fonctionne.

C'est plus simple qu'il n'y paraît

Tout d'abord, nous avons besoin d'une fonction pour nous dire si l'utilisateur interagit avec WP via CLI ou non. C'est utile pour beaucoup de choses comme ne pas envoyer d'en-têtes HTTP en CLI et pour ne pas inclure les fonctions CLI sur les appels "réguliers". Cela nous donne également la possibilité de réutiliser d'anciennes fonctions écrites à l'origine pour l'interface graphique avec seulement quelques modifications mineures.

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

L'étape suivante consiste à trouver un nom pour votre commande CLI. Il y a environ 40 commandes intégrées. Vous ne pouvez donc utiliser aucun de ces noms et vous devez rester à l'écart de tout nom de marque tel que "google", car vous ne possédez probablement pas Google. Idéalement, il devrait s'agir du nom de votre plugin ou d'un nom générique pour un ensemble de fonctions qu'il exécute afin que vous puissiez placer toutes les commandes sous celui-ci afin de ne pas polluer l'espace de noms principal. C'est du bon sens, comme avec n'importe quel morceau de code. Utilisons site-info et nous créerons quelques fonctions qui renvoient diverses informations sur le site.

Pour garder les choses propres et bien rangées, placez tout le code lié à WP-CLI dans un nouveau fichier - custom-wp-cli-commands.php . Nous n'inclurons ce fichier que lorsqu'il est nécessaire et lorsque tout le code lié à la CLI est disponible. Pour cela, nous allons utiliser la fonction que nous venons de construire. Pour tester et apprendre, placez le fichier dans le dossier de votre thème actif, puis ajoutez-le au fichier functions.php du thème.

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

Ensuite, mettez ceci dans 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' );

Si vous ouvrez le site, la page d'accueil ou l'administrateur, rien ne se passera dans un navigateur. C'est bon. Pour tester la nouvelle commande CLI, revenez à votre fenêtre de ligne de commande, exécutez wp site-info version et vous obtiendrez le plugin et la version du site. Ou exécutez wp site-info plugins et vous obtiendrez le nombre total de plugins sur le site. Facile, non ? Passons en revue le code.

Aussi simple que d'étendre une classe PHP

Notre classe cli_site_info étend la classe WP_CLI_Command ; rien d'extraordinaire là-bas. Vous pouvez appeler la classe comme bon vous semble. Ce qui est important, c'est le code sur la dernière ligne du fichier - WP_CLI::add_command( 'site-info', 'cli_site_info' ) . Il enregistre notre commande de niveau supérieur et y lie notre classe. Si vous voulez changer la commande site-info en autre chose, c'est ici qu'il faut le faire.

Chaque méthode publique (fonction) de la classe est une sous-commande dans WP-CLI. Assurez-vous de vérifier l'anatomie d'une commande pour apprendre le bon jargon WP-CLI. Il n'est pas nécessaire d'"enregistrer" la méthode où que ce soit ou de faire quoi que ce soit d'autre. Comme nous l'avons fait pour plugins() et version() - créez une fonction standard, et c'est tout. WP-CLI saura quoi en faire.

Une fois que vous êtes dans la méthode, vous pouvez exécuter n'importe quel code dont vous avez besoin. Cependant, l'interaction avec la CLI nécessitera certaines fonctions personnalisées, car des éléments tels que echo ne fonctionneront pas comme prévu. Au lieu de echo , il y a WP_CLI::line() . L'API WP-CLI interne couvre tout ce dont vous avez besoin et toutes les fonctions sont bien documentées et séparées en entrées, sorties, divers, système et autres catégories, ce qui les rend très faciles à trouver.

Outre l'impression de texte, vous souhaiterez probablement utiliser des arguments de commande (associatifs) afin de pouvoir appeler des éléments tels que wp site-info version --wponly (essayez-le) qui ne génère que les informations de version WP. Les arguments associatifs sont stockés dans le deuxième argument de la fonction de la méthode. Dans notre cas, il s'appelle $assoc_args . La seule chose qui reste est de tester la clé du tableau pour une valeur spécifique et d'ajuster le code en conséquence, comme nous l'avons fait dans function version( $args, $assoc_args ) .

Documentation et aide en CLI

WP-CLI a un système d'aide intégré. C'est assez pratique. Il n'y a jamais besoin de documentation externe pour une commande si le développeur investit un peu de temps pour décrire la commande dans son code. La documentation ne s'écrira pas (malheureusement) mais si vous investissez le strict minimum lors de la création de vos commandes, les utilisateurs vous seront éternellement reconnaissants car vous mettrez toutes les docs sous un même toit.

Vous écrivez les documents de votre classe sous forme de commentaires, en utilisant le format PHPDoc. Pour approfondir, consultez le manuel CLI. En exécutant wp help site-info , vous obtiendrez une liste et une description de nos sous-commandes, et si vous regardez dans le code, vous verrez d'où il vient. Très explicite. Pour plus de détails sur la sous-commande version, exécutez wp help site-info version et vous obtiendrez également des détails sur les options.

Rendez vos utilisateurs heureux

Bien sûr, si vous développez un widget météo, l'ajout de la prise en charge de WP-CLI ne semble pas être la bonne décision. Cependant, tout outil utilisé par les développeurs et les administrateurs purs et durs tels que WP Reset bénéficiera grandement de WP-CLI. Les utilisateurs pourront chaîner des commandes, écrire des scripts bash et généralement faire plus de choses plus rapidement et plus facilement. Cela conduit à de meilleures critiques, des utilisateurs plus satisfaits, plus d'utilisateurs et au final plus d'argent pour vous, quel que soit le modèle de monétisation que vous avez mis en place.