Risolvere i Problemi Comuni di ACF: Troubleshooting

ACF Troubleshooting: Affrontare i Problemi Più Comuni

Advanced Custom Fields è uno dei plugin WordPress più stabili e affidabili, ma come qualsiasi software complesso, può presentare problemi che richiedono diagnosi e risoluzione. Che si tratti di campi che non appaiono dove dovrebbero, valori che non vengono salvati correttamente, conflitti con altri plugin o problemi di performance, sapere come identificare e risolvere rapidamente questi inconvenienti è una competenza fondamentale per chiunque lavori con ACF.

In questo articolo, l’ultimo della nostra serie completa su ACF, raccogliamo i problemi più frequenti segnalati dalla comunità WordPress e forniamo soluzioni pratiche e testate per ciascuno. Dall’installazione alla configurazione, dalla visualizzazione frontend alla compatibilità con altri plugin, copriamo tutti gli scenari di troubleshooting che potresti incontrare nel tuo lavoro quotidiano con ACF.

I Campi Non Appaiono nell’Editor

Il problema più comune in assoluto con ACF è quando i campi personalizzati non vengono visualizzati nell’editor dei contenuti. Nella stragrande maggioranza dei casi, la causa è una configurazione errata delle Location Rules del gruppo di campi. Verifica attentamente che le regole di posizionamento corrispondano al contesto in cui ti aspetti di vedere i campi: il tipo di post è corretto? Il template di pagina è quello specificato nella regola? La categoria corrisponde?

Un errore frequente riguarda la distinzione tra Post e Page: se hai impostato la regola su “Post Type è uguale a Post”, i campi appariranno solo negli articoli, non nelle pagine. Se usi custom post type, assicurati di usare lo slug esatto del CPT nella regola. Un altro errore comune è dimenticare che le regole AND richiedono che tutte le condizioni siano vere: se hai “Post Type = Page AND Template = Homepage”, i campi appariranno solo nelle pagine che usano il template Homepage, non in tutte le pagine.

Se le Location Rules sono corrette ma i campi non appaiono comunque, verifica i seguenti aspetti. Il gruppo di campi è pubblicato (non in bozza o in cestino)? C’è un altro plugin o tema che utilizza una versione diversa di ACF incorporata, causando un conflitto di versioni? L’utente che sta modificando il contenuto ha i permessi necessari per vedere i campi? Se stai usando Gutenberg, i campi ACF appaiono nel pannello laterale o come metabox sotto l’editor, a seconda della configurazione: controlla entrambe le posizioni.

I Valori dei Campi Non Vengono Salvati

Se i campi appaiono nell’editor ma i valori inseriti non vengono salvati dopo il clic su “Pubblica” o “Aggiorna”, ci sono diverse cause possibili. La più comune è un conflitto JavaScript nella pagina di editing: un errore JS causato da un altro plugin può bloccare il processo di salvataggio di ACF. Apri la console del browser (F12 > Console) e verifica se ci sono errori JavaScript. Se trovi errori, prova a disattivare temporaneamente gli altri plugin per identificare il conflitto.

Un’altra causa frequente è il limite di variabili POST del server PHP. Quando un post ha molti campi ACF (specialmente Repeater con molte righe), il numero di variabili inviate nel form può superare il limite max_input_vars di PHP (predefinito: 1000). I dati eccedenti vengono silenziosamente scartati, causando la perdita di valori. La soluzione è aumentare il valore di max_input_vars nel file php.ini o .htaccess:

# Nel php.ini
max_input_vars = 5000

# Nel .htaccess (Apache)
php_value max_input_vars 5000

Verifica anche il limite post_max_size e upload_max_filesize se stai caricando file o immagini tramite campi ACF. Se questi limiti sono troppo bassi, il salvataggio potrebbe fallire silenziosamente. Puoi controllare i valori correnti dalla pagina Strumenti > Salute del Sito > Info nella dashboard WordPress o con phpinfo().

get_field() Restituisce NULL o FALSE

Quando la funzione get_field() restituisce null o false anche se il campo ha un valore nell’editor, le cause più probabili sono le seguenti. Primo: stai usando il nome sbagliato del campo. Il parametro di get_field() deve corrispondere esattamente al “Field Name” (non alla “Field Label”) definito nella configurazione del campo. I nomi sono case-sensitive e usano underscore, non spazi o trattini.

Secondo: stai chiamando get_field() fuori dal loop di WordPress senza specificare il post ID. Se non sei all’interno del loop standard di WordPress (ad esempio, in un file template che non usa while(have_posts())), devi passare l’ID del post come secondo parametro: get_field(nome_campo, $post_id). Per i campi delle Options Page, devi usare option come secondo parametro: get_field(nome_campo, option).

Terzo: c’è un problema di formato di ritorno. Alcuni campi (Select, Checkbox, Post Object) possono restituire formati diversi in base alle impostazioni (valore, etichetta, array, oggetto). Se ti aspetti una stringa ma il campo restituisce un array (o viceversa), potresti ottenere risultati inattesi. Controlla l’impostazione “Return Format” del campo nella configurazione ACF.

Problemi con il Repeater Field

I campi Repeater possono presentare problemi specifici. Il più comune è che have_rows() restituisce false anche quando ci sono righe compilate. Le cause tipiche sono: il nome del Repeater è errato, stai chiamando la funzione fuori dal contesto corretto (senza specificare il post ID per un post diverso da quello corrente), oppure il campo è stato rinominato dopo che i dati sono stati salvati (ACF usa il nome del campo come meta_key, quindi rinominare un campo rende inaccessibili i dati esistenti).

Un altro problema frequente con i Repeater è la perdita di righe durante il salvataggio. Come menzionato precedentemente, questo è quasi sempre causato dal limite max_input_vars: ogni riga del Repeater con 5 sottocampi genera almeno 10 variabili POST (nome e valore per ogni sottocampo), quindi un Repeater con 100 righe e 5 sottocampi genera circa 1000 variabili solo per quel campo, raggiungendo rapidamente il limite predefinito.

Se un Repeater funzionava e improvvisamente smette di salvare nuove righe, controlla anche lo spazio su disco del server e i limiti del database. Un disco pieno o una tabella wp_postmeta che ha raggiunto i limiti di dimensione possono causare errori di scrittura silenziosi. Verifica i log di errore PHP (error_log) e i log MySQL per eventuali errori di scrittura.

Conflitti con Altri Plugin

ACF è generalmente compatibile con la stragrande maggioranza dei plugin WordPress, ma i conflitti possono verificarsi, specialmente con: altri plugin di campi personalizzati (Meta Box, Pods, CMB2), page builder (Elementor, WPBakery, Divi), plugin di caching (WP Rocket, W3TC), plugin di sicurezza (Wordfence, Sucuri) e temi che includono una versione embedded di ACF.

Il metodo standard per diagnosticare un conflitto è il test di esclusione: disattiva tutti i plugin tranne ACF, verifica se il problema persiste, poi riattiva i plugin uno alla volta fino a identificare quello che causa il conflitto. Se il problema è nel tema, passa temporaneamente a un tema predefinito (come Twenty Twenty-Four) per verificare. Una volta identificato il conflitto, cerca una soluzione specifica nella documentazione di ACF o del plugin in conflitto, oppure contatta il supporto di uno dei due.

Un conflitto particolarmente insidioso è quello con i temi o plugin che includono una copia embedded di ACF. Se il tema carica la propria versione di ACF (spesso una versione vecchia), questa può entrare in conflitto con la versione installata come plugin separato. La soluzione è individuare la versione embedded (solitamente nella cartella del tema sotto includes/acf/ o lib/acf/) e disattivarla, mantenendo solo la versione installata come plugin indipendente.

Problemi con Gutenberg e l’Editor a Blocchi

L’editor Gutenberg introduce alcune specificità nel funzionamento di ACF. I metabox ACF appaiono sotto l’editor a blocchi come pannelli separati, il che può confondere gli utenti abituati al Classic Editor dove i metabox erano più integrati nell’interfaccia. Se preferisci, puoi spostare i metabox nel pannello laterale utilizzando l’impostazione “Position: Side” nel gruppo di campi.

Se i campi ACF non appaiono in Gutenberg, verifica che il custom post type sia configurato con show_in_rest => true nella registrazione: senza questa impostazione, Gutenberg non carica l’editor a blocchi e i metabox ACF potrebbero non apparire. Verifica anche che non sia stato aggiunto il filtro use_block_editor_for_post_type per disabilitare Gutenberg per quel tipo di post.

Per i blocchi ACF (acf_register_block_type), i problemi più comuni sono: il blocco non appare nell’inseritore (verifica che la registrazione avvenga nell’hook acf/init e non in un hook precedente), il template di rendering non viene trovato (verifica il percorso nel parametro render_template), e l’anteprima nell’editor è vuota (verifica che il template gestisca correttamente il caso in cui i campi sono vuoti, senza errori PHP).

Performance Lente nel Backend

Se la pagina di editing dei contenuti è lenta a caricarsi quando ci sono campi ACF, le cause più comuni sono: un numero eccessivo di campi nello stesso gruppo (più di 50 campi rallentano visibilmente l’interfaccia), Repeater con molte righe (più di 50 righe in layout Table generano centinaia di elementi DOM), campi Post Object o Relationship con query non filtrate su un database con migliaia di post (ogni campo carica l’elenco completo dei post disponibili via AJAX).

Per ottimizzare le performance del backend, considera queste soluzioni. Suddividi gruppi di campi molto grandi in più gruppi più piccoli con regole di posizionamento specifiche. Per i Repeater, usa il layout Block (con righe collassate) invece di Table per ridurre il numero di elementi DOM renderizzati. Per i campi Post Object e Relationship, filtra i post disponibili per tipo, stato e tassonomia per ridurre il dataset da caricare. Usa i campi Tab per organizzare i campi in sezioni e ridurre il carico visivo iniziale.

Problemi di Migrazione e Aggiornamento

La migrazione di un sito con ACF tra server o l’aggiornamento di ACF a una nuova versione possono occasionalmente causare problemi. Durante la migrazione, assicurati di trasferire sia i file (inclusa la cartella acf-json se usi Local JSON) sia il database completo. I valori dei campi ACF sono nel database (tabella wp_postmeta e wp_options), le configurazioni dei gruppi di campi sono nella tabella wp_posts (come custom post type acf-field-group e acf-field).

Se dopo la migrazione i gruppi di campi esistono ma i valori sono vuoti, il problema è probabilmente una migrazione incompleta del database: la tabella wp_postmeta non è stata trasferita correttamente. Se i valori esistono ma i gruppi di campi non compaiono, la tabella wp_posts potrebbe essere incompleta (mancano le righe di tipo acf-field-group). Se usi Local JSON, puoi ricreare i gruppi di campi dalla sincronizzazione JSON anche senza le righe nel database.

Per gli aggiornamenti di ACF, la compatibilità è generalmente eccellente: il team di sviluppo mantiene la retrocompatibilità con molta cura. Tuttavia, è sempre consigliabile testare gli aggiornamenti in un ambiente di staging prima di applicarli in produzione, specialmente per gli aggiornamenti major (ad esempio da ACF 5.x a 6.x). Dopo l’aggiornamento, verifica che tutti i gruppi di campi funzionino, che i valori siano accessibili e che le funzioni PHP nel tema non producano errori o warning.

Strumenti di Debug per ACF

ACF offre diversi strumenti per il debug che facilitano l’identificazione dei problemi. La funzione get_field_objects() restituisce tutti i campi ACF associati a un post, incluse le configurazioni complete: utile per verificare che i campi siano correttamente registrati e associati. La funzione get_fields() restituisce un array con tutti i valori dei campi del post corrente: perfetta per un controllo rapido di tutti i dati salvati.

Per il debug visivo, puoi inserire temporaneamente nel template:

<?php
// Mostra tutti i campi e i loro valori
echo <pre>;
print_r(get_fields());
echo </pre>;

// Mostra i dettagli di configurazione di tutti i campi
echo <pre>;
print_r(get_field_objects());
echo </pre>;
?>

Il plugin Query Monitor è un alleato prezioso per il debug di ACF: mostra le query SQL generate, il tempo di esecuzione, gli hook eseguiti e i possibili problemi di performance. In combinazione con WP_DEBUG e WP_DEBUG_LOG attivati nel wp-config.php, avrai una visibilità completa su tutto ciò che accade dietro le quinte.

Checklist di Troubleshooting Rapido

Quando incontri un problema con ACF, segui questa checklist di diagnosi rapida in ordine. 1. Verifica le Location Rules: il gruppo di campi è pubblicato e le regole corrispondono al contesto corrente? 2. Controlla i nomi dei campi: stai usando il Field Name (non la Field Label) nelle funzioni PHP? 3. Verifica il contesto: sei nel loop WordPress o stai specificando il post ID? Per Options Page, usi option? 4. Controlla la console del browser: ci sono errori JavaScript che bloccano il salvataggio? 5. Verifica i limiti PHP: max_input_vars, memory_limit, post_max_size sono adeguati?

6. Testa senza altri plugin: disattiva tutti i plugin tranne ACF per escludere conflitti. 7. Testa con un tema predefinito: passa a Twenty Twenty-Four per escludere problemi del tema. 8. Controlla i log: PHP error log e MySQL error log per errori nascosti. 9. Verifica la versione: stai usando l’ultima versione di ACF? L’aggiornamento potrebbe risolvere il problema. 10. Consulta la documentazione: il sito ufficiale di ACF ha una sezione di troubleshooting dettagliata per i problemi noti.

Con questa checklist e le soluzioni descritte in questo articolo, sarai in grado di diagnosticare e risolvere la stragrande maggioranza dei problemi che puoi incontrare lavorando con Advanced Custom Fields. Ricorda che la comunità ACF è vasta e attiva: se un problema persiste dopo aver seguito tutti i passaggi, non esitare a cercare aiuto nei forum di supporto ufficiali o su Stack Overflow.

Se hai bisogno di supporto tecnico per risolvere problemi con ACF o desideri un sito WordPress costruito con le migliori pratiche, il team di G Tech Group è specializzato nella realizzazione di siti web WordPress professionali e nella risoluzione di problemi complessi. Contattaci per assistenza immediata e lascia che i nostri esperti risolvano ogni problema del tuo sito.

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