Generazione a Cicli per Cataloghi di Grandi Dimensioni

La modalità ciclo suddivide il catalogo prodotti in batch di dimensione fissa, così la generazione del feed viene completata in modo affidabile anche su hosting condiviso con limiti PHP rigidi.

note

Disponibile dalla v2.0.0

Panoramica

Senza la modalità ciclo, generare un feed richiede l'elaborazione di tutti i prodotti in un'unica richiesta PHP ininterrotta. Su negozi con migliaia di prodotti — o su hosting condiviso dove il server interrompe le richieste dopo 30–60 secondi — questo produce un feed incompleto o vuoto.

La modalità ciclo risolve il problema elaborando un numero configurabile di prodotti per richiesta, salvando i progressi dopo ogni batch e concatenando automaticamente le richieste finché l'intero catalogo non viene scritto. Il file del feed che Facebook legge è sempre uno snapshot completo e valido dell'ultima generazione completa andata a buon fine; non viene mai sostituito da un file parziale.

Due aree del modulo controllano il comportamento del ciclo:

• Scheda Product Options — il campo Cycle Items (FPF_CYCLE) attiva o disattiva la modalità ciclo.
• Scheda Generation Options — impostazioni di prestazioni e sicurezza che controllano il comportamento del motore ciclo.

Come Funziona la Modalità Ciclo

Quando la modalità ciclo è abilitata, ogni richiesta di generazione segue i passaggi seguenti:

1. Prima richiesta — avvia una nuova generazione. Il motore interroga i primi N prodotti (dove N è la dimensione del ciclo), li scrive in un file feed temporaneo e salva la posizione corrente in feeds/progress.json.

2. Continuazione — una volta scritto il primo batch, il motore effettua una chiamata cURL interna a se stesso, passando la posizione e lo stato correnti come dati POST. La nuova richiesta riprende esattamente da dove si era interrotta la precedente, incrementa il contatore del ciclo ed elabora il batch successivo.

3. Completamento — quando l'ultimo prodotto viene elaborato, il file temporaneo viene spostato nella posizione finale del feed. Solo a questo punto l'URL del feed live riflette la nuova generazione. Facebook legge sempre un file completo.

4. File di progresso — feeds/progress.json viene aggiornato ogni 5 prodotti durante un ciclo e a ogni confine di ciclo. La dashboard del Back Office legge questo file per mostrare la barra di avanzamento live e il conteggio dei prodotti. Il file contiene meta.total_feeds, meta.completed_feeds e meta.global_percent così l'interfaccia può mostrare una percentuale accurata senza caricare l'intero feed.

5. Recupero da crash — se una richiesta viene interrotta (timeout del server, errore di memoria, chiusura del browser), la successiva chiamata cron pianificata verifica se progress.json è stato aggiornato negli ultimi 120 secondi. In caso affermativo, la generazione è già in corso e la nuova chiamata termina senza fare nulla. Se sono trascorsi più di 120 secondi dall'ultimo aggiornamento del progresso, il motore considera bloccata l'esecuzione precedente e avvia una nuova generazione dall'inizio.

Il limite di 120 secondi è fisso nel codice. Su server molto lenti o con dimensioni di ciclo molto grandi è possibile evitare riavvii erronei mantenendo la dimensione del ciclo abbastanza piccola da completare ogni batch in meno di 120 secondi.

Configurazione

Abilitare la Modalità Ciclo

Vai su Moduli > Gestione moduli > Facebook & Instagram Product Catalogue Feed Pro > Configura, poi apri la scheda Product Options.

Campo	Posizione	Valori	Predefinito	Descrizione
Cycle Items (FPF_CYCLE)	Product Options	Qualsiasi intero positivo, o 0 per disabilitare	0 (disabilitato)	Numero di prodotti da elaborare per ciclo. Imposta 0 per generare l'intero catalogo in un'unica richiesta. Consigliato: 500–2000 in base alla complessità del catalogo.

Quando Cycle Items è 0, il motore tenta di generare tutti i prodotti in un'unica richiesta. Funziona bene su VPS o hosting dedicato senza limiti di tempo, ma è probabile che vada in timeout su hosting condiviso con cataloghi superiori a ~1.000 prodotti.

Impostazioni di Prestazioni e Sicurezza

Apri la scheda Generation Options per i seguenti campi.

Campo	Valori	Predefinito	Minimo	Descrizione
Product processing chunks (FPF_CHUNK_SIZE)	Intero positivo	2000	—	I prodotti vengono caricati dal database in blocchi di questa dimensione. Controlla la dimensione delle query SQL, non il numero di prodotti per ciclo. Abbassa questo valore se si verificano errori di memoria durante il caricamento delle giacenze.
Product Save cycle (FPF_FEED_UPDATE)	Intero ≥ 5	5	5	Con quale frequenza (in prodotti elaborati) il file feed temporaneo viene scritto su disco. Valori più bassi riducono la perdita di dati in caso di crash ma aumentano l'I/O. I valori inferiori a 5 vengono silenziosamente portati a 5.
Product Overrides save cycle (FPF_FEED_UPDATE_OVERRIDES)	Intero ≥ 10	10	10	Come sopra, ma per i feed di override per lingua e paese. I valori inferiori a 10 vengono silenziosamente portati a 10.
Maximum number of Cycles (FPF_FEED_UPDATE_CYCLES)	Intero ≥ 50	50	50	Limite massimo assoluto sul numero di cicli che una singola generazione completa può usare prima che il motore si fermi. È una protezione contro i loop infiniti. I valori inferiori a 50 vengono silenziosamente portati a 50.
Ignore Abort (FPF_IGNORE_ABORT)	Abilitato / Disabilitato	Disabilitato	—	Se abilitato, chiama ignore_user_abort(true) in modo che il processo PHP continui anche se la connessione browser viene interrotta. Utile per la generazione manuale tramite il visualizzatore console.

I valori minimi per FPF_FEED_UPDATE_OVERRIDES (10) e FPF_FEED_UPDATE_CYCLES (50) vengono applicati silenziosamente al salvataggio. Se si inserisce un numero inferiore, viene sostituito senza alcun messaggio di avviso.

Limite di cicli raggiunto: Se il catalogo richiede più cicli del valore impostato in Maximum number of Cycles, la generazione si interrompe anticipatamente e il feed potrebbe essere incompleto. Moltiplica il numero di prodotti per 1,2 (per tenere conto dei feed per lingua e paese) e dividi per la dimensione del ciclo per stimare il numero di cicli necessari. Imposta il massimo almeno al 20% sopra quella stima.

Utilizzo Combinato con Cron

La modalità ciclo e cron sono progettati per funzionare insieme. La configurazione consigliata è:

1. Imposta Cycle Items su un valore che rientri comodamente nel limite di esecuzione PHP del server — in genere 500 prodotti richiedono 10–30 secondi in base alla velocità del server, alla complessità del catalogo e alla disponibilità delle spedizioni.
2. Aggiungi un cron job che chiama l'URL di generazione del feed ogni 15–30 minuti. L'URL cron è indicato nella scheda Automatic Generation (Cron Jobs).
3. La prima chiamata cron avvia la generazione. Se il catalogo richiede più cicli, il motore li concatena automaticamente all'interno della stessa invocazione cron tramite chiamate cURL interne. Il cron non deve eseguire una chiamata per ogni ciclo.

Se la generazione del feed per l'intero catalogo richiede più tempo dell'intervallo cron, due meccanismi proteggono il processo: il limite di 120 secondi sul progresso impedisce a una seconda chiamata cron di riavviare una generazione già in corso, e l'URL del feed live viene aggiornato solo al completamento della generazione — così Facebook legge sempre l'ultima versione completa.

Per cataloghi molto grandi (50.000+ prodotti) o server in cui cURL è limitato, si consiglia di avviare la generazione dalla riga di comando:

php index.php --fpf_secret_key=YOUR_KEY

La generazione da CLI disabilita l'approccio ciclo-per-richiesta ed esegue la generazione completa in un unico processo senza l'overhead del concatenamento cURL.

Comportamento del Limite di Tempo

All'inizio di ogni ciclo, il modulo tenta di aumentare il max_execution_time di PHP. Il limite di tempo target viene calcolato in base alla dimensione del ciclo: dimensione_ciclo / 5 secondi quando le combinazioni sono abilitate, dimensione_ciclo / 10 secondi altrimenti. Ad esempio, con 2.000 prodotti e combinazioni abilitate, richiede 400 secondi per ciclo.

Se set_time_limit è disabilitato sul server (comune su hosting condiviso), questa regolazione viene saltata silenziosamente e si applica il limite esistente. Mantieni la dimensione del ciclo abbastanza piccola da completare ogni batch entro quel limite.

Il modulo tenta anche di aumentare il limite di memoria PHP a 1 GB all'inizio della generazione, se al momento è allocata meno di 1 GB di memoria e se è disponibile sufficiente memoria di sistema libera.

Esempi di Utilizzo

Esempio: Hosting condiviso con limite di 120 secondi

Un negozio con 8.000 prodotti su hosting condiviso. Ogni prodotto impiega circa 15 ms per essere elaborato (nessuna combinazione, nessuna spedizione). Ciò dà circa 2.000 prodotti per 30 secondi.

Impostazioni consigliate:

• Cycle Items: 1.500 (offre un margine di sicurezza sotto il limite di 120 s)
• Maximum number of Cycles: 100 (8.000 / 1.500 = ~6 cicli per il feed principale, più feed per lingua e paese)
• Intervallo cron: ogni 15 minuti

Ogni chiamata cron concatena ~6 cicli automatici e completa la generazione intera in un'unica esecuzione.

Esempio: Negozio di abbigliamento con combinazioni

Un negozio con 3.000 prodotti, ognuno con 10–15 combinazioni di taglia/colore. L'elaborazione delle combinazioni richiede circa 3–5 volte più tempo per prodotto.

Impostazioni consigliate:

• Cycle Items: 500
• Maximum number of Cycles: 100
• Product processing chunks (FPF_CHUNK_SIZE): 500 (allineare alla dimensione del ciclo per evitare di caricare in memoria più prodotti di quanti se ne elaborano)

Esempio: VPS senza limite di tempo

Un negozio con 15.000 prodotti su un VPS dove max_execution_time è 0 o molto alto.

Impostazioni consigliate:

• Cycle Items: 0 (disabilitato — generazione in un unico passaggio)
• Intervallo cron: ogni 60 minuti

Disabilitare i cicli elimina l'overhead del concatenamento cURL e semplifica la risoluzione dei problemi.

Note Importanti

• La modalità ciclo è per negozio nelle configurazioni multi-negozio, ma il campo Cycle Items è memorizzato come valore di configurazione globale e si applica a tutti i negozi in un'installazione multi-negozio.
• I feed di override per lingua e paese vengono generati dopo il completamento del feed principale. Anch'essi beneficiano della modalità ciclo, ma usano una frequenza di salvataggio separata controllata da FPF_FEED_UPDATE_OVERRIDES.
• Il file feeds/progress.json viene scritto nella cartella feeds/ del modulo. Assicurati che l'utente del server web abbia i permessi di scrittura su quella cartella.
• Il feed viene servito da un file temporaneo durante la generazione e spostato nella posizione finale solo al completamento. Se controlli l'URL del feed durante la generazione, ricevi la versione completa precedente.
• Quando si esegue da CLI (php_sapi_name() === 'cli'), il valore FPF_CYCLE non viene caricato — la generazione da CLI viene sempre eseguita in modalità passaggio singolo indipendentemente dall'impostazione di Cycle Items.

Risoluzione dei Problemi

Problema	Soluzione
Il feed è sempre vuoto o parziale	La dimensione del ciclo è troppo grande per il limite di tempo del server. Riduci Cycle Items a 500 o meno e rigenera.
Il messaggio "A Feed generation is currently in progress" appare ogni volta che si avvia la generazione	Una generazione precedente si è bloccata. Attendi 120 secondi e riprova. Se il problema si ripete, verifica che la cartella feeds/ sia scrivibile in modo che progress.json possa essere aggiornato.
La barra di avanzamento nella dashboard è bloccata a una percentuale	Il processo di generazione è stato interrotto a metà ciclo. La barra riflette l'ultimo progress.json scritto. Avvia una nuova generazione per ripartire.
Limite di cicli raggiunto, feed incompleto	Aumenta Maximum number of Cycles nella scheda Generation Options. Stima i cicli necessari come: (prodotti totali × numero di feed) ÷ dimensione del ciclo.
Errori di memoria durante la generazione	Abbassa Product processing chunks (FPF_CHUNK_SIZE) per ridurre il numero di prodotti caricati in memoria contemporaneamente durante il caricamento delle giacenze.
La generazione viene completata ma l'URL del feed mostra ancora dati vecchi	Il feed non è stato spostato perché la generazione non si è completata del tutto. Controlla la scheda Errors per eventuali errori sui prodotti che potrebbero aver causato l'interruzione anticipata della generazione.
La generazione da CLI ignora l'impostazione Cycle Items	Questo è il comportamento atteso. La CLI esegue in modalità passaggio singolo; la modalità ciclo si applica solo alle richieste web e cron.

Domande Frequenti

Come faccio a sapere se il mio negozio ha bisogno della modalità ciclo?

Se il negozio ha più di 1.000 prodotti, oppure se in precedenza hai ottenuto un feed vuoto o incompleto, dovresti abilitare la modalità ciclo. Inizia con una dimensione del ciclo di 1.000 e riducila se la generazione va ancora in timeout.

La modalità ciclo rallenta la generazione del feed complessivamente?

Leggermente. Ogni ciclo aggiunge un piccolo overhead per la chiamata cURL e l'I/O del file di progresso. Per la maggior parte dei negozi il tempo di generazione totale aumenta del 5–10% rispetto al passaggio singolo. Il compromesso è l'affidabilità su server con limiti di tempo.

Cosa succede al feed live mentre la generazione è in corso?

Niente cambia. L'URL del feed live serve l'ultimo feed completato fino a quando la nuova generazione non termina e sposta il file temporaneo nella posizione finale. I tuoi clienti e Facebook non subiscono alcuna interruzione.

Ho impostato Maximum number of Cycles a 30 e salvato, ma nel modulo mostra 50. È un bug?

No. Il valore minimo consentito per questo campo è 50. Se si inserisce un numero inferiore a 50, viene automaticamente portato a 50 al salvataggio. Lo stesso vale per Product Overrides save cycle (minimo 10) e Product Save cycle (minimo 5).

Posso avviare la generazione dalla riga di comando invece di usare cron?

Sì. Usa php index.php --fpf_secret_key=YOUR_KEY dalla root di PrestaShop. La generazione da CLI viene sempre eseguita in modalità passaggio singolo (la modalità ciclo è disabilitata in CLI). È utile per cataloghi molto grandi su server dove PHP CLI non ha limiti di tempo.

In una configurazione multi-negozio, ogni negozio genera il proprio feed in modo indipendente?

Una singola esecuzione di generazione elabora tutti i negozi abilitati in sequenza all'interno della stessa catena di cicli. I negozi già completati vengono saltati automaticamente nei cicli di continuazione, così il lavoro non viene mai duplicato.

La barra di avanzamento nella dashboard mostra il 100% ma l'URL del feed restituisce prodotti vecchi. Cosa è andato storto?

Può accadere se la cartella feeds/ non è scrivibile, il che impedisce lo spostamento del file temporaneo nella posizione finale. Verifica che l'utente del server web abbia i permessi di scrittura su /modules/facebookproductsfeed/feeds/.

Funzionalità Correlate

• Generazione Automatica con Cron Jobs
• Protezione del Feed
• Generazione Manuale del Feed