render.php dans block.json : la nouvelle génération de blocs dynamiques

Le rendu côté serveur des blocs dynamiques a longtemps reposé sur une callback PHP enregistrée à la main, séparée du reste de la déclaration du bloc. Depuis que block.json s’est généralisé, WordPress propose une alternative plus lisible : la propriété render, qui pointe directement vers un fichier render.php livré avec le bloc. Le résultat est un couplage bien plus naturel entre la définition du bloc et son affichage final.

Cet article détaille comment migrer un bloc dynamique vers cette approche, quelles variables sont disponibles dans render.php, et dans quels cas il reste pertinent de garder un render_callback classique.

Pourquoi préférer render.php à render_callback

Avec l’ancienne méthode, la fonction PHP de rendu était enregistrée via l’argument render_callback de register_block_type(), généralement définie ailleurs dans le plugin, parfois à des centaines de lignes du fichier block.json. Cette séparation rendait la lecture du code plus difficile : pour comprendre comment un bloc s’affiche, il fallait sauter entre plusieurs fichiers sans lien évident.

La propriété render de block.json résout ce problème en colocalisant la déclaration et le rendu :

{
  "apiVersion": 2,
  "name": "wpmoderne/compte-a-rebours",
  "title": "Compte à rebours",
  "category": "widgets",
  "attributes": {
    "dateCible": {
      "type": "string",
      "default": ""
    }
  },
  "render": "file:./render.php"
}

Avec cette syntaxe, WordPress sait qu’il doit inclure render.php chaque fois que le bloc doit être affiché sur le front, sans qu’aucune ligne de PHP supplémentaire ne soit nécessaire dans le fichier principal du plugin.

Les variables disponibles dans render.php

À l’intérieur de render.php, trois variables sont automatiquement injectées par WordPress :

• $attributes : le tableau associatif des attributs du bloc, déjà validé selon les types déclarés dans block.json.
• $content : le contenu HTML des éventuels blocs enfants, dans le cas d’un bloc utilisant InnerBlocks.
• $block : une instance de WP_Block, qui donne accès au contexte du bloc, à son nom, et à des méthodes utiles comme render() pour un rendu récursif.

Voici à quoi ressemble le fichier render.php correspondant au bloc « compte à rebours » déclaré plus haut :

<?php
$date_cible = $attributes['dateCible'] ?? '';
if ( empty( $date_cible ) ) {
    return;
}

$wrapper_attributes = get_block_wrapper_attributes( [
    'data-date-cible' => esc_attr( $date_cible ),
] );
?>
<div <?php echo $wrapper_attributes; ?>>
    <p>Compte à rebours jusqu'au <?php echo esc_html( $date_cible ); ?></p>
</div>

La fonction get_block_wrapper_attributes() mérite d’être soulignée : elle génère automatiquement les classes et attributs liés aux supports déclarés dans block.json (couleur, espacement, alignement), évitant de les recopier à la main comme c’était souvent le cas avec un render_callback écrit rapidement.

Migrer un bloc existant

Pour un bloc qui utilisait déjà render_callback, la migration se fait en trois étapes simples. D’abord, extraire le corps de la fonction PHP dans un nouveau fichier render.php, à la racine du dossier du bloc. Ensuite, remplacer les références à $attributes passé en paramètre de fonction par la variable globale du même nom, disponible directement dans le fichier inclus. Enfin, ajouter la propriété render dans block.json et supprimer l’argument render_callback de l’appel à register_block_type(), qui n’est alors plus nécessaire puisque WordPress lit désormais tout depuis le fichier JSON.

Un point de vigilance : si votre register_block_type() pointait vers le dossier du bloc (et non directement vers block.json), aucune modification supplémentaire n’est requise, WordPress détecte automatiquement render.php une fois la propriété déclarée.

Quand garder un render_callback classique

Le passage à render.php n’est pas obligatoire, et certains cas de figure justifient encore l’ancienne approche :

1. Un bloc dont le rendu dépend fortement d’une classe PHP existante, avec une logique métier déjà bien testée ailleurs dans le plugin.
2. Un bloc généré dynamiquement à partir d’un registre de blocs, où la fonction de rendu est produite par une boucle plutôt qu’écrite littéralement dans un fichier.
3. Un projet legacy où la cohérence avec les autres blocs existants (déjà en render_callback) prime sur la modernisation ponctuelle d’un seul bloc.

Dans la pratique, sur la plupart des projets neufs, render.php devient le choix par défaut : il rapproche le code de rendu de sa déclaration, et facilite grandement la relecture pour un développeur qui découvre le bloc.

Sur nos projets récents, dès qu’un bloc dépasse une vingtaine de lignes de rendu PHP, on l’isole systématiquement dans render.php : le fichier principal du plugin reste lisible même avec quinze ou vingt blocs enregistrés.

Sécuriser le rendu

Que l’on utilise render.php ou render_callback, les mêmes règles de sécurité s’appliquent. Chaque valeur issue de $attributes doit être échappée avant affichage, avec esc_html(), esc_attr() ou esc_url() selon le contexte. Un attribut de type string déclaré dans block.json n’est jamais garanti exempt de contenu malveillant : la validation de type ne protège que contre les erreurs de structure, pas contre l’injection de balises.

Il est également recommandé de vérifier la présence des attributs attendus avant de les utiliser, en particulier lorsque le bloc a pu être créé avec une version antérieure du plugin, où certains attributs n’existaient pas encore.

En résumé

La propriété render de block.json simplifie nettement l’écriture des blocs dynamiques : un seul fichier PHP, colocalisé avec la déclaration du bloc, avec trois variables prêtes à l’emploi et une fonction utilitaire pour gérer les supports automatiquement. Pour tout nouveau bloc dynamique, c’est désormais l’approche à privilégier ; la migration des blocs existants reste simple et peut se faire bloc par bloc, sans urgence particulière.