# « Migrer un bloc ACF vers block.json : ce que change ACF Blocks 2.0 »

> acf_register_block_type a longtemps suffi. Depuis ACF Blocks 2.0, un fichier block.json ouvre l'accès à des fonctionnalités natives auparavant hors de portée.

- Auteur : Clément Hadrot
- Publié le : 2022-12-20
- Mis à jour le : 2022-12-20
- Catégorie : Blocs Gutenberg
- URL : https://wpmoderne.dev.wordpress-developpement.fr/blocs/migrer-bloc-acf-vers-block-json-acf-blocks-2/

## L’essentiel

- block.json reste compatible avec un rendu PHP via render_template
- Les variations et le support natif deviennent enfin accessibles
- La migration se fait champ par champ, sans réécrire les templates

Un développeur travaillant depuis des années sur des sites vitrines pour des artisans locaux utilisait systématiquement `acf_register_block_type()` pour ses blocs sur mesure, une fonction qui avait fait ses preuves projet après projet. Une mise à jour d'Advanced Custom Fields a changé la donne : la version 2.0 d'ACF Blocks a introduit la prise en charge native du format `block.json`, le même format utilisé par les blocs natifs de WordPress, ouvrant l'accès à des fonctionnalités jusque-là hors de portée pour un bloc ACF classique.

Cette migration n'oblige pas à repenser toute la logique déjà en place : les templates PHP existants restent largement réutilisables, et l'effort porte principalement sur le déplacement de la déclaration du bloc vers un fichier dédié, dans un format désormais partagé avec l'ensemble de l'écosystème de blocs WordPress.

## Ce que acf_register_block_type faisait bien

La fonction historique reste fonctionnelle et continue d'être prise en charge : elle enregistre un bloc dynamique en une seule fois, avec un nom, une icône, une catégorie et un template PHP de rendu, sans nécessiter de build JavaScript ni de fichier de configuration séparé.

```
acf_register_block_type( array(
    'name'            => 'temoignage-artisan',
    'title'           => __( 'Témoignage artisan' ),
    'render_template' => 'blocks/temoignage-artisan.php',
    'category'        => 'formatting',
    'icon'            => 'admin-comments',
) );
```

## Ce que block.json apporte en plus

En migrant vers un fichier `block.json`, le même bloc profite désormais des variations, du support natif pour l'alignement ou les couleurs déclaré via la propriété `supports`, et surtout d'une meilleure interopérabilité avec les outils qui interrogent le registre standard de blocs, comme les scripts d'audit basés sur `WP_Block_Type_Registry`.

```
{
  "name": "acf/temoignage-artisan",
  "title": "Témoignage artisan",
  "category": "formatting",
  "icon": "admin-comments",
  "acf": {
    "renderTemplate": "temoignage-artisan.php"
  },
  "supports": {
    "align": true,
    "color": { "background": true }
  }
}
```

> L'essentiel à retenir : block.json reste compatible avec un rendu PHP via render_template ; Les variations et le support natif deviennent enfin accessibles ; La migration se fait champ par champ, sans réécrire les templates

## Enregistrer le bloc depuis ce fichier

Côté PHP, l'enregistrement se fait désormais via la fonction native `register_block_type()`, la même utilisée pour n'importe quel bloc WordPress, en pointant simplement vers le dossier contenant `block.json`.

```
function mon_agence_enregistrer_bloc_acf() {
    register_block_type( __DIR__ . '/blocks/temoignage-artisan' );
}
add_action( 'init', 'mon_agence_enregistrer_bloc_acf' );
```

Le template PHP référencé par `renderTemplate` continue de recevoir les mêmes variables globales qu'auparavant, `$block`, `$content` et `$is_preview`, ce qui signifie que la logique métier déjà écrite dans ces fichiers n'a, dans la majorité des cas, aucune raison de changer.

## Les champs ACF restent inchangés

Un point rassurant pour qui craint une migration lourde : les groupes de champs ACF associés au bloc via l'emplacement de règles ne nécessitent aucune modification. La migration ne concerne que la déclaration du bloc lui-même, pas la structure des champs personnalisés qui restent définis exactement comme avant, dans l'interface d'administration d'ACF ou via un fichier de synchronisation JSON déjà en place.

## Une checklist de migration progressive

- Créer le fichier block.json à côté du template PHP existant, sans encore le supprimer.
- Remplacer l'appel à acf_register_block_type par register_block_type pointant vers ce dossier.
- Vérifier dans l'éditeur que le bloc s'insère et se rend normalement, sans changement visuel inattendu.
- Ajouter progressivement les propriétés supports pertinentes une fois la base migrée validée.

> Une migration réussie vers block.json ne devrait produire strictement aucune différence visible pour le rédacteur avant l'ajout volontaire d'une nouvelle fonctionnalité comme une variation ou un support de couleur.

## Quand ne pas migrer tout de suite

Pour un site avec une dizaine de blocs ACF stables, sans besoin identifié de variations ni de support natif supplémentaire, la migration reste un choix d'opportunité plutôt qu'une urgence : acf_register_block_type continue de fonctionner sans dépréciation annoncée. La migration devient en revanche pertinente dès qu'un nouveau bloc doit proposer plusieurs variantes d'insertion, ou dès qu'un audit du registre de blocs doit pouvoir recenser ces blocs au même titre que les blocs natifs.

## Notre verdict

ACF Blocks 2.0 ne remplace pas la logique de rendu PHP qui a fait le succès des blocs ACF depuis des années, il l'enrichit d'un format de déclaration partagé avec le reste de l'écosystème WordPress. Pour un développeur déjà à l'aise avec acf_register_block_type, la migration se limite à un déplacement de déclaration, pas à une réécriture, ce qui rend ce chantier bien moins intimidant qu'il n'y paraît au premier abord.