ACF: Import, Export e Sincronizzazione JSON dei Field Group

Perché Import, Export e Sincronizzazione JSON Sono Fondamentali

In qualsiasi progetto WordPress professionale, la gestione delle configurazioni ACF tra diversi ambienti (sviluppo locale, staging, produzione) è un’esigenza critica. Quando lavori su un sito in locale, crei gruppi di campi, li testi e li perfezionate. Poi devi trasferire queste configurazioni al server di produzione. Senza un sistema strutturato, questo processo diventa manuale, soggetto a errori e impossibile da tracciare nel tempo. ACF affronta questo problema con tre strumenti potenti: l’import/export tramite file JSON e PHP, e la sincronizzazione JSON locale (Local JSON) che automatizza il salvataggio e il caricamento delle configurazioni.

Questi strumenti non sono semplici comodità: sono componenti essenziali di un workflow di sviluppo professionale. Permettono di versionare le configurazioni con Git, di sincronizzare gli ambienti senza interventi manuali nel database, di collaborare in team senza sovrascrivere il lavoro altrui e di ripristinare configurazioni precedenti in caso di errori. In questo articolo esploreremo ogni aspetto di questi strumenti, dalla configurazione base alle strategie avanzate per i workflow di sviluppo professionali.

Export e Import Manuale: JSON e PHP

ACF offre due formati di esportazione manuale: JSON e PHP. Entrambi sono accessibili dalla sezione ACF > Tools della dashboard. L’esportazione JSON genera un file .json che contiene la configurazione completa di uno o più gruppi di campi selezionati: campi, sottocampi, opzioni, regole di posizionamento, impostazioni del gruppo — tutto ciò che serve per ricreare esattamente lo stesso gruppo in un’altra installazione WordPress.

Per esportare, vai su ACF > Tools, seleziona i gruppi di campi che vuoi esportare e clicca su Export File. Il browser scaricherà un file JSON che puoi conservare come backup o trasferire ad un’altra installazione. Per importare, vai sulla stessa pagina nell’installazione di destinazione, seleziona il file JSON nella sezione Import Field Groups e clicca su Import File. ACF creerà i gruppi di campi importati, o aggiornerà quelli esistenti se hanno la stessa chiave univoca (field group key).

L’esportazione PHP genera invece codice PHP che può essere inserito direttamente nel file functions.php del tema o in un plugin personalizzato. Questo codice utilizza la funzione acf_add_local_field_group() per registrare i gruppi di campi a livello di codice, senza bisogno che siano presenti nel database. Il vantaggio è che i gruppi di campi diventano parte integrante del tema e non possono essere accidentalmente modificati o cancellati dalla dashboard. Lo svantaggio è che le modifiche richiedono l’editing del codice PHP, il che può non essere ideale in tutti i contesti.

Local JSON: La Sincronizzazione Automatica

La funzionalità Local JSON è il sistema più elegante e pratico per gestire le configurazioni ACF in un workflow di sviluppo professionale. Quando Local JSON è attivo, ACF salva automaticamente un file JSON nella cartella del tema ogni volta che un gruppo di campi viene creato o aggiornato. Contemporaneamente, al caricamento del sito, ACF controlla se ci sono file JSON più recenti rispetto alla versione nel database e li carica automaticamente.

Per attivare Local JSON, crea semplicemente una cartella chiamata acf-json nella directory root del tuo tema attivo:

wp-content/themes/mio-tema/acf-json/

Assicurati che la cartella abbia i permessi di scrittura corretti (755 o 775) perché ACF possa crearvi i file. Non servono configurazioni aggiuntive: ACF rileva automaticamente la presenza della cartella e attiva il sistema Local JSON. Da questo momento, ogni volta che salvi un gruppo di campi nella dashboard, ACF genererà (o aggiornerà) un file JSON nella cartella acf-json con un nome basato sulla chiave del gruppo (ad esempio group_64a3b2c1d4e5f.json).

Vantaggi del Local JSON per il Versionamento

Il vantaggio principale del Local JSON è la possibilità di versionare le configurazioni ACF con Git. Poiché i file JSON sono nella cartella del tema, vengono inclusi nel repository Git insieme al codice del tema. Questo significa che ogni modifica a un gruppo di campi genera un commit tracciabile, con la possibilità di vedere esattamente cosa è cambiato (campi aggiunti, opzioni modificate, regole di posizionamento cambiate) attraverso il diff del file JSON.

In un workflow basato su Git, il processo tipico è: lo sviluppatore crea o modifica un gruppo di campi nell’ambiente locale, ACF salva automaticamente il file JSON aggiornato, lo sviluppatore fa commit dei file JSON modificati, il codice viene deployato al server di staging/produzione tramite Git pull o CI/CD, ACF rileva i file JSON aggiornati e sincronizza il database. Questo flusso elimina completamente la necessità di esportare e importare manualmente i gruppi di campi tra gli ambienti.

Un altro vantaggio significativo è il miglioramento delle performance. Quando Local JSON è attivo, ACF carica le configurazioni dai file JSON locali invece di eseguire query al database. Questo è più veloce, specialmente su siti con molti gruppi di campi, perché la lettura di file locali è generalmente più rapida di una query SQL. ACF memorizza anche il risultato nella cache dell’oggetto per evitare letture ripetute del filesystem.

Sincronizzazione dei Campi tra Ambienti

La sincronizzazione tra ambienti è uno degli aspetti più delicati della gestione ACF. Con Local JSON, il processo è semi-automatico ma richiede un’azione manuale: dopo aver trasferito i file JSON aggiornati al server (tramite Git, FTP o deploy automatico), devi andare su ACF > Field Groups dove vedrai un avviso che indica i gruppi che necessitano di sincronizzazione. Clicca su Sync per aggiornare il database con le configurazioni dei file JSON.

Puoi anche automatizzare completamente la sincronizzazione utilizzando un hook PHP nel functions.php del tema. Il filtro acf/settings/json e le funzioni di sincronizzazione programmatica di ACF permettono di importare automaticamente le modifiche senza intervento manuale. Tuttavia, questa automazione va implementata con cautela per evitare conflitti quando più sviluppatori modificano gli stessi gruppi di campi contemporaneamente.

Personalizzare la Cartella di Salvataggio JSON

Per impostazione predefinita, ACF salva i file JSON nella cartella acf-json del tema attivo. Puoi personalizzare questa posizione utilizzando i filtri acf/settings/save_json e acf/settings/load_json. Il primo controlla dove ACF salva i file, il secondo dove li cerca:

<?php
// Salvare i JSON in una cartella personalizzata
add_filter(acf/settings/save_json, custom_acf_json_save_point);
function custom_acf_json_save_point($path) {
    return get_stylesheet_directory() . /acf-json;
}

// Caricare i JSON da più cartelle
add_filter(acf/settings/load_json, custom_acf_json_load_point);
function custom_acf_json_load_point($paths) {
    // Rimuovi il path predefinito
    unset($paths[0]);
    // Aggiungi il path del tema figlio
    $paths[] = get_stylesheet_directory() . /acf-json;
    // Aggiungi il path del tema genitore
    $paths[] = get_template_directory() . /acf-json;
    // Aggiungi il path di un plugin
    $paths[] = plugin_dir_path(__FILE__) . acf-json;
    return $paths;
}
?>

La possibilità di caricare JSON da più cartelle è particolarmente utile quando lavori con temi figlio (child theme): puoi avere gruppi di campi “base” nel tema genitore e gruppi aggiuntivi nel tema figlio. È utile anche per i plugin: un plugin può includere la propria cartella acf-json con i gruppi di campi necessari al suo funzionamento.

Gestire i Conflitti di Sincronizzazione

Quando più sviluppatori lavorano sullo stesso progetto e modificano gli stessi gruppi di campi, possono verificarsi conflitti di sincronizzazione. Il file JSON contiene un timestamp modified che ACF utilizza per determinare quale versione è più recente. Se due sviluppatori modificano lo stesso gruppo contemporaneamente e fanno commit, il secondo merge in Git genererà un conflitto nel file JSON.

Per gestire questi conflitti, la best practice è stabilire regole di team: un solo sviluppatore alla volta modifica i gruppi di campi, le modifiche vengono comunicate al team prima di fare commit, e i merge vengono gestiti con attenzione verificando il file JSON risultante. In alternativa, puoi adottare la strategia di un gruppo di campi per file (che è già il comportamento predefinito di ACF) e assegnare la responsabilità di specifici gruppi a specifici sviluppatori, minimizzando la probabilità di conflitti.

Se un conflitto si verifica, risolverlo manualmente nel file JSON è possibile ma rischioso: i file JSON di ACF sono complessi e un errore nella risoluzione può corrompere la configurazione. La strategia più sicura è accettare una delle due versioni (solitamente la più recente), applicarla e poi reintegrare manualmente le modifiche dell’altra versione attraverso l’interfaccia di ACF.

Backup e Ripristino delle Configurazioni

Il Local JSON con Git fornisce un sistema di backup e ripristino naturale: puoi tornare a qualsiasi versione precedente delle configurazioni ACF semplicemente facendo checkout del commit desiderato e sincronizzando il database. Senza Git, puoi comunque mantenere backup manuali copiando periodicamente la cartella acf-json o esportando i gruppi di campi come file JSON dalla sezione Tools.

Una strategia di backup robusta prevede tre livelli: il Local JSON nel repository Git come backup primario con storico completo delle modifiche, esportazioni periodiche tramite Tools come backup secondario (utile se il Local JSON viene accidentalmente corrotto), e il backup del database che include le configurazioni ACF nella tabella wp_posts (i gruppi di campi sono salvati come custom post type acf-field-group).

WP-CLI e Automazione

Per i workflow più avanzati, ACF supporta WP-CLI per le operazioni di import/export dalla riga di comando. Puoi esportare tutti i gruppi di campi con wp acf export e importarli con wp acf import. Questo è particolarmente utile per gli script di deploy automatizzato e le pipeline CI/CD dove non c’è accesso alla dashboard WordPress.

Puoi anche creare script personalizzati che automatizzano la sincronizzazione come parte del processo di deploy. Ad esempio, uno script post-deploy che esegue wp acf sync per sincronizzare automaticamente tutti i gruppi di campi dal Local JSON al database, senza bisogno di accedere alla dashboard e cliccare manualmente il pulsante Sync. Questo livello di automazione è essenziale per team che praticano il continuous deployment.

La padronanza degli strumenti di import, export e sincronizzazione JSON di ACF è ciò che distingue un utilizzo amatoriale da un utilizzo professionale del plugin. Questi strumenti, combinati con un workflow Git disciplinato, garantiscono che le configurazioni ACF siano sempre sotto controllo, tracciabili, replicabili e sicure, indipendentemente dalla complessità del progetto e dal numero di ambienti coinvolti.

Per implementare un workflow di sviluppo professionale con ACF, sincronizzazione JSON e deploy automatizzato, il team di G Tech Group è specializzato nella realizzazione di siti web con processi di sviluppo strutturati e affidabili. Contattaci per una consulenza e porta il tuo progetto WordPress al livello professionale.

Migliora il Tuo Sito WordPress

Scopri le nostre guide complete sugli altri plugin essenziali per WordPress:

• Come Installare Elementor su WordPress
• Come Installare e Configurare WP Rocket
• Come Installare e Configurare SEOPress
• Come Installare e Configurare UpdraftPlus