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

> Avec block.json, le rendu dynamique se déclare désormais dans un simple fichier render.php. Fini le couplage rigide au render_callback enregistré en PHP.

- Auteur : Clément Hadrot
- Publié le : 2022-09-13
- Mis à jour le : 2022-09-13
- Catégorie : Blocs Gutenberg
- URL : https://wpmoderne.dev.wordpress-developpement.fr/blocs/render-php-block-json-blocs-dynamiques/

## L’essentiel

- Une propriété render qui pointe vers un fichier PHP autonome
- Les variables $attributes, $content et $block prêtes à l'emploi
- Compatible avec l'ancien render_callback pendant la transition

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'essentiel à retenir : Une propriété render qui pointe vers un fichier PHP autonome ; Les variables $attributes, $content et $block prêtes à l'emploi ; Compatible avec l'ancien render_callback pendant la transition

À 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.