Cómo agregar compatibilidad con WP-CLI a cualquier complemento de WordPress

Ajustar un complemento a las necesidades del usuario es una de las agendas principales que todo propietario de un complemento debe seguir. Para un control deslizante en la página principal, eso significa más selectores de color, fuentes y opciones visuales similares. Sin embargo, si atiende a desarrolladores, administradores y otros usuarios avanzados tarde o temprano, querrán soporte CLI. Querrán deshacerse del mouse y trabajar solo con el teclado. Gracias al proyecto WP-CLI, agregar soporte CLI a su complemento es pan comido.

La eterna batalla GUI vs CLI

Vamos a aclarar algo: la GUI (interfaz gráfica de usuario) no es mejor que la CLI (interfaz de línea de comandos) y viceversa: la CLI no es mejor que la GUI. La gente prefiere uno sobre el otro. Es una cuestión de preferencia personal o hábito. “¿Son iguales, son intercambiables?” Con algunos compromisos, sí, pueden serlo, pero a nadie le gusta elegir colores en una interfaz de línea de comandos en blanco y negro. Eso es simplemente contraproducente. Cada uno tiene un propósito especializado.

“Entonces, ¿por qué necesitamos ambos? ¿No está WP más orientado a la GUI? Lo es, WP está más orientado a GUI. Pero no para todos los usuarios. Algunas personas usan WP de una manera que es más adecuada para CLI y les permite trabajar mucho más rápido con él. Además, ¿por qué no tener ambos? No hincha nada ni se interpone en el camino.

Entonces, WP-CLI es un complemento, ¿verdad?

No, no es un complemento. No necesita agregar nada a una instalación de WordPress para que WP-CLI funcione. Solo necesita WP-CLI en su sistema operativo. WP-CLI está escrito en PHP y empaquetado en un phar. Es una forma de colocar una aplicación PHP completa en un solo archivo, un "phar" (Archivo PHP) para una fácil distribución e instalación en varios sistemas operativos. El proceso de instalación depende de su sistema operativo, pero es fácil y está bien documentado en el manual de WP-CLI, o si le gustan más los videos, aquí tiene uno de la instalación de WP-CLI en Windows.

No voy a repetir nada del material anterior. Es lo suficientemente detallado y debería ponerlo en marcha con WP-CLI en cuestión de minutos. Cuando lo tenga en ejecución, cambie su directorio de trabajo a la instalación de WP con la que planea trabajar y ejecute wp option get home para asegurarse de que está en la instalación de WP correcta y que WP-CLI funciona.

es mas simple de lo que parece

Primero, necesitamos una función que nos diga si el usuario está interactuando con WP a través de CLI o no. Es útil para muchas cosas, como no enviar ningún encabezado HTTP mientras está en CLI y para no incluir funciones de CLI en llamadas "regulares". También nos brinda la oportunidad de reutilizar funciones antiguas originalmente escritas para GUI con solo algunos cambios menores.

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

El siguiente paso es encontrar un nombre para su comando CLI. Hay alrededor de 40 comandos integrados. Por lo tanto, no puede usar ninguno de esos nombres, y debe mantenerse alejado de cualquier nombre de marca como "google", ya que probablemente no sea el propietario de Google. Idealmente, debería ser el nombre de su complemento o un nombre general para un conjunto de funciones que realiza para que pueda poner todos los comandos debajo de ese en un esfuerzo por no contaminar el espacio de nombres principal. Es sentido común, como con cualquier pieza de código. Usemos site-info y crearemos algunas funciones que devuelvan información diversa sobre el sitio.

Para mantener las cosas limpias y ordenadas, coloque todo el código relacionado con WP-CLI en un nuevo archivo: custom-wp-cli-commands.php . Solo incluiremos ese archivo cuando sea necesario y cuando todo el código relacionado con la CLI esté disponible. Para eso, usaremos la función que acabamos de construir. Para probar y aprender, coloque el archivo en la carpeta de su tema activo y luego agréguelo al archivo functions.php del tema.

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

Luego, pon esto en 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 abre el sitio, la página de inicio o el administrador, en un navegador no pasará nada. Eso es bueno. Para probar el nuevo comando CLI, vuelva a la ventana de la línea de comandos, ejecute wp site-info version y obtendrá el complemento y la versión del sitio. O ejecute wp site-info plugins y obtendrá la cantidad total de complementos en el sitio. Fácil, ¿verdad? Repasemos el código.

Tan fácil como extender una clase de PHP

Nuestra clase cli_site_info extiende la clase WP_CLI_Command ; nada lujoso allí. Puedes llamar a la clase como quieras. Lo importante es el código en la última línea del archivo: WP_CLI::add_command( 'site-info', 'cli_site_info' ) . Registra nuestro comando de nivel superior y vincula nuestra clase a él. Si desea cambiar el comando site-info a otra cosa, este es el lugar para hacerlo.

Cada método público (función) en la clase es un subcomando en WP-CLI. Asegúrese de revisar la anatomía de un comando para aprender la jerga adecuada de WP-CLI. No hay necesidad de “registrar” el método en ningún lugar ni hacer nada extra. Como hicimos con los plugins() y la version() : crea una función estándar y eso es todo. WP-CLI sabrá qué hacer con él.

Una vez que esté en el método, puede ejecutar cualquier código que necesite. Sin embargo, la interacción con la CLI requerirá algunas funciones personalizadas, ya que cosas como el echo no funcionarán como se esperaba. En lugar de echo hay WP_CLI::line() . La API interna de WP-CLI cubre todo lo que necesita y todas las funciones están bien documentadas y separadas en entrada, salida, miscelánea, sistema y otras categorías, lo que las hace muy fáciles de encontrar.

Además de imprimir texto, probablemente querrá usar argumentos de comando (asociativos) para poder llamar cosas como wp site-info version --wponly (pruébelo) que genera solo la información de la versión de WP. Los argumentos asociativos se almacenan en el segundo argumento de función del método. En nuestro caso se llama $assoc_args . Lo único que queda es probar la clave de matriz para un valor específico y ajustar el código en consecuencia, como hicimos en function version( $args, $assoc_args ) .

Documentación y ayuda en CLI

WP-CLI tiene un sistema de ayuda incorporado. Es bastante útil. Nunca se necesita documentación externa para un comando si el desarrollador invierte un poco de tiempo para describir el comando en su código. La documentación no se escribirá sola (desafortunadamente), pero si invierte lo mínimo mientras crea sus comandos, los usuarios estarán eternamente agradecidos, ya que pondrá todos los documentos bajo un mismo techo.

Escribes los documentos en tu clase como comentarios, usando el formato PHPDoc. Para profundizar más, consulte el Manual de CLI. Al ejecutar wp help site-info , obtendrá una lista y una descripción de nuestros subcomandos, y si observa el código, verá de dónde proviene. Muy autoexplicativo. Para obtener más detalles sobre el subcomando de versión, ejecute wp help site-info version y también obtendrá detalles sobre las opciones.

Haz felices a tus usuarios

Claro, si está desarrollando un widget meteorológico, agregar soporte WP-CLI no parece ser el movimiento correcto. Sin embargo, cualquier herramienta utilizada por desarrolladores y administradores acérrimos, como WP Reset, se beneficiará enormemente de WP-CLI. Los usuarios podrán encadenar comandos, escribir scripts de bash y, en general, hacer más cosas de forma más rápida y sencilla. Eso conduce a mejores reseñas, usuarios más felices, más usuarios y, al final, más dinero para ti, independientemente del modelo de monetización que tengas.