Come aggiungere il supporto WP-CLI a qualsiasi plugin di WordPress

L'adeguamento di un plug-in alle esigenze dell'utente è una delle agende principali che ogni proprietario di plug-in deve seguire. Per un dispositivo di scorrimento in prima pagina ciò significa più raccoglitori di colori, caratteri e opzioni visive simili. Tuttavia, se ti rivolgi a sviluppatori, amministratori e altri utenti esperti prima o poi, vorranno il supporto CLI. Vorranno abbandonare il mouse e lavorare solo con la tastiera. Grazie al progetto WP-CLI aggiungere il supporto CLI al tuo plugin è un gioco da ragazzi.

L'eterna battaglia tra GUI e CLI

Togliamo qualcosa di mezzo: la GUI (Graphical User Interface) non è migliore della CLI (Command Line Interface) e viceversa: la CLI non è migliore della GUI. Le persone preferiscono l'una all'altra. È una questione di preferenze o abitudini personali. "Sono uguali, sono intercambiabili?" Con alcuni compromessi, sì, possono esserlo, ma a nessuno piace scegliere i colori in un'interfaccia a riga di comando in bianco e nero. Questo è semplicemente controproducente. Ognuno di loro ha uno scopo specializzato.

“Allora perché abbiamo bisogno di entrambi? WP non è più orientato alla GUI?" Lo è, WP è più orientato alla GUI. Ma non per tutti gli utenti. Alcune persone usano WP in un modo che è più adatto per CLI e consente loro di lavorare molto più velocemente con esso. Inoltre, perché non averli entrambi? Non gonfia nulla e non intralcia.

Quindi, WP-CLI è un plugin, giusto?

No, non è un plugin. Non è necessario aggiungere nulla a un'installazione di WordPress affinché WP-CLI funzioni. Hai solo bisogno di WP-CLI sul tuo sistema operativo. WP-CLI è scritto in PHP e confezionato in un phar. È un modo per mettere un'intera applicazione PHP in un unico file, un "phar" (Archivio PHP) per una facile distribuzione e installazione su vari sistemi operativi. Il processo di installazione dipende dal tuo sistema operativo, ma è facile e ben documentato nel manuale di WP-CLI – o se ti piacciono di più i video, ecco una delle installazioni di WP-CLI su Windows.

Non ho intenzione di ripetere nessuno dei materiali di cui sopra. È abbastanza dettagliato e dovrebbe farti iniziare con WP-CLI in pochi minuti. Quando è in esecuzione, cambia la directory di lavoro nell'installazione WP con cui prevedi di lavorare ed esegui l' wp option get home per assicurarti di essere sull'installazione WP corretta e che WP-CLI funzioni.

È più semplice di quanto sembri

Innanzitutto, abbiamo bisogno di una funzione che ci dica se l'utente sta interagendo con WP tramite CLI o meno. È utile per molte cose come non inviare intestazioni HTTP mentre si è nella CLI e per non includere le funzioni CLI nelle chiamate "normali". Ci dà anche l'opportunità di riutilizzare le vecchie funzioni originariamente scritte per la GUI con solo alcune piccole modifiche.

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

Il prossimo passo è trovare un nome per il tuo comando CLI. Ci sono circa 40 comandi integrati. Quindi non puoi usare nessuno di quei nomi e dovresti stare alla larga da nomi di marchi come "google" poiché probabilmente non possiedi Google. Idealmente, dovrebbe essere il nome del tuo plugin o un nome ombrello per un insieme di funzioni che fa in modo da poter inserire tutti i comandi sotto quello nel tentativo di non inquinare lo spazio dei nomi principale. È buon senso, come con qualsiasi pezzo di codice. Usiamo site-info e faremo alcune funzioni che restituiscono varie informazioni sul sito.

Per mantenere le cose pulite e ordinate, inserisci tutto il codice relativo a WP-CLI in un nuovo file: custom-wp-cli-commands.php . Includeremo quel file solo quando è necessario e quando tutto il codice relativo alla CLI sarà disponibile. Per questo, useremo la funzione che abbiamo appena creato. Per motivi di test e apprendimento, inserisci il file nella cartella del tema attivo e quindi aggiungilo al file functions.php del tema.

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

Quindi, inseriscilo in 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 apri il sito, la home page o l'amministratore, in un browser non accadrà nulla. Va bene. Per testare il nuovo comando CLI, torna alla finestra della riga di comando, esegui wp site-info version e otterrai il plug-in e la versione del sito. Oppure esegui wp site-info plugins e otterrai il numero totale di plugin sul sito. Facile, vero? Esaminiamo il codice.

Facile come estendere una classe PHP

La nostra classe cli_site_info estende la classe WP_CLI_Command ; niente di speciale lì. Puoi chiamare la classe come preferisci. L'importante è il codice nell'ultima riga del file – WP_CLI::add_command( 'site-info', 'cli_site_info' ) . Registra il nostro comando di primo livello e lega ad esso la nostra classe. Se vuoi cambiare il comando site-info in qualcos'altro, questo è il posto giusto per farlo.

Ogni metodo pubblico (funzione) nella classe è un sottocomando in WP-CLI. Assicurati di controllare l'anatomia di un comando per imparare il gergo WP-CLI corretto. Non è necessario "registrare" il metodo da nessuna parte o fare qualcosa in più. Come abbiamo fatto per plugins() e version() : crea una funzione standard e il gioco è fatto. WP-CLI saprà cosa farne.

Una volta che sei nel metodo, puoi eseguire qualsiasi codice di cui hai bisogno. L'interazione con la CLI, tuttavia, richiederà alcune funzioni personalizzate poiché cose come echo non funzioneranno come previsto. Invece di echo c'è WP_CLI::line() . L'API WP-CLI interna copre tutto ciò di cui hai bisogno e tutte le funzioni sono ben documentate e separate in input, output, misc, system e altre categorie, il che le rende estremamente facili da trovare.

Oltre a stampare il testo, probabilmente vorrai usare argomenti di comando (associativi) in modo da poter chiamare cose come wp site-info version --wponly (provalo) che restituisce solo le informazioni sulla versione WP. Gli argomenti associativi vengono archiviati nel secondo argomento della funzione del metodo. Nel nostro caso si chiama $assoc_args . L'unica cosa rimasta è testare la chiave dell'array per un valore specifico e regolare il codice di conseguenza, come abbiamo fatto in function version( $args, $assoc_args ) .

Documentazione e guida in CLI

WP-CLI ha un sistema di guida integrato. È abbastanza utile. Non c'è mai bisogno di documentazione esterna per un comando se lo sviluppatore investe un po' di tempo per descrivere il comando nel suo codice. La documentazione non si scriverà da sola (purtroppo) ma se investi il ​​minimo indispensabile durante la creazione dei tuoi comandi, gli utenti ti saranno eternamente grati poiché metterai tutti i documenti sotto lo stesso tetto.

Scrivi i documenti nella tua classe come commenti, usando il formato PHPDoc. Per approfondire, consulta il CLI Handbook. Eseguendo wp help site-info otterrai un elenco e una descrizione dei nostri sottocomandi e, se guardi nel codice, vedrai da dove proviene. Molto autoesplicativo. Per maggiori dettagli sul sottocomando versione, esegui wp help site-info version e otterrai anche dettagli sulle opzioni.

Rendi felici i tuoi utenti

Certo, se stai sviluppando un widget meteo, l'aggiunta del supporto WP-CLI non suona come la mossa giusta. Tuttavia, qualsiasi strumento utilizzato da sviluppatori e amministratori irriducibili come WP Reset trarrà grandi vantaggi da WP-CLI. Gli utenti saranno in grado di concatenare comandi, scrivere script bash e generalmente fare più cose in modo più semplice e veloce. Ciò porta a recensioni migliori, utenti più felici, più utenti e alla fine più soldi per te, indipendentemente dal modello di monetizzazione che hai adottato.