Développement de bloc Gutenberg personnalisé en React/PHP

Introduction

Depuis l’arrivée de l’éditeur Gutenberg dans WordPress 5.0, la manière de créer et de structurer du contenu dans WordPress a profondément changé. Fini l’éditeur classique limité : place à une interface visuelle moderne, où chaque élément (titre, paragraphe, image, galerie…) est représenté sous forme de blocs.

Mais que faire si les blocs natifs ne suffisent pas à tes besoins ? Que tu veuilles ajouter un bouton stylisé sur mesure, une section FAQ dynamique ou une mise en forme spécifique à ton site, la réponse est claire : créer un bloc personnalisé.

Ce guide complet te montre pas à pas comment créer ton propre bloc Gutenberg, avec :

• une interface d’édition développée en React/JSX (pour le backend),
• un rendu dynamique ou statique en PHP (pour le frontend),
• une approche modulaire via le fichier block.json introduit par WordPress.

Objectif : à la fin de cet article, tu seras capable de créer et enregistrer un bloc WordPress 100 % personnalisé, avec des attributs, des styles et une logique propre à ton projet.

1. Comprendre l’architecture de Gutenberg

1.1 Gutenberg : un éditeur basé sur React

L’éditeur Gutenberg, introduit dans WordPress 5.0, repose sur une architecture React-based. Il transforme chaque élément de contenu en bloc réutilisable et configurable. Cette approche « block-first » offre une expérience visuelle, modulaire et bien plus intuitive que l’ancien éditeur classique.

📦 Un bloc peut représenter :

• un paragraphe,
• une galerie,
• une image,
• un bouton,
• une citation,
• ou encore des éléments complexes comme une FAQ ou un slider.

1.2 Le rôle des blocs dans WordPress

Chaque contenu dans Gutenberg est une instance de bloc. WordPress distingue trois grandes catégories :

Chaque bloc contient des attributs, une interface d’édition (React) et un rendu côté frontend (HTML ou PHP).

🎯 Objectif : le développeur peut étendre l’éditeur Gutenberg à volonté, en ajoutant des blocs adaptés aux besoins du site ou du client.

1.3 La structure d’un bloc personnalisé

Créer un bloc personnalisé repose sur trois piliers principaux :

Une arborescence typique ressemblera à ceci :

my-plugin/
├── my-plugin.php
├── build/
│   └── index.js             ← JS compilé du bloc
├── src/
│   └── edit.js              ← Code React du bloc
├── block.json               ← Déclaration du bloc
└── style.css                ← Styles du bloc côté site

✅ Depuis WordPress 5.5+, block.json permet d’enregistrer le bloc automatiquement avec register_block_type_from_metadata(), simplifiant grandement la déclaration.

2. Prérequis pour créer un bloc Gutenberg

Avant de se lancer dans la création d’un bloc personnalisé, il est essentiel de préparer un environnement de travail adapté. Gutenberg s’appuie sur des technologies modernes comme React, ESNext, npm, et Webpack, qui nécessitent quelques outils côté développeur.

2.1 Environnement nécessaire

Pour développer un bloc Gutenberg, voici les outils dont tu auras besoin :

Prérequis techniques :

• ✅ WordPress version 5.8 ou supérieure (support natif de block.json)
• ✅ Node.js installé (version recommandée : 18+)
• ✅ npm (installé avec Node.js)
• ✅ Un éditeur de code moderne (ex. : VS Code)
• ✅ Un site WordPress local (via LocalWP, MAMP, XAMPP, Lando…)

💡 Tu peux vérifier que Node.js et npm sont installés avec les commandes :

node -v
npm -v

Un thème ou plugin actif :
Tu vas devoir enregistrer le bloc dans un plugin (de préférence) ou dans un thème enfant. Ici, nous optons pour la création d’un plugin dédié au bloc, ce qui rend ton développement portable et modulaire.

2.2 Créer un plugin de base

Commençons par la création du squelette de ton plugin :

Arborescence minimale :

my-plugin/
├── my-plugin.php         ← Fichier principal du plugin
├── block.json            ← Métadonnées du bloc
├── src/                  ← Fichiers source (React / JSX)
└── build/                ← JS compilé par Webpack

Exemple : contenu de my-plugin.php

<?php
/**
 * Plugin Name: Mon Bloc Gutenberg Personnalisé
 * Description: Un bloc Gutenberg développé sur mesure avec React + PHP.
 * Version: 1.0.0
 * Author: Webpixelia
 */

function wpb_register_custom_block() {
    // Enregistrement automatique via block.json
    register_block_type(__DIR__);
}
add_action('init', 'wpb_register_custom_block');

Avec cette simple fonction register_block_type(__DIR__), WordPress va chercher un fichier block.json à la racine du plugin pour charger le bloc.

Tu as maintenant un plugin WordPress opérationnel qui peut accueillir ton futur bloc Gutenberg.
👉 La prochaine étape ? Configurer block.json, installer les dépendances JS, puis coder le bloc en React.

3. Créer et enregistrer un bloc avec block.json

Depuis WordPress 5.5+, l’usage du fichier block.json est devenu la méthode recommandée pour déclarer les blocs Gutenberg. Il centralise toutes les métadonnées du bloc, simplifie son enregistrement, et améliore la compatibilité avec l’éditeur et l’API REST.

3.1 Le fichier block.json

Le fichier block.json est à la base de la configuration du bloc. Il contient les informations essentielles que WordPress utilise pour :

• identifier le bloc,
• l’afficher dans l’éditeur,
• charger les scripts et styles associés,
• définir ses attributs, sa catégorie, son icône, etc.

Exemple de block.json :

{
  "apiVersion": 2,
  "name": "monplugin/mon-bloc",
  "title": "Mon Bloc",
  "category": "widgets",
  "icon": "admin-customizer",
  "description": "Un bloc personnalisé créé avec amour.",
  "keywords": ["custom", "bloc", "webpixelia"],
  "textdomain": "monplugin",
  "editorScript": "file:./build/index.js",
  "style": "file:./build/style-index.css",
  "editorStyle": "file:./build/editor.css"
}

Détails des champs principaux :

• "name" : identifiant global unique du bloc (namespace/nom).
• "title" : nom lisible du bloc (visible dans l’éditeur).
• "category" : groupe où le bloc apparaît (common, text, widgets, design, etc.).
• "icon" : icône Dashicons ou SVG personnalisé.
• "editorScript" : script JS de l’éditeur (généré par Webpack).
• "style" / "editorStyle" : fichiers CSS frontend et éditeur.

Points importants :

• apiVersion: 2 est obligatoire pour bénéficier des nouvelles fonctionnalités du système de blocs (notamment le support du système de styles, du rendu dynamique amélioré, etc.).
  Si tu ne le précises pas, WordPress considérera que tu utilises l’ancienne version (apiVersion 1) avec des limitations.
• Différence entre editorScript et script :
  • editorScript : script JavaScript chargé uniquement dans l’éditeur Gutenberg (backend).
  • script : script JavaScript chargé sur le frontend, pour rendre ou enrichir le bloc côté site public.
• style : CSS chargé à la fois dans l’éditeur et sur le frontend.
• editorStyle : CSS chargé uniquement dans l’éditeur.

💡 Pour tester facilement différentes icônes Dashicons : https://developer.wordpress.org/resource/dashicons/

3.2 Fonction PHP pour l’enregistrement

Une fois le fichier block.json en place, l’enregistrement côté PHP est très simple, grâce à la fonction native register_block_type().

Code dans my-plugin.php :

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

Ici, __DIR__ désigne le dossier du plugin, où se trouve le block.json. WordPress scanne automatiquement ce fichier et charge les bonnes ressources JS/CSS.

✅ Aucun besoin d’enregistrer manuellement les scripts ou styles avec wp_register_script() : tout est géré depuis block.json.

Étapes suivantes :

• Installer les dépendances JS (React, WordPress scripts, etc.)
• Créer le fichier src/index.js avec le code du bloc
• Compiler avec Webpack via @wordpress/scripts

4. Écriture du bloc côté éditeur (React)

4.1 Initialisation avec @wordpress/scripts

Depuis la modernisation de l’écosystème WordPress, la manière la plus simple de démarrer un bloc personnalisé consiste à utiliser le scaffolding tool officiel :

npx @wordpress/create-block mon-bloc

Cette commande va :

• Créer un dossier mon-bloc/
• Générer automatiquement :
  • un block.json bien formé
  • le code JSX/React pour l’éditeur (edit.js)
  • le rendu du bloc (save.js)
  • le fichier d’entrée Webpack (index.js)
  • la configuration build complète via @wordpress/scripts

Cela permet de se concentrer uniquement sur le code du bloc, sans se soucier de la configuration Webpack, Babel, ESLint, etc.

Exemple de structure générée :

mon-bloc/
├── block.json
├── build/
├── src/
│   ├── edit.js
│   ├── save.js
│   └── index.js
├── package.json
└── README.md

4.2 Création de l’interface d’édition

L’interface d’un bloc dans Gutenberg repose sur React. WordPress fournit ses propres composants via le package @wordpress/components et l’API de l’éditeur via @wordpress/block-editor.

Exemple minimal avec RichText

const { RichText } = wp.blockEditor;

export default function Edit({ attributes, setAttributes }) {
    return (
        <RichText
            tagName="p"
            value={attributes.contenu}
            onChange={(value) => setAttributes({ contenu: value })}
            placeholder="Saisissez votre texte ici..."
        />
    );
}

Détail :

• RichText permet une zone éditable riche (gras, italique, liens…)
• attributes.contenu contient la valeur actuelle
• setAttributes() permet de mettre à jour l’état du bloc en temps réel

4.3 Gestion des attributs

Les attributs d’un bloc sont déclarés dans le fichier block.json, ce qui rend leur gestion plus lisible et centralisée.

Exemple dans block.json :

{
  "attributes": {
    "contenu": {
      "type": "string",
      "source": "html",
      "selector": "p"
    }
  }
}

Explication :

• type: le type de donnée (string, array, object, etc.)
• source: où chercher la valeur dans le DOM lors du rendu (html, attribute, text)
• selector: balise HTML contenant la donnée

Cela permet à WordPress de faire automatiquement le lien entre :

• le contenu dans save.js (rendu frontend),
• le contenu saisi dans l’éditeur (edit.js),
• la sérialisation et le stockage dans la base de données via l’éditeur Gutenberg.

4.4 Compilation et performance

Lorsque tu développes un bloc Gutenberg avec React et ESNext, tu écris ton code en modules modernes qu’il faut compiler pour qu’il soit compatible avec tous les navigateurs. Ce processus est géré via un outil de build comme Webpack, souvent simplifié avec le paquet @wordpress/scripts.

Processus de compilation avec npm run build (ou wp-scripts build)

Pour préparer ton bloc en production, tu utilises la commande :

npm run build

ou si tu utilises directement les scripts WordPress :

wp-scripts build

Cette commande va :

• Compiler ton code React/JSX en JavaScript standard.
• Minifier le code (réduire sa taille en supprimant espaces, commentaires, noms longs).
• Optimiser le bundle pour améliorer les performances.

Le résultat est un fichier JavaScript prêt à être chargé en production.

Mode développement avec npm run start (ou wp-scripts start)

En phase de développement, tu utilises plutôt :

npm run start

ou

wp-scripts start

Cela lance un serveur de développement avec hot reloading : tes modifications sont automatiquement reflétées dans l’éditeur Gutenberg sans que tu aies à recharger manuellement la page.

Ce mode produit un bundle non minifié et plus facile à déboguer.

Optimisation des bundles JavaScript (tree-shaking, minification)

Webpack, via @wordpress/scripts, applique plusieurs optimisations :

• Tree-shaking : il élimine les parties de code inutilisées dans ton bundle, pour ne pas envoyer du code mort aux navigateurs.
• Minification : le code est compressé pour être le plus léger possible, ce qui accélère le chargement.

Cela améliore la rapidité de ton site et réduit la consommation de bande passante.

Importance de charger uniquement les scripts nécessaires (éditeur vs frontend)

Ton bloc peut avoir deux environnements d’exécution :

• L’éditeur (backend) : où tu charges la version React/JSX pour éditer ton bloc (editorScript).
• Le frontend : où tu charges éventuellement un script plus léger (script) pour gérer des interactions ou effets visuels.

Il est important de ne pas charger le code de l’éditeur sur le frontend et inversement, pour ne pas alourdir inutilement la page.

Le fichier block.json te permet de déclarer précisément ces scripts.

Optimisation des blocs dynamiques via la mise en cache côté serveur

Pour les blocs dynamiques qui exécutent du PHP côté serveur (via render_callback), il est conseillé d’optimiser la performance en cachant le rendu HTML.

Voici deux techniques courantes :

• Transient API : stocke le rendu HTML en base de données avec une durée de vie limitée. Par exemple :

function render_mon_bloc($attributes) {
    $cache_key = 'mon_bloc_cache_' . md5(serialize($attributes));
    $output = get_transient($cache_key);

    if (false === $output) {
        // Génération coûteuse
        $output = '<div>Contenu dynamique...</div>';

        // Sauvegarde en cache 1 heure
        set_transient($cache_key, $output, HOUR_IN_SECONDS);
    }

    return $output;
}

• Cache HTTP : configurer des headers pour que la page soit mise en cache par le navigateur ou un proxy.

5. Rendu du bloc côté frontend (PHP)

Dans WordPress, tous les blocs ne sont pas statiques. Si tu souhaites un rendu dynamique côté serveur (par exemple pour afficher des données en temps réel, utiliser des fonctions PHP, des shortcodes, etc.), tu peux utiliser une fonction render_callback. C’est ce qu’on appelle un bloc dynamique.

5.1 Utilisation de render_callback

La clé pour un bloc dynamique est de spécifier la fonction de rendu dans le block.json :

{
  "name": "mon-namespace/mon-bloc",
  "title": "Mon Bloc Dynamique",
  "category": "widgets",
  "attributes": {
    "contenu": {
      "type": "string",
      "default": ""
    }
  },
  "supports": {
    "html": false
  }
}

Ensuite, dans un fichier PHP (par exemple render.php ou mon-bloc.php), on enregistre le bloc avec la fonction de rendu :

register_block_type(__DIR__, [
    'render_callback' => 'render_mon_bloc',
]);

Cette fonction PHP sera appelée automatiquement pour générer le contenu du bloc au moment de l’affichage.

5.2 Exemple de fonction de rendu

Dans render.php, tu peux créer une fonction PHP comme celle-ci :

<?php
function render_mon_bloc( $attributes, $content, $block ) {
    $contenu = wp_kses_post( $attributes['contenu'] ?? '' );

    return "<div class='mon-bloc'>{$contenu}</div>";
}

Explication des paramètres :

• $attributes : les attributs définis dans block.json (et éventuellement modifiés par l’utilisateur dans l’éditeur).
• $content : le contenu généré par save.js si le bloc est hybride.
• $block : objet contenant plus d’informations sur le contexte du bloc.

Pourquoi utiliser un bloc dynamique ?

• Pour afficher des données à jour (ex : date, nombre de commentaires, post en vedette…)
• Pour intégrer des fonctions PHP (comme do_shortcode, get_posts(), etc.)
• Pour gérer du contenu multilingue ou personnalisé (selon l’utilisateur, la date, etc.)

6. Ajouter des styles personnalisés

L’un des grands avantages de Gutenberg est la possibilité de styliser les blocs à la fois dans l’éditeur (backend) et sur le site public (frontend). Cela permet une expérience « WYSIWYG » (ce que tu vois est ce que tu obtiens) très appréciée des utilisateurs.

WordPress propose deux fichiers CSS séparés :

• editor.css : appliqué uniquement dans l’éditeur (backend).
• style.css : appliqué uniquement sur le frontend.

6.1 CSS pour l’éditeur (editor.css)

Ce fichier permet de styliser l’apparence du bloc dans Gutenberg, sans affecter l’apparence publique du site.

Exemple de structure :

mon-bloc/
├── src/
│   └── editor.css
└── block.json

Dans block.json, ajoute :

{
  "editorStyle": "file:./src/editor.css"
}

Exemple dans editor.css :

.wp-block-mon-namespace-mon-bloc {
    background-color: #f0f8ff;
    border: 2px dashed #007cba;
    padding: 1rem;
    font-style: italic;
}

Le sélecteur .wp-block-<namespace>-<slug> est automatiquement ajouté par WordPress à chaque bloc, ce qui facilite le ciblage CSS.

6.2 CSS pour le frontend (style.css)

Ce fichier définit l’apparence publique du bloc, visible par tes visiteurs.

Emplacement :

mon-bloc/
├── src/
│   └── style.css
└── block.json

Ajoute dans block.json :

{
  "style": "file:./src/style.css"
}

Exemple dans style.css :

.wp-block-mon-namespace-mon-bloc {
    background-color: #ffffff;
    border: 1px solid #ccc;
    padding: 1.5rem;
    border-radius: 6px;
    font-size: 1rem;
}

Conseil : garde les styles backend et frontend cohérents pour une meilleure expérience utilisateur.

Bonus : SCSS et compilation

Si tu utilises @wordpress/scripts, tu peux :

• Renommer tes fichiers .scss,
• Les importer dans index.js et edit.js,
• Et les compiler automatiquement via Webpack.

Exemple :

import './style.scss';
import './editor.scss';

7. Étendre les possibilités

Une fois les bases du bloc établies (structure, rendu, styles), tu peux le rendre plus interactif, plus dynamique et plus réutilisable. Gutenberg propose une riche collection de composants et d’API pour cela.

7.1 Ajouter une image ou un lien

Ajouter une image avec MediaUpload

Pour permettre à l’utilisateur d’insérer une image dans le bloc, tu peux utiliser le composant MediaUpload (de @wordpress/block-editor).

Exemple :

import { MediaUpload, MediaUploadCheck } from '@wordpress/block-editor';
import { Button } from '@wordpress/components';

<MediaUploadCheck>
    <MediaUpload
        onSelect={(media) => setAttributes({ imageUrl: media.url })}
        allowedTypes={['image']}
        render={({ open }) => (
            <Button onClick={open} variant="secondary">Choisir une image</Button>
        )}
    />
</MediaUploadCheck>

Ajouter un lien avec URLInput

Pour intégrer un lien dans le bloc, utilise URLInput, qui fournit une interface simple de sélection d’URL.

Exemple :

import { URLInput } from '@wordpress/block-editor';

<URLInput
    value={attributes.lien}
    onChange={(url) => setAttributes({ lien: url })}
/>

Tu peux ensuite utiliser ce lien dans ton rendu PHP :

<a href="<?php echo esc_url($attributes['lien']); ?>">Cliquez ici</a>

7.2 Blocs dynamiques vs statiques

WordPress prend en charge deux types de blocs :

Blocs statiques

• Le contenu HTML est sauvegardé directement dans l’article.
• Il est rendu tel quel (par exemple un paragraphe <p> ou une image).
• Très performants, mais difficiles à mettre à jour dynamiquement.

Blocs dynamiques

• Le contenu est généré à chaque affichage grâce à un render_callback en PHP.
• Idéal pour afficher des données à jour : produits WooCommerce, articles récents, utilisateurs connectés, etc.
• Très flexible, mais nécessite plus de code.

Choisir entre les deux dépend de tes besoins :

• Tu affiches du contenu figé ? Préfére un bloc statique.
• Tu affiches du contenu basé sur des données ou des calculs ? Opte pour un bloc dynamique.

7.3 Réutiliser des composants existants

Le cœur de Gutenberg repose sur une librairie de composants React préfabriqués. En les utilisant, tu gagnes du temps et bénéficies d’un design cohérent avec WordPress.

Exemples de composants utiles :

Exemple d’utilisation de ToggleControl :

import { ToggleControl } from '@wordpress/components';

<ToggleControl
    label="Afficher l’image ?"
    checked={attributes.afficherImage}
    onChange={(val) => setAttributes({ afficherImage: val })}
/>

8. Personnaliser ton bloc avec des contrôles avancés (React + @wordpress/components)

Maintenant que tu sais créer un bloc simple avec un champ texte, il est temps de rendre ton bloc plus interactif et riche en fonctionnalités. On va voir comment ajouter des contrôles avancés dans l’éditeur Gutenberg pour que l’utilisateur puisse configurer ton bloc facilement, directement depuis l’interface.

8.1 Comprendre les InspectorControls

Les InspectorControls sont un conteneur qui te permet d’ajouter des panneaux et des réglages dans la sidebar latérale de l’éditeur Gutenberg. C’est là que tu places par exemple des champs pour choisir une couleur, une image, un sélecteur, etc.

Pour utiliser InspectorControls, importe-le depuis @wordpress/block-editor et place-le dans le JSX de ton composant Edit.

Exemple simple :

import { InspectorControls, RichText } from '@wordpress/block-editor';
import { PanelBody, TextControl } from '@wordpress/components';
import { useState } from '@wordpress/element';

export default function Edit({ attributes, setAttributes }) {
    const { contenu, titre } = attributes;

    return (
        <>
            <InspectorControls>
                <PanelBody title="Réglages du bloc" initialOpen={true}>
                    <TextControl
                        label="Titre du bloc"
                        value={titre}
                        onChange={(value) => setAttributes({ titre: value })}
                    />
                </PanelBody>
            </InspectorControls>
            
            <RichText
                tagName="p"
                value={contenu}
                onChange={(value) => setAttributes({ contenu: value })}
                placeholder="Écris ton contenu ici..."
            />
        </>
    );
}

Ici, on ajoute un panneau dans la sidebar avec un champ texte permettant de modifier un titre. Pendant ce temps, dans l’éditeur, l’utilisateur modifie un paragraphe.

8.2 Utiliser différents composants pour enrichir ton bloc

Gutenberg propose plein de composants React prêts à l’emploi dans @wordpress/components pour rendre ton bloc puissant :

• ToggleControl : interrupteur On/Off, idéal pour activer/désactiver une option.
• SelectControl : menu déroulant pour choisir parmi plusieurs options.
• ColorPalette : palette de couleurs pour choisir une teinte.
• RangeControl : slider pour sélectionner une valeur numérique.
• MediaUpload : uploader / sélectionner une image ou un média.

Exemple avec plusieurs contrôles :

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

export default function Edit({ attributes, setAttributes }) {
    const { contenu, couleur, afficherTitre, tailleTexte } = attributes;

    return (
        <>
            <InspectorControls>
                <PanelBody title="Options de personnalisation" initialOpen={true}>
                    <ToggleControl
                        label="Afficher le titre"
                        checked={afficherTitre}
                        onChange={(val) => setAttributes({ afficherTitre: val })}
                    />
                    <SelectControl
                        label="Taille du texte"
                        value={tailleTexte}
                        options={[
                            { label: 'Petit', value: 'small' },
                            { label: 'Moyen', value: 'medium' },
                            { label: 'Grand', value: 'large' },
                        ]}
                        onChange={(val) => setAttributes({ tailleTexte: val })}
                    />
                    <ColorPalette
                        value={couleur}
                        onChange={(val) => setAttributes({ couleur: val })}
                    />
                </PanelBody>
            </InspectorControls>

            {afficherTitre && <h2 style={{ color: couleur }}>Titre du bloc</h2>}

            <RichText
                tagName="p"
                value={contenu}
                onChange={(value) => setAttributes({ contenu: value })}
                placeholder="Écris ton contenu ici..."
                style={{
                    fontSize:
                        tailleTexte === 'small'
                            ? '12px'
                            : tailleTexte === 'large'
                            ? '24px'
                            : '16px',
                    color: couleur,
                }}
            />
        </>
    );
}

Avec ça, ton utilisateur peut :

• Choisir d’afficher ou non un titre
• Sélectionner la taille du texte via un menu déroulant
• Choisir une couleur personnalisée via une palette

8.3 Gestion des attributs dans block.json

Pour que ces contrôles fonctionnent, il faut bien déclarer les attributs dans ton fichier block.json. Voici un exemple adapté :

{
    "attributes": {
        "contenu": {
            "type": "string",
            "source": "html",
            "selector": ".mon-bloc__contenu"
        },
        "couleur": {
            "type": "string",
            "default": "#000000"
        },
        "afficherTitre": {
            "type": "boolean",
            "default": true
        },
        "tailleTexte": {
            "type": "string",
            "default": "medium"
        },
        "titre": {
            "type": "string",
            "default": "Titre du bloc"
        }
    }
}

Chaque attribut est typé, certains ont une valeur par défaut. source et selector permettent de lier l’attribut au contenu HTML rendu.

8.4 Résumé & conseils

• Utilise InspectorControls pour ajouter tes réglages dans la sidebar.
• Choisis parmi les composants standards de Gutenberg pour les contrôles (toggle, select, couleur…).
• N’oublie pas de déclarer proprement tes attributs dans block.json.
• Teste bien en mode éditeur pour voir les changements en temps réel.
• Garde un bon équilibre entre fonctionnalités et simplicité pour que l’utilisateur ne soit pas perdu.

9. Internationalisation, accessibilité et bonnes pratiques

9.1 Internationalisation (i18n)

Pour que ton bloc soit utilisable dans différentes langues, il est important de préparer ton code à l’internationalisation. WordPress fournit la fonction __() pour traduire les chaînes de caractères PHP, et dans le JS, tu peux utiliser le package @wordpress/i18n.

En PHP :

echo __( 'Mon bloc personnalisé', 'mon-plugin' );

En JS (React) :

import { __ } from '@wordpress/i18n';

return <p>{ __( 'Écris ton contenu ici...', 'mon-plugin' ) }</p>;

Pense aussi à générer les fichiers .pot et traductions .po/.mo pour que les traducteurs puissent intervenir facilement.

9.2 Accessibilité (a11y)

L’accessibilité est cruciale pour garantir que ton bloc soit utilisable par tous, notamment les personnes utilisant des lecteurs d’écran ou des claviers uniquement.

Quelques bonnes pratiques simples :

• Utilise des éléments HTML sémantiques (ex: <button>, <label>, <fieldset>) au lieu de divs ou spans quand c’est possible.
• Ajoute des attributs ARIA pour décrire l’état ou le rôle des éléments quand nécessaire.
• Assure-toi que les contrôles sont accessibles au clavier, que l’ordre de tabulation est logique.
• Teste ton bloc avec des outils comme Lighthouse ou des lecteurs d’écran (NVDA, VoiceOver).

9.3 Bonnes pratiques de développement

• Modularise ton code : divise ton JS en composants React clairs.
• Utilise les hooks WordPress (useSelect, useDispatch) pour interagir proprement avec l’éditeur.
• Garde ton CSS propre et scoped pour éviter les conflits avec d’autres blocs ou styles du thème.
• Teste régulièrement dans différents contextes (éditeur, frontend, mobile).
• Documente ton code pour faciliter la maintenance ou l’évolution.

10. Débogage et résolution de problèmes

Développer des blocs Gutenberg peut parfois amener son lot de bugs ou comportements inattendus. Cette section t’aide à comprendre les erreurs les plus fréquentes, à utiliser les bons outils et à tester efficacement ton bloc.

10.1 Erreurs courantes et leurs solutions

• Problèmes de build (Webpack, Babel)
  Erreurs lors de la compilation JS ? Vérifie ta configuration, les versions de Node et npm, et les dépendances. Pense à nettoyer le cache avec npm cache clean --force et à réinstaller les modules (rm -rf node_modules && npm install).
  Les messages d’erreur dans le terminal sont précieux pour comprendre où ça coince.
• Attributs mal déclarés ou non pris en compte
  Assure-toi que tes attributs sont bien définis dans block.json avec le bon type et sélecteur. Si l’attribut ne se met pas à jour, vérifie que tu utilises bien setAttributes dans l’éditeur et que la fonction save ou le render_callback les récupèrent.
• Scripts ou styles non chargés
  Si ton bloc ne s’affiche pas correctement ou perd ses styles, vérifie que les scripts et CSS sont bien enregistrés et déclarés dans block.json ou via PHP. Utilise les outils de développement pour voir si les fichiers sont chargés dans le bon contexte (éditeur ou frontend).
• Problèmes liés au render_callback
  Si ton bloc dynamique ne s’affiche pas, teste ta fonction PHP indépendamment, en vérifiant les erreurs PHP (log) et que les attributs sont bien transmis. Active le mode debug de WordPress pour avoir plus d’infos.

10.2 Outils de développement utiles

• React Developer Tools (extension navigateur) :
  Inspecte la hiérarchie React dans l’éditeur Gutenberg, observe les props et états des composants.
• Console du navigateur :
  Vérifie les erreurs JS, les warnings, utilise les points d’arrêt (breakpoints) et surveille les requêtes réseau.
• Debug Bar & Query Monitor (plugins WordPress) :
  Affichent les erreurs PHP, les requêtes SQL, les hooks exécutés, parfaits pour diagnostiquer des problèmes côté serveur.
• Constantes WordPress de debug :
  Active dans wp-config.php : define('WP_DEBUG', true); define('WP_DEBUG_LOG', true); define('SCRIPT_DEBUG', true); Pour avoir un log complet des erreurs et forcer le chargement des versions non minifiées des scripts.

10.3 Comment tester efficacement les blocs

• Tester dans différentes versions de WordPress :
  Certaines APIs évoluent, teste ton bloc sur plusieurs versions, notamment si tu cibles une large audience.
• Validation des attributs (JS + PHP) :
  Vérifie la cohérence des données échangées entre React (éditeur) et PHP (render_callback), notamment les types et valeurs.
• Tester les blocs dynamiques côté frontend :
  Ne te limite pas à l’éditeur, vérifie le rendu final dans plusieurs thèmes et navigateurs.
• Utilisation des snapshots et tests unitaires avec Jest :
  Automatiser les tests te permet de détecter rapidement les régressions lors d’évolutions de ton bloc.

Conclusion

Tu as maintenant une vision claire pour créer un bloc Gutenberg complet, du setup initial au rendu côté frontend :

• Setup : Préparer ton environnement (Node.js, WordPress 5.8+), créer la structure de base du plugin.
• Développement JS : Utiliser React et les packages WordPress pour construire l’interface d’édition avec des contrôles avancés et gérer les attributs.
• Rendu PHP : Générer un rendu dynamique, sécurisé et stylé sur le frontend via une fonction render_callback.

Les blocs personnalisés te permettent d’offrir une expérience éditoriale riche, intuitive, et adaptée aux besoins spécifiques de tes utilisateurs. Plutôt que de bricoler avec des shortcodes ou du contenu statique, tu proposes un vrai composant dynamique, visuel, et facile à utiliser.

Prochaines pistes à explorer :

• Blocs répétés avec InnerBlocks : pour imbriquer plusieurs blocs et créer des mises en page complexes.
• Support Advanced Custom Fields (ACF) : pour profiter d’un système de champs personnalisés puissant et rapide.
• Blocs hybrides : combiner rendu PHP classique avec interface React moderne pour plus de flexibilité.