Cómo migrar un widget de WordPress a un bloque de Gutenberg

Hace varios años desarrollé dos plugins para WordPress: JS Archive List y JS Categories List. Ambos nacieron cuando los widgets de WordPress se desarrollaban prácticamente por completo en PHP: creabas una clase, extendías WP_Widget, generabas el formulario de configuración y, finalmente, renderizabas el HTML. Funcionaba bastante bien, pero WordPress ha cambiado mucho desde la llegada de Gutenberg. Así que decidí migrar ambos plugins para que pudieran utilizarse como un bloque de Gutenberg. En el caso de JS Categories List, ocurrió desde la versión 4.0 y en JS Archive List desde la versión 5.0, manteniendo además el widget anterior en PHP por compatibilidad con instalaciones existentes.

Lo interesante de esta migración no fue solo aprender a crear un bloque. También me hizo ver, de una forma diferente, cómo ha evolucionado WordPress.

De widgets en PHP a una interfaz en React

Un widget clásico de WordPress normalmente hacía casi todo en PHP. Por ejemplo, teníamos algo parecido a esto:

class My_Widget extends WP_Widget {

    public function widget( $args, $instance ) {
        // Obtener datos.
        // Generar HTML.
        // Mostrar el widget.
    }

    public function form( $instance ) {
        // Formulario de configuración.
    }
}

El formulario que veía el administrador, la configuración y el HTML final estaban muy ligados entre sí. Con Gutenberg la separación es diferente. Ahora puedes tener PHP encargándose de los datos y del renderizado mientras que el editor utiliza JavaScript y React para construir la interfaz de configuración.

Por esta razón, siento que WordPress cada vez se siente más como un CMS que ofrece servicios y APIs en PHP, mientras que diferentes interfaces consumen esos servicios.

Gutenberg es probablemente el mejor ejemplo, porque el editor trabaja con entidades como posts, páginas, usuarios o términos mediante @wordpress/core-dataQue internamente puede procesar los datos mediante las APIs de WordPress.

PHP no desapareció. Simplemente ya no tiene que encargarse de toda la interfaz.

¿Cómo comenzar un bloque de Gutenberg?

WordPress posee una herramienta oficial llamada @wordpress/create-block que genera la estructura inicial de un plugin con un bloque, incluyendo JavaScript, PHP, CSS y la configuración necesaria para compilar todo. Puedes crear uno ejecutando:

npx @wordpress/create-block@latest my-block --namespace=my-plugin

Luego:

cd my-block
npm start

Aunque estés migrando un plugin existente, te recomiendo ejecutar este comando al menos una vez. Es una forma sencilla de entender cuál es la estructura recomendada actualmente por WordPress.

Entre los archivos encontrarás uno particularmente importante:

block.json

Este archivo contiene la definición del bloque: nombre, atributos, scripts, estilos y demás metadatos. Por ejemplo:

{
    "apiVersion": 3,
    "name": "my-plugin/archive-list",
    "title": "Archive List",
    "category": "widgets",
    "attributes": {
        "showCount": {
            "type": "boolean",
            "default": false
        }
    }
}

WordPress actualmente recomienda registrar los bloques utilizando esta metadata y register_block_type() Desde PHP se hace asi:

add_action( 'init', function() {
    register_block_type( __DIR__ . '/build' );
} );

Con eso PHP conoce nuestro bloque y WordPress puede cargar los scripts y estilos necesarios.

La configuración del bloque de Gutenberg ahora vive en React

En un widget clásico, las opciones se construían con inputs HTML generados en PHP. En un bloque de Gutenberg puedes crear esa interfaz con los componentes que ya ofrece WordPress. Por ejemplo:

import { InspectorControls } from '@wordpress/block-editor';
import {
    PanelBody,
    ToggleControl
} from '@wordpress/components';

export default function Edit({ attributes, setAttributes }) {
    return (
        <InspectorControls>
            <PanelBody title="Options">
                <ToggleControl
                    label="Show post count"
                    checked={ attributes.showCount }
                    onChange={ ( value ) =>
                        setAttributes({ showCount: value })
                    }
                />
            </PanelBody>
        </InspectorControls>
    );
}

De esta forma, Gutenberg se encarga de gran parte de la experiencia del editor y nosotros solo debemos definir qué opciones necesita nuestro bloque.

En mis plugins esto reemplazó buena parte de los formularios que antes tenía que generar manualmente desde PHP.

Consumir los datos de WordPress desde el bloque de Gutenberg

Otra parte interesante es que no necesariamente tienes que crear tus propios endpoints para obtener información que WordPress ya conoce. Desde el editor puedes consultar entidades utilizando core-data. Por ejemplo, para obtener páginas puedes utilizar:

import { useEntityRecords } from '@wordpress/core-data';

const { records, isResolving } = useEntityRecords(
    'postType',
    'page'
);

WordPress se encarga de resolver la petición, de mantener los datos en su store y de entregarlos al componente. En un plugin como JS Categories List, el mismo concepto permite trabajar con taxonomías y categorías desde la interfaz del bloque, sin tener que imprimir previamente toda esa información en el HTML generado por PHP.

Eso también tiene otra ventaja, la nueva versión de mis plugins puede leer la información dinámicamente y cargar JavaScript y CSS solamente cuando realmente existe un bloque o widget en la página, en lugar de cargar recursos innecesariamente en todo el sitio.

No tienes que reescribir todo tu PHP

Esta fue una de las cosas que pensé inicialmente que serían más complicadas.

Migrar a un bloque de Gutenberg no significa necesariamente convertir todo el plugin a JavaScript. Puedes crear un bloque dinámico y continuar renderizando su contenido desde PHP, por ejemplo, block.json puede indicar:

{
    "render": "file:./render.php"
}

Y dentro de render.php Puedes reutilizar buena parte de la lógica que ya tenía tu antiguo widget, permitiendo tener una migración más progresiva:

<?php

$show_count = $attributes['showCount'] ?? false;

echo my_old_archive_render_function(
    $show_count
);

La interfaz del editor puede estar hecha con React, mientras que el frontend todavía utiliza funciones PHP que llevan años funcionando. Los bloques dinámicos están diseñados precisamente para casos donde el contenido debe calcularse al momento de renderizar la página, y WordPress permite hacerlo mediante un archivo render.php o un render_callback.

En mi caso, esto fue bastante útil porque no tenía sentido reescribir código estable solamente por utilizar Gutenberg.

Mantener el antiguo widget por retrocompatibilidad

También decidí no eliminar de inmediato los widgets anteriores. Tanto JS Archive List como JS Categories List mantienen una versión legacy en PHP para instalaciones que todavía la utilizan, mientras que el desarrollo nuevo está enfocado en el bloque Gutenberg.

Creo que esta es una buena estrategia para plugins que llevan muchos años publicados. Puedes modernizar el código sin afectar las instalaciones de los usuarios que configuraron el widget hace más de cinco años. Ya con el tiempo puedes dejar la implementación antigua únicamente en modo de mantenimiento.

WordPress es bastante diferente ahora

Después de hacer esta migración, creo que desarrollar para WordPress actualmente se parece bastante menos al WordPress con el que comencé hace años.

PHP continúa siendo una parte fundamental, pero ahora tenemos una capa de APIs, bases de datos, componentes y una interfaz escrita en React.

En lugar de pensar:

“Tengo que crear una página PHP para configurar esto.”

Cada vez pienso más:

“¿Qué datos o servicios debe proporcionar WordPress y cómo los va a consumir la interfaz?”

Ese cambio de mentalidad hace que Gutenberg tenga mucho más sentido. Así que si tienes un plugin antiguo basado en WP_Widget, no necesitas reescribirlo por completo de una vez. Puedes comenzar creando un bloque, mover las opciones del formulario a React y reutilizar tu código PHP para el renderizado. Luego moderniza el resto poco a poco.

Para empezar y entender cómo funciona todo, crea primero un bloque vacío con @wordpress/create-block, ejecuta npm start Y comienza a modificarlo. Es probablemente la forma más rápida de dejar de ver Gutenberg como algo extraño y comenzar a verlo simplemente como la nueva interfaz de desarrollo de WordPress.

Happy coding!