Herramientas para escribir mejor código de WordPress: Composer

Aunque creo que el título de esta serie y los artículos de cada uno son lo suficientemente claros, hay otras cosas que pretendo hacer con esta serie en contraste con las otras series que he escrito hasta este momento.

Específicamente, dos de las cosas que estoy tratando de hacer son dos:

1. mantener cada artículo relativamente sucinto (en comparación con cómo han sido los artículos anteriores),
2. concéntrese en una cosa a la vez y mantenga la descripción breve.

Dado que este es contenido de membresía, no me importa que sea un poco más largo de lo habitual, pero tampoco quiero que sea tan largo que sea difícil de seguir. Prefiero que sea una lectura corta con algo práctico que puedas implementar después de leer cada publicación.

Y una de las cosas que ayuda mucho a escribir un mejor código de WordPress es Composer.

Mejor código de WordPress con Composer

Si has leído este blog durante algún tiempo, sabrás que soy fanático de Composer (sin embargo, estoy lejos de ser la única persona que trabaja en WordPress que lo es).

Y aunque he escrito algo de material al respecto, no he escrito algo con el objetivo específico de ponerlo en marcha al final de la lectura de un solo artículo breve.

En ese momento, necesitaremos hacer algunos compromisos: a saber, proporcionaré un archivo de configuración de muestra junto con una forma de organizar el directorio de su complemento. Luego, en la próxima publicación, explicaré algunas de las características de Composer.

¿Qué es Compositor?

Primero, es importante entender qué es Composer. Y es fácil recitar la definición como se indica en el sitio, ¿no es así? Es un administrador de dependencias para PHP.

Pero primero, ¿qué es una dependencia?

Para algunos, sin embargo, plantea algunas preguntas:

• ¿Qué es una dependencia?
• ¿Por qué necesito administrarlos?

Y si profundiza un poco más, es posible que descubra que es un administrador de paquetes, y esto simplemente plantea las mismas preguntas, excepto que simplemente reemplaza "dependencia" con "paquete", y está de vuelta donde comenzó.

Así que haré lo que pueda para dejar esto lo más claro posible:

Una dependencia, o un paquete, una pieza de software que usa su código. Puede ser algo en lo que se base para la funcionalidad durante el tiempo de ejecución, como una forma de realizar solicitudes HTTP, o puede ser una biblioteca para convertir matrices a XML.

Composer facilita la inclusión de estos paquetes particulares en su biblioteca al permitirle:

• descargue e incluya el paquete en su complemento,
• carga automáticamente su complemento durante el tiempo de ejecución,
• haga que sea fácil para su complemento crear una instancia o llamar al complemento según sea necesario.

Esto significa que no tenemos que ensuciar los directorios de nuestro código base con una gran cantidad de archivos agregados manualmente y significa que no tenemos el uso de include o require por todas partes.

Estos tendrán su lugar, del cual hablaré en la próxima publicación, pero no necesitarán instalarse automáticamente. En cambio, Composer los administrará. Por lo tanto, el administrador de dependencias forma parte de su propósito.

Ahora que lo tienes instalado, tienes algo de contexto.

Usando el compositor

Escribir esta sección en particular es algo difícil porque todos tenemos necesidades diferentes, ¿verdad? Pero al menos, todos podemos aprovechar un cargador automático.

Eso es algo que todos podemos usar.

Así que esto es lo que haré:

1. Configuraré un directorio básico de complementos,
2. Cree los archivos necesarios para manejar el complemento,
3. Configure un archivo Composer simple,
4. Ejecutalo

Y luego te dejaré ver los resultados. Podemos ingresar a bibliotecas de terceros u otras características en una publicación futura (o en una serie futura, en realidad).

Pero al menos, esto le mostrará cómo usar Composer para definir un cargador automático para que pueda concentrarse en escribir código y no en preguntarse si las clases están incluidas.

El directorio de complementos

Generalmente estructuro mis complementos así:

• hay un archivo de arranque leído por WordPress,
• hay un  directorio src en el que se guardan todos los directorios y archivos PHP,
• hay un  directorio de activos de nivel superior donde se guardan las imágenes, los archivos JavaScript y los archivos Sass,
• y hay una carpeta de proveedores creada por Composer para albergar las dependencias y el cargador automático.

De vez en cuando puede haber alguna otra carpeta extraña como una carpeta inc o lib, pero eso es muy irregular en este momento en el tipo de trabajo que hago. Y por eso, no me voy a preocupar por eso en este post.

En cambio, mi directorio se parece a esto.

Falta el  directorio de proveedores porque todavía no he creado un archivo Composer que se use para ejecutar. Pero eso lo veremos antes del final del post.

Archivos de ejemplo

Configuremos un archivo de muestra en el complemento. Y cuando digo muestra, también quiero decir simple.

Este archivo va a tener un único propósito: imprimir un mensaje en el tablero cuando inicie sesión en WordPress.

Sin embargo, recuerde que el propósito de esto no es mostrar cómo escribir un complemento con una buena arquitectura. En cambio, es para mostrar cómo generar un cargador automático para que los archivos del complemento se generen automáticamente.

Entonces, el arranque del complemento se ve así :

<?php
/**
 * The plugin bootstrap file
 *
 * This file is read by WordPress to generate the plugin information in the plugin
 * admin area. This file also includes all of the dependencies used by the plugin,
 * registers the activation and deactivation functions, and defines a function
 * that starts the plugin.
 *
 * @since             0.1.0
 * @package           SamplePlugin
 *
 * @wordpress-plugin
 * Plugin Name:       Sample Plugin
 * Description:       A sample plugin used for a blog post.
 * Version:           0.1.0
 * Author:            Tom McFarlin
 * Author URI:        https://tommcfarlin.com
 * License:           GPL-3.0+
 * License URI:       http://www.gnu.org/licenses/gpl-3.0.txt
 */

namespace SamplePlugin;

use SamplePluginMessenger;

// This file called directly.
defined('WPINC') || die;

// Include the autoloader.
require_once __DIR__. '/vendor/autoload.php';

// Start the machine.
(new Messenger())->start();

Y el archivo específicamente responsable de mostrar el mensaje se ve así :

<?php

namespace SamplePlugin;

class Messenger
{
    /**
     * Subscribers the `adminNotices` function to the admin_notices hook in WordPress.
     */
    public function start()
    {
        add_action('admin_notices', [$this, 'adminNotices']);
    }

    /**
     * Displays the contents of the `message.html` file into the adminitrative notices
     * area on the dashboard whenever the plugin is active.
     */
    public function adminNotices()
    {
        if ('dashboard' !== get_current_screen()->id) {
            return;
        }

        include_once dirname(__FILE__). '/Admin/Views/message.html';
    }
}

Y si tiene curiosidad sobre el archivo HTML, también es simple :

<div class="notice notice-success is-dismissible">
    <p>This is a message from the <strong>Sample Plugin</strong></p>
</div>

Te dije que era sencillo.

El archivo de configuración del compositor

Este archivo en particular puede ser tan simple o tan complicado como sea necesario. Para esta publicación, lo mantendremos simple. El objetivo de esta publicación es simplemente darle un nombre, una descripción, una licencia, los autores y luego cómo configurar el cargador automático.

Echa un vistazo aquí y luego te explicaré lo que ves justo debajo:

{
    "name": "tommcfarlin/sample-plugin",
    "description": "A sample plugin used for a blog post.",
    "type": "wordpress-plugin",
    "license": "GPL-3.0-or-later",
    "authors": [
      {
        "name": "Tom McFarlin",
        "email": "tom@tommcfarlin.com",
        "homepage": "https://tommcfarlin.com"
      }
    ],
      "autoload": {
        "psr-4": {
          "SamplePlugin": "src/"
        }
      }
  }

Primero, el nombre, la descripción, el tipo y la licencia deben ser lo suficientemente fáciles de seguir. El área del autor también es sencilla.

La carga automática es el área que nos preocupa en este momento. Debería ser bastante claro.

En resumen, tenemos una directiva para PSR4 sobre  la que puede leer más y luego dónde se encuentra un espacio de nombres. Entonces, en el ejemplo anterior, cualquier cosa en el espacio de nombres SamplePlugin se encuentra en src. 

Esto es lo que le dice al cargador automático dónde buscar ciertos archivos. Y en nuestro caso, solo buscará la  clase Messenger.

Compositor en ejecución

Ahora que hemos cubierto los conceptos básicos del archivo de configuración de Composer, es hora de ejecutarlo. Recuerde que su directorio de complementos debería verse así:

En tu terminal, ingresa el siguiente comando :

Y deberías ver algo como esto:

Suponiendo que todo haya ido bien, debería poder iniciar sesión en WordPress y activar el complemento.

Verlo todo junto

Una vez que se activa el complemento, puede navegar al panel de control de su sitio. Allí, debería ver un aviso de descartable que se ve exactamente como vimos al comienzo de la publicación:

Si has llegado hasta aquí, ¡entonces estás listo para empezar! De lo contrario, verifique dos veces su sintaxis para asegurarse de que todo esté bien. Si algo está mal, es probable que no haya podido llegar tan lejos y, asumiendo que tiene configuradas las constantes de depuración básicas, es probable que vea dónde existe el problema.

esto no es todo

Hay mucho más en Composer, y recomiendo leer la documentación correspondiente. Cubriré algo de esto cuando mire las herramientas que planeo cubrir más adelante en esta serie pero, por ahora, recomiendo familiarizarse con algunas de las convenciones.

¡Vaya! Y no recomiendo consultar el directorio de proveedores en su repositorio. Eso puede convertirse en un directorio enorme más tarde y puede socavar el propósito completo de Composer.

En el próximo post, voy a hablar de por qué. Algunas personas lo hacen, y está bien, y yo lo he hecho antes, pero es importante ser juicioso cuando lo haces.

Errar por el lado de no hacerlo. Y te explico por qué en el próximo post.