Qué hacer para que tu plugin se pueda usar con WP-CLI

Ajustar un plugin a las necesidades del usuario es una de las principales prioridades que todo desarrollador de plugins debe seguir.

Para un carrusel de portada esto significa más selectores de color, fuentes y opciones visuales similares.

Sin embargo, si estás ayudando a desarrolladores, administradores y otros usuarios avanzados, tarde o temprano querrán compatibilidad con CLI. Querrán deshacerse del ratón y trabajar sólo con el teclado.

Gracias al proyecto WP-CLI, añadir compatibilidad con CLI a tu plugin es pan comido.

El eterno debate entre interfaz gráfica de usuario y línea de comandos

Digamos algo claro: Una GUI (interfaz gráfica de usuario) no es mejor que CLI (interfaz de línea de comandos) o viceversa: CLI no es mejor que GUI.

La gente prefiere una cosa a la otra. Es una cuestión de preferencia o de costumbres personales. «¿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 improductivo. Cada uno de ellos tiene un propósito especializado.

Entonces, ¿por qué necesitamos ambas cosas? ¿No está WordPress más orientado al GUI?

Es decir, WordPress está más orientado a GUI. Pero no para todos los usuarios.

Algunas personas usan WordPress de una manera más indicada para CLI y les permite trabajar mucho más rápido con ella. Además, ¿por qué no tener ambos? No hincha nada ni estorba.

Vale, probemos ¿cómo instalo eso del WP-CLI?

WP-CLI no es un plugin, no lo puedes instalar como tal.

Tampoco es necesario añadir nada a una instalación de WordPress para que WP-CLI funcione. Sólo necesitas tener instalado WP-CLI en el sistema operativo de tu alojamiento.

WP-CLI está escrito en PHP y empaquetado en un archivo en formato phar. Es una forma de poner toda una aplicación PHP en un solo archivo, un «phar» (PHP Archive) para una fácil distribución e instalación a través de varios sistemas operativos.

El proceso de instalación depende de tu sistema operativo, pero es fácil y está bien documentado en el manual de WP-CLI – o si te gustan más los videos, aquí tienes una instalación de WP-CLI en Windows:

El procedimiento está lo suficientemente detallado y claro en el manual que deberías ser capaz de poner en marcha WP-CLI en cuestión de minutos.

Cuando lo tengas en marcha, cambia tu directorio de trabajo a la instalación de WordPress con la que planeas trabajar y ejecuta el comando wp option get home para asegurarte de que estás en la instalación de WordPress correcta y que WP-CLI funciona.

Y encima es fácil de usar

Primero necesitamos una función que nos diga si el usuario está interactuando con WordPress vía CLI o no. Es útil para muchas cosas como no enviar ninguna cabecera HTTP mientras estás en CLI y para no incluir funciones CLI en llamadas «regulares».

También nos da la oportunidad de reutilizar funciones antiguas escritas originalmente para la GUI con sólo algunos cambios menores.

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

El siguiente paso es encontrar un nombre para el comando CLI. Hay alrededor de 40 comandos internos. Así que no puedes usar ninguno de esos nombres, y deberías mantenerte alejado de cualquier marca como «google», ya que seguramente no seas el propietario de Google.

Lo ideal es que sea el nombre de tu plugin, o un nombre paraguas para un conjunto de funciones que hace para que puedas poner todos los comandos debajo de ese, en un esfuerzo por no contaminar el namespace principal.

Es de sentido común, como con cualquier código. Usemos la información del sitio y haremos unas cuantas funciones que devuelven información variada sobre el sitio.

Para mantener las cosas limpias y ordenadas, coloca todo el código relacionado con WP-CLI en un nuevo archivo, por ejemplo miplugin-wp-cli-commands.php.

Sólo incluiremos ese archivo cuando sea necesario y cuando todo el código relacionado con CLI esté disponible. Para eso, usaremos la función que acabamos de crear. Para probar y aprender, coloca el archivo en la carpeta de tu tema activo y luego añádelo al archivo functions.php del tema.

if ( funciona_cli() ) {
  require_once 'miplugin-wp-cli-commands.php';
}

Luego pon el siguiente código en tu archivo miplugin-wp-cli-commands.php:

/**
 * Comandos WP-CLI de ejemplo que podríamos añadir
 */
class cli_site_info extends WP_CLI_Command {
  /**
   * Mostramos información de la versión.
   * ## OPTIONS
   *
   * [--wponly]
   * : Muestra solo la versión de WP, omitiendo la del plugin.
   */
  function version( $args, $assoc_args ) {
    if ( !empty( $assoc_args['wponly'] ) ) {
      WP_CLI::line( 'La versión de WordPress es ' . get_bloginfo( 'version' ) . '.' );
    } else {
      WP_CLI::line( 'La versión de este plugin es la 0.1-beta, y la versión de WordPress la ' . get_bloginfo( 'version' ) . '.' );
    }
  }
     
     
  /**
   * Mostramos la cantidad de plugins.
   */
  function plugins() {
    WP_CLI::line( 'Hay un total de ' . sizeof( get_plugins() ) . ' plugins en este sitio.' );
  }
}
 
WP_CLI::add_command( 'site-info', 'cli_site_info' );

Si abres el sitio, la página principal o la administración, en un navegador no pasará nada. Eso es bueno.

Para probar el nuevo comando CLI, vuelve a la ventana de la línea de comandos, ejecuta wp site-info version y obtendrás la versión del plugin y del sitio.

O ejecuta los wp site-info plugins y obtendrás el número total de plugins en el sitio.

Fácil, ¿verdad? Repasemos el código.

Aprendiendo del ejemplo de código

Nuestra clase cli_site_info extiende la clase WP_CLI_Command; nada sofisticado. 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 a nuestra clase con él.

Si quieres cambiar el comando site-info por 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úrate de revisar la anatomía de un comando para aprender la nomenclatura correcta de WP-CLI.

No hay necesidad de «registrar» el método en ningún sitio ni de hacer nada extra.

Como hicimos para plugins() y version() – crear una función estándar, y eso es todo. WP-CLI sabrá qué hacer con él.

Una vez conozcas el método, puedes ejecutar cualquier código que necesites.

Interactuar con la CLI, sin embargo, requerirá de algunas funciones personalizadas ya que cosas como echo no funcionarán como uno espera. En lugar de echo está WP_CLI::line().

La API interna de WP-CLI cubre todo lo que necesitas y todas las funciones están bien documentadas, así como separadas en las categorías de entrada, salida, misc, sistema y otras, lo que las hace súper fáciles de encontrar.

Además de imprimir texto, probablemente querrás usar argumentos de comandos (asociativos) para poder llamar a cosas como wp site-info version --wponly (pruébalo) que sólo genera la información de la versión WP.

Los argumentos asociativos se almacenan en el argumento de la segunda función del método. En nuestro caso se llama $assoc_args.

Lo único que quedaría pendiente sería probar la clave de la matriz para un valor específico y ajustar el código en consecuencia, como hicimos en la versión de la función ( $args, $assoc_args).

¡Necesito más ayuda!

WP-CLI tiene un sistema de ayuda incorporado. Es muy útil.

Nunca hay necesidad de documentación externa para un comando si inviertes un poco de tiempo en describir el comando en el código.

La documentación no se escribirá sola (desafortunadamente) pero si inviertes un mínimo mientras creas tus comandos, los usuarios estarán eternamente agradecidos ya que pondrás todos los documentos bajo un mismo techo.

Escribe los documentos en tu clase como comentarios, usando el formato PHPDoc. Para profundizar más, consulta el manual de CLI.

Ejecutando wp help site-info obtendrás una lista y descripción de los subcomandos, y si buscas en el código, verás de dónde viene. Se explica por sí mismo.

Para más detalles sobre la versión, ejecuta wp help site-info version y obtendrás también detalles sobre las opciones.

Piensa en tus usuarios, en todos

Por supuesto, si estás desarrollando un widget de emoticonos, añadir compatibilidad con WP-CLI no suena como la jugada perfecta.

Sin embargo, cualquier plugin utilizado u orientado a desarrolladores y administradores se beneficiará enormemente de WP-CLI.

Los usuarios podrán encadenar comandos, escribir scripts bash y, en general, hacer más cosas de forma más rápida y sencilla.

Esto se traduce en mejores críticas, usuarios más satisfechos, más usuarios y, al final, más dinero para ti, independientemente del modelo de monetización que tengas en marcha.

¿Te gustó este artículo? ¡Ni te imaginas lo que te estás perdiendo en YouTube!