Dupliquer la configuration complète des blocs réutilisables d’un site vers un autre

Un réseau de boutiques indépendantes, chacune avec son propre site WordPress mais partageant une charte graphique commune, avait construit sur son site pilote une bibliothèque de vingt-deux blocs réutilisables (bandeaux d’information, encarts de garantie, blocs de coordonnées). Chaque nouvelle boutique qui rejoignait le réseau devait recréer cette bibliothèque à la main, un travail répétitif et sujet à l’erreur de copier-coller.

Les blocs réutilisables de WordPress sont en réalité de simples articles du type wp_block, stockés comme n’importe quel contenu. Cette simplicité rend leur copie programmatique possible via l’API REST, à condition de gérer correctement le cas où un bloc réutilisable en référence un autre en son sein.

Récupérer les blocs du site source

Le type wp_block est exposé nativement dans l’API REST sous le point de terminaison /wp/v2/blocks, à condition d’être authentifié avec un compte disposant des droits suffisants (un mot de passe d’application, généré depuis le profil utilisateur, convient parfaitement pour ce cas d’usage ponctuel) :

function reseau_recuperer_blocs_source( string $url_site, string $utilisateur, string $mot_de_passe_app ) {
    $reponse = wp_remote_get( trailingslashit( $url_site ) . 'wp-json/wp/v2/blocks?per_page=100', array(
        'headers' => array(
            'Authorization' => 'Basic ' . base64_encode( $utilisateur . ':' . $mot_de_passe_app ),
        ),
    ) );

    if ( is_wp_error( $reponse ) ) {
        return array();
    }

    return json_decode( wp_remote_retrieve_body( $reponse ), true );
}

Recréer chaque bloc sur le site cible

La création côté cible passe par le même point de terminaison, cette fois en POST, avec les identifiants d’authentification propres au site cible :

function reseau_copier_blocs_vers_cible( array $blocs_source, string $url_cible, string $utilisateur, string $mot_de_passe_app ) {
    $correspondance_ids = array();

    foreach ( $blocs_source as $bloc ) {
        $reponse = wp_remote_post( trailingslashit( $url_cible ) . 'wp-json/wp/v2/blocks', array(
            'headers' => array(
                'Authorization' => 'Basic ' . base64_encode( $utilisateur . ':' . $mot_de_passe_app ),
                'Content-Type'  => 'application/json',
            ),
            'body' => wp_json_encode( array(
                'title'   => $bloc['title']['raw'] ?? $bloc['title']['rendered'],
                'content' => $bloc['content']['raw'],
                'status'  => 'publish',
            ) ),
        ) );

        if ( ! is_wp_error( $reponse ) ) {
            $corps = json_decode( wp_remote_retrieve_body( $reponse ), true );
            $correspondance_ids[ $bloc['id'] ] = $corps['id'] ?? null;
        }
    }

    return $correspondance_ids;
}

Le cas des blocs qui s’imbriquent les uns dans les autres

Le vrai point d’attention de cette migration : un bloc réutilisable peut en référencer un autre via un bloc core/block, dont le contenu porte l’attribut ref pointant vers l’identifiant du bloc réutilisable référencé. Comme cet identifiant change nécessairement d’un site à l’autre, il faut réécrire ces références après la copie, en s’appuyant sur la table de correspondance construite à l’étape précédente :

function reseau_reecrire_references( string $contenu, array $correspondance_ids ) {
    return preg_replace_callback(
        '/(<!-- wp:block \{"ref":)(\d+)(\} \/-->)/',
        function ( $correspondances ) use ( $correspondance_ids ) {
            $ancien_id = (int) $correspondances[2];
            $nouvel_id = $correspondance_ids[ $ancien_id ] ?? $ancien_id;

            return $correspondances[1] . $nouvel_id . $correspondances[3];
        },
        $contenu
    );
}

Cette réécriture doit intervenir après que tous les blocs ont été créés sur le site cible (pour disposer de la table de correspondance complète), ce qui implique de faire une seconde passe de mise à jour sur les blocs contenant des références, via une requête POST sur /wp/v2/blocks/{id} cette fois.

Vérifier le résultat avant de généraliser

Sur ce réseau de boutiques, la première migration test a révélé un cas non anticipé : un bloc réutilisable contenait une image dont l’identifiant de média (wp-image-{id}) n’existait évidemment pas sur le nouveau site, faute d’avoir migré la médiathèque en parallèle. Le script s’est donc enrichi d’une étape de téléversement préalable des images utilisées, avant la copie des blocs eux-mêmes, avec la même logique de table de correspondance appliquée aux identifiants de médias.

• Testez toujours la migration sur un site de test avant de l’appliquer à un site en production.
• Utilisez systématiquement un mot de passe d’application dédié à cette migration, révoqué une fois l’opération terminée.
• Vérifiez le rendu final des blocs copiés directement dans l’éditeur du site cible, pas seulement via la réponse de l’API.

Sur un réseau de sites qui partage une charte commune, je recommande de désigner clairement un site « source de vérité » pour les blocs réutilisables : sans cette règle explicite, les versions divergent rapidement d’un site à l’autre après quelques mois d’ajustements locaux indépendants.

Pour aller plus loin

Cette approche par l’API REST, avec table de correspondance d’identifiants, s’applique à bien d’autres cas de migration entre installations WordPress distinctes : modèles de gabarits personnalisés, motifs de blocs, ou taxonomies avec hiérarchie. Le principe reste le même : traiter les éléments sans dépendance en premier, puis réécrire les références dans une seconde passe une fois toutes les correspondances connues.