Export et import JSON des réglages d’une extension, avec validation au retour

Une agence qui gère un réseau de douze sites vitrine construits sur le même socle technique perd un temps considérable à reconfigurer manuellement chaque extension maison sur chaque nouvel environnement de préproduction. La demande de l’équipe est simple : pouvoir exporter la configuration d’une extension en un clic depuis un site de référence, puis l’importer sur un nouveau site en un autre clic, sans recopier des dizaines de champs un par un.

Ce besoin, courant pour toute extension qui accumule plusieurs options au fil du temps, se résout avec un export JSON structuré et un import qui valide strictement ce qu’il reçoit avant de rien écrire en base.

Concevoir l’export

Un export utile ne se limite pas à un simple json_encode() de l’option brute. Il doit inclure des métadonnées qui permettront, au moment de l’import, de vérifier la compatibilité du fichier avec la version de l’extension qui le reçoit :

function generer_export_reglages(): string {
    $reglages = get_option( 'agence_config', array() );

    $export = array(
        'schema_version' => 3,
        'plugin_version' => AGENCE_EXT_VERSION,
        'exporte_le'     => gmdate( 'c' ),
        'donnees'        => $reglages,
    );

    return wp_json_encode( $export, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE );
}

Le champ schema_version est celui qui compte le plus sur la durée : il permet, des années plus tard, de savoir si un fichier d’export ancien est encore compatible avec la structure de données actuelle de l’extension, ou s’il nécessite une transformation avant d’être appliqué.

Proposer le téléchargement

add_action( 'admin_post_exporter_reglages_agence', function() {
    if ( ! current_user_can( 'manage_options' ) ) {
        wp_die( __( 'Action non autorisée.', 'agence-ext' ) );
    }

    check_admin_referer( 'export_reglages_agence' );

    $contenu = generer_export_reglages();

    header( 'Content-Type: application/json' );
    header( 'Content-Disposition: attachment; filename="reglages-agence-' . gmdate( 'Y-m-d' ) . '.json"' );
    echo $contenu;
    exit;
} );

L’appel à check_admin_referer() protège contre une exécution déclenchée depuis un lien externe malveillant, un point souvent oublié sur les routes d’export justement parce qu’on les considère, à tort, comme de simples lectures sans conséquence.

Valider strictement à l’import

L’import est l’endroit le plus sensible de tout ce mécanisme : un fichier corrompu, incomplet, ou volontairement malveillant ne doit jamais pouvoir écraser la configuration existante sans contrôle. La règle à suivre est stricte : en cas de doute sur la structure, on rejette, on ne tente jamais de deviner ou de compléter les champs manquants avec des valeurs par défaut silencieuses.

function importer_reglages_agence( string $contenu_json ) {
    $donnees = json_decode( $contenu_json, true );

    if ( JSON_ERROR_NONE !== json_last_error() ) {
        return new WP_Error( 'json_invalide', __( 'Le fichier n\'est pas un JSON valide.', 'agence-ext' ) );
    }

    if ( empty( $donnees['schema_version'] ) || empty( $donnees['donnees'] ) || ! is_array( $donnees['donnees'] ) ) {
        return new WP_Error( 'structure_invalide', __( 'Le fichier ne correspond pas au format attendu.', 'agence-ext' ) );
    }

    if ( $donnees['schema_version'] > 3 ) {
        return new WP_Error(
            'schema_trop_recent',
            __( 'Ce fichier provient d\'une version plus récente de l\'extension.', 'agence-ext' )
        );
    }

    $reglages_verifies = array();
    $champs_autorises  = array( 'nom_agence', 'couleur_principale', 'email_contact', 'delai_reponse_heures' );

    foreach ( $champs_autorises as $champ ) {
        if ( isset( $donnees['donnees'][ $champ ] ) ) {
            $reglages_verifies[ $champ ] = sanitize_text_field( $donnees['donnees'][ $champ ] );
        }
    }

    update_option( 'agence_config', $reglages_verifies );

    return true;
}

Deux choix méritent d’être soulignés. D’abord, la liste blanche explicite des champs autorisés : seuls les champs connus de la version actuelle sont recopiés, ce qui empêche un fichier d’import d’injecter une clé arbitraire dans l’option stockée en base. Ensuite, le passage systématique par sanitize_text_field() même sur des données déjà censées être propres, puisqu’un fichier JSON reste une source externe non fiable, qu’il vienne d’un autre site de confiance ou non.

Demander confirmation avant d’écraser

Côté interface, l’import ne doit jamais s’exécuter au premier clic sur le bouton d’envoi de fichier. Un écran intermédiaire affiche un résumé lisible du contenu détecté, par exemple le nom d’agence et la couleur principale qui seront appliqués, avec un bouton de confirmation distinct. Ce garde-fou évite qu’un import du mauvais fichier, un export d’un autre client par exemple, n’écrase silencieusement une configuration en production.

• Toujours afficher la date d’export du fichier importé avant confirmation.
• Conserver une sauvegarde de l’ancienne configuration avant d’écrire la nouvelle, sous forme d’option temporaire, pour permettre un retour arrière immédiat en cas d’erreur.
• Journaliser chaque import réalisé, avec l’utilisateur qui l’a déclenché et l’horodatage, utile en cas de litige sur une configuration modifiée par erreur.

Un import qui accepte tout ce qu’on lui donne n’est pas un import pratique, c’est une extension prête à être piégée par son propre fichier de sauvegarde.

En résumé

Un export-import de réglages bien conçu ne se limite jamais à sérialiser puis désérialiser une option : il porte une version de schéma, une validation stricte à base de liste blanche, et une confirmation explicite avant écrasement. Ces trois éléments transforment un gain de confort pour l’équipe technique en un mécanisme suffisamment robuste pour être utilisé sans crainte entre des environnements différents.