Cómo renderizar bloques en un tema clásico de WordPress con do_blocks() en PHP

Desde la llegada del editor de bloques a WordPress, muchas funciones se han modernizado. Sin embargo, si trabajas con un tema clásico o híbrido, puede que te encuentres con la necesidad de renderizar contenido en bloques desde PHP, algo que parece exclusivo del editor visual… pero no lo es.

Aquí entra en juego do_blocks(): una función poco conocida, pero extremadamente útil para integrar bloques de Gutenberg directamente desde el código PHP. Ideal para temas clásicos, desarrollos a medida o integraciones con ACF, WooCommerce y más.

En este artículo aprenderás cómo funciona, cuándo usarla y cómo sacarle el máximo partido con ejemplos prácticos y buenas prácticas.

¿Qué es do_blocks() y para qué sirve?

do_blocks() es una función del núcleo de WordPress que permite procesar y renderizar bloques desde PHP. Se introdujo en WordPress 5.0 junto al editor Gutenberg y está pensada para convertir el contenido guardado con bloques (normalmente como HTML enriquecido con comentarios especiales) en HTML real, totalmente funcional.

¿Cómo funciona internamente?

Cuando creas contenido con el editor de bloques, WordPress lo guarda así:

<!-- wp:paragraph -->
<p>¡Hola mundo!</p>
<!-- /wp:paragraph -->

Eso por sí solo es simplemente HTML plano. Aquí entra do_blocks(), que interpreta ese contenido, procesa los bloques involucrados y devuelve su versión final con estilos, atributos y funcionalidades completas.

Sintaxis básica

Puedes usarlo fácilmente en tus plantillas clásicas de WordPress:

$contenido = '<!-- wp:paragraph --><p>¡Hola mundo!</p><!-- /wp:paragraph -->';
echo do_blocks( $contenido );

Esta simple llamada convierte el contenido en bloque en el HTML final que verás en pantalla, igual que si lo hubieras insertado desde el editor visual.

¿Dónde encontrar la estructura del bloque?

Si necesitas copiar la estructura de un bloque ya creado en Gutenberg:

1. Abre el editor de bloques.
2. Haz clic en los tres puntos (esquina superior derecha).
3. Elige la opción “Editor de código”.

Desde ahí puedes copiar el bloque completo para adaptarlo en tu código PHP. Puedes seguir los pasos que se muestran en esta animación para verlo más claro.

Consejo: Puedes generar bloques dinámicos basados en campos personalizados u opciones del tema, algo que veremos en los próximos apartados.

Renderizar bloques con PHP paso a paso

Aunque do_blocks() es una función sencilla, conviene entender bien cómo se integra dentro de una plantilla clásica o híbrida para sacarle todo el partido.

Aquí te explico paso a paso cómo usarla en un entorno real.

1. Escribe el bloque como string

El primer paso es tener el bloque escrito como un texto con su sintaxis de Gutenberg. Por ejemplo, un párrafo básico se vería así:

$bloque = '<!-- wp:paragraph --><p>¡Hola desde BUBUKU!</p><!-- /wp:paragraph -->';

Este contenido es el que normalmente se genera en el editor de bloques y que puedes copiar desde el “Editor de código” como vimos antes.

2. Procesa el bloque con do_blocks()

Una vez tengas el string, simplemente pásalo a la función:

echo do_blocks( $bloque );

Y listo. WordPress interpretará ese bloque y lo mostrará con el HTML y estilos correspondientes, tal como si se hubiera insertado desde el editor visual.

3. Comprobación previa con has_blocks()

Antes de ejecutar do_blocks(), es buena práctica verificar si el contenido realmente contiene bloques:

if ( has_blocks( $bloque ) ) {
    echo do_blocks( $bloque );
}

Esto evita errores y mejora el rendimiento si el contenido no necesita ser procesado.

Con esto ya tenemos una base clara para ver el siguiente punto cómo adaptar un bloque dinámicamente, por ejemplo, para renderizar formularios o integrar ACF.

Ejemplo práctico con bloques personalizados y ACF

Supongamos que estás trabajando en un tema híbrido y necesitas mostrar un formulario de HubSpot que ya está integrado como un bloque personalizado en Gutenberg. En lugar de duplicar código o lógica, puedes usar do_blocks() para reutilizar ese bloque directamente desde PHP.

Escenario real

En uno de nuestros proyectos, teníamos un bloque personalizado creado con ACF para insertar formularios de HubSpot. Puesto que el formulario estaba bien configurado en el CMS, decidimos no duplicar lógica y renderizarlo con do_blocks() así:

$block_hubspot = '<!-- wp:prefix/hubspot {
    "name": "prefix/hubspot",
    "data": {
        "_prefix_hubspot_id_form": "formulario-id",
        "_prefix_hubspot_lazy": "0"
    },
    "mode": "preview",
    "className": "is-style-boxed"
} /-->';
echo do_blocks( $block_hubspot );

Este código muestra directamente el bloque ya existente, respetando su configuración y estilos.

Adaptar dinámicamente con valores desde ACF

¿Y si necesitas que ese formulario cambie según el contenido? Puedes usar sprintf() para insertar dinámicamente valores obtenidos de campos personalizados, como este:

$form_id = get_field('_form_id', $post_id);
$block_hubspot = sprintf('<!-- wp:prefix/hubspot {
    "name": "prefix/hubspot",
    "data": {
        "_prefix_hubspot_id_form": "%s",
        "_prefix_hubspot_lazy": "0"
    },
    "mode": "preview",
    "className": "is-style-boxed"
} /-->', sanitize_text_field($form_id));
echo do_blocks( $block_hubspot );

Así mantienes la lógica de configuración en el CMS, pero adaptas su comportamiento desde el código, lo que te da flexibilidad sin perder control.

¿Dónde ver la key exacta del campo?

A veces ACF muestra el nombre del campo y otras veces su key (como field_xxx). Para identificarlo bien, puedes consultar nuestro artículo donde lo explicamos paso a paso cómo identificar la Clave de un campo ACF.

Cómo integrar do_blocks() con WooCommerce

Uno de los usos más potentes de do_blocks() es poder mostrar bloques de productos de WooCommerce desde PHP, sin depender exclusivamente del editor de bloques. Esto es ideal si estás montando secciones personalizadas (como un carrusel de productos, una landing a medida, o una sección dinámica) y quieres reutilizar los bloques nativos de WooCommerce.

Ventajas en un tema clásico, bloques o patrones

• Reutilizas los bloques existentes (imagen, título, precio, botón…).
• No duplicas estilos ni estructuras HTML.
• Puedes montar layouts personalizados desde PHP.
• Ganas flexibilidad sin romper la lógica de WooCommerce.

Ejemplo con foreach y do_blocks()

Supongamos que tienes una lista de IDs de productos que quieres mostrar. Este fragmento lo renderiza como un grid:

$render_block = '';
foreach ( $posts as $product_id ) :
    if ( wc_get_product( $product_id ) ) {
        global $post;
        $original_post = $post;
        $post = get_post( $product_id );
        setup_postdata( $post );
        $image_block = sprintf(
            '<!-- wp:woocommerce/product-image {"productId":%d} /-->',
            $product_id
        );
        $title_block = sprintf(
            '<h3 class="has-text-align-center wp-block-post-title has-medium-font-size">%s</h3>',
            get_the_title( $product_id )
        );
        $price_block = sprintf(
            '<!-- wp:woocommerce/product-price {"productId":%d,"fontSize":"small","textAlign":"center"} /-->',
            $product_id
        );
        $button_block = sprintf(
            '<!-- wp:woocommerce/product-button {"productId":%d,"fontSize":"small","align":"center"} /-->',
            $product_id
        );
        $render_block .= '<li class="product type-product">' .
            do_blocks( $image_block . $title_block . $price_block . $button_block ) .
            '</li>';
        $post = $original_post;
        wp_reset_postdata();
    }
endforeach;
echo '<ul class="wp-block-post-template is-layout-grid">' . $render_block . '</ul>';

Este código renderiza cada producto con su imagen, título, precio y botón de compra usando los bloques nativos de WooCommerce, todo desde PHP.

Ideal para layouts personalizados

Puedes usar esta técnica en sliders, tabs, bloques destacados o cualquier plantilla que necesite productos sin tener que recrear los bloques manualmente. Reutilizas lo que ya funciona y se mantiene con WooCommerce.

Buenas prácticas y consideraciones técnicas

Aunque do_blocks() es muy potente, usarlo en un tema híbrido requiere prestar atención a ciertos detalles para evitar problemas de rendimiento, seguridad o diseño. Aquí tienes una guía con las mejores prácticas para integrarlo correctamente.

1. Comprueba si el contenido realmente tiene bloques

Antes de procesar cualquier contenido con do_blocks(), asegúrate de que contiene bloques. Usa la función has_blocks() para verificarlo:

if ( $contenido && has_blocks( $contenido ) ) {
    echo do_blocks( $contenido );
}

Esto evita procesar contenido plano o vacío innecesariamente.

2. Sanitiza el contenido si proviene de campos personalizados

Si el contenido viene de campos ACF o de entradas de usuarios, no des por hecho que es seguro. Asegúrate de limpiarlo con funciones como wp_kses_post:

$contenido = wp_kses_post( get_field( 'bloques_editor', $post_id ) );

O usa sanitize_text_field() si trabajas con cadenas de texto simples.

3. Controla el diseño desde el tema

Permitir que los bloques se rendericen desde campos personalizados puede afectar la consistencia visual. Para evitar sorpresas:

• Restringe los bloques disponibles con el filtro allowed_block_types_all.
• Envuelve el contenido en contenedores con clases específicas (<div class=»bloque-contenido»>) para poder aplicar estilos.
• Define estilos base desde CSS o theme.json para mantener la coherencia.

4. Piensa en el rendimiento

Renderizar muchos bloques dinámicos en bucles o plantillas complejas puede ralentizar la carga. Algunos consejos:

• Si el contenido no cambia, usa transients o caché de fragmentos.
• Evita renderizar bloques dentro de foreach extensos sin necesidad.

5. Usa funciones de WordPress nativas

No intentes reinventar la rueda procesando el contenido a mano. do_blocks() ya incluye los filtros y estructuras necesarias para renderizar correctamente los bloques como lo haría el editor visual.

Estas buenas prácticas te ayudarán a mantener tu código limpio, eficiente y alineado con el funcionamiento interno de WordPress.

Ventajas y desventajas de usar do_blocks()

Usar do_blocks() en un tema clásico de WordPress abre la puerta a una integración progresiva con el editor de bloques, pero también conlleva ciertas consideraciones.

Aquí tienes una comparativa clara para ayudarte a decidir cuándo y cómo usarlo:

Como ves, do_blocks() es una herramienta útil para modernizar tu flujo de trabajo en temas clásicos, pero requiere una implementación cuidadosa.

Otras alternativas para renderizar bloques desde PHP

Aunque do_blocks() es la forma más directa y flexible de renderizar contenido en bloques desde PHP, no es la única opción. WordPress ofrece otras funciones y enfoques que pueden resultarte útiles según el contexto o el tipo de contenido que estés tratando.

apply_filters( ‘the_content’, $contenido )

Esta función procesa el contenido como si estuviera dentro de the_content(), aplicando filtros como shortcodes, oEmbeds… y también ejecuta do_blocks() internamente si detecta bloques.

echo apply_filters( 'the_content', $contenido );

Ventaja: Muy útil si quieres aprovechar los filtros de plugins que actúan sobre el contenido.

Inconveniente: Procesa más de lo necesario si solo quieres renderizar bloques.

render_block() (bloques individuales como arrays)

Ideal si estás generando bloques de forma programática. Tienes que pasarle un array con los atributos del bloque:

$block = array(
    'blockName'    => 'core/paragraph',
    'attrs'        => array(),
    'innerHTML'    => '<p>Este es un párrafo renderizado con PHP.</p>',
    'innerBlocks'  => [],
);
echo render_block( $block );

Ventaja: Máximo control sobre cada bloque.

Inconveniente: Requiere construir la estructura manualmente, no apto para contenido complejo o externo.

block_template_render()

Si trabajas con temas híbridos o plantillas de bloques completas, esta función permite renderizar plantillas de tipo block-template. Más pensada para entornos FSE.

Ventaja: Perfecta para sitios basados en bloques.

Inconveniente: No aplicable a temas clásicos si no usas plantillas de bloques.

Otras opciones: shortcodes o widgets personalizados

En casos donde no necesitas bloques visuales complejos, crear un shortcode o un widget clásico puede ser suficiente, especialmente para funcionalidades simples o repetitivas.

Como ves, la elección depende de tus necesidades: do_blocks() es ideal para contenido estructurado con Gutenberg; render_block() para control avanzado; y apply_filters() si buscas compatibilidad con plugins o contenido tradicional.

Claves finales para usar do_blocks() con éxito

Después de ver cómo funciona do_blocks(), sus ventajas y las distintas formas de usarlo, es buen momento para recapitular los puntos esenciales que te ayudarán a aplicarlo correctamente en tus desarrollos WordPress.

Úsalo cuando quieras renderizar bloques fuera del editor

do_blocks() es perfecto cuando necesitas mostrar bloques en ubicaciones no gestionadas directamente desde el editor visual, como:

• Campos personalizados con contenido de bloques.
• Plantillas de tema personalizadas.
• Integraciones con WooCommerce, formularios o lógica condicional.

Verifica siempre con has_blocks()

No proceses contenido plano innecesariamente. Asegúrate de que el contenido contiene bloques antes de pasarlo a do_blocks():

if ( has_blocks( $contenido ) ) {
    echo do_blocks( $contenido );
}

Sanitiza el contenido dinámico

Si los datos vienen de ACF u otras fuentes externas, asegúrate de aplicar funciones como sanitize_text_field() o wp_kses_post() para mantener la seguridad del sitio.

Reutiliza bloques existentes

En lugar de duplicar componentes o lógica, puedes reutilizar bloques de Gutenberg ya existentes como los de WooCommerce, ACF o cualquier bloque personalizado.

Esto te ayuda a mantener un diseño coherente y un código más limpio y mantenible.

Piensa a largo plazo

do_blocks() te permite modernizar tu proyecto poco a poco, sin necesidad de cambiar todo el tema. Es ideal si gestionas un sitio heredado o híbrido, y quieres introducir bloques sin hacer una migración completa al Full Site Editing.

Preguntas frecuentes sobre do_blocks()