Istruzioni di installazione e configurazione del modulo Kowal_ExportImportCategories
Questo documento descrive l installazione, la configurazione e l utilizzo del modulo Kowal_ExportImportCategories per Magento 2. Le istruzioni includono le informazioni del file README.md e le funzionalità implementate nel modulo.
Requisiti
- Magento 2.
- PHP compatibile con l installazione Magento, PHP
8.1 o superiore consigliato. - Accesso alla CLI Magento.
- Accesso a Composer.
- Autorizzazioni di amministratore Magento.
- Accesso al repository del modulo.
- Per l importazione delle immagini: possibilità di inserire file nella directory
pub/media/import/categories.
Installazione tramite Composer
Il modulo è disponibile tramite repository Composer.
1. Aggiungi il repository Composer
composer config repositories.export.import.categories vcs https://github.com/kowalco/export-import-categories
2. Aggiungi il token di accesso al repository GitHub privato
Se il repository è privato, configura il token GitHub:
composer config --global --auth github-oauth.github.com
Sostituisci con il tuo token di accesso.
3. Installa il modulo
composer require kowal/module-export-import-categories
4. Abilita il modulo in Magento
bin/magento module:enable Kowal_ExportImportCategories
5. Esegui l aggiornamento di Magento
bin/magento setup:upgrade
6. Svuota la cache
bin/magento cache:flush
7. Facoltativamente esegui la compilazione DI
Negli ambienti di produzione o in modalità production:
bin/magento setup:di:compile
8. Facoltativamente distribuisci le risorse statiche
Se l ambiente lo richiede:
bin/magento setup:static-content:deploybin/magento cache:flush
Installazione manuale in app/code
In alternativa il modulo può essere inserito manualmente nella directory:
app/code/Kowal/ExportImportCategories
Dopo aver copiato i file, esegui:
bin/magento module:enable Kowal_ExportImportCategoriesbin/magento setup:upgradebin/magento cache:flush
In modalità production esegui anche:
bin/magento setup:di:compile
Verifica dell installazione
Dopo l installazione verifica che il modulo sia attivo:
bin/magento module:status Kowal_ExportImportCategories
Il modulo dovrebbe trovarsi nell elenco dei moduli attivi.
Nel pannello di amministrazione vai a:
System > Data Transfer > Export/Import Categories
Dovrebbero essere visibili tre voci:
Export Categories,Import Categories,Import History.
Autorizzazioni ACL
Il modulo aggiunge autorizzazioni amministrative separate:
- accesso alla sezione principale
Export/Import Categories, - esportazione delle categorie,
- importazione delle categorie,
- cronologia delle importazioni.
Se l utente admin non vede il menu del modulo, controlla il ruolo utente in:
System > Permissions > User Roles
Quindi assegna le autorizzazioni appropriate alle risorse del modulo.
Posizione del modulo nel pannello
Il modulo è disponibile in:
System > Data Transfer > Export/Import Categories
Viste:
Export Categories - esportazione delle categorie in CSV.Import Categories - importazione delle categorie da CSV.Import History - cronologia delle importazioni e report.
Configurazione dell esportazione
La vista di esportazione consente di generare un file CSV con le categorie.
Campi di esportazione
Store View
Seleziona lo store view da cui verranno letti i valori degli attributi categoria.
Se selezioni uno store view linguistico, l esportazione può contenere valori specifici per quello store view o valori ereditati dallo scope predefinito, a seconda della modalità dei valori.
Start Category ID
Campo opzionale che consente di limitare l esportazione alla categoria selezionata e al suo sottoalbero.
Se il campo viene lasciato vuoto, il modulo esporta le categorie dalla root category dello store view selezionato.
Store View Value Mode
Definisce come esportare i valori dipendenti dallo store view.
Varianti disponibili:
resolved_value,store_override_only.
resolved_value esporta il valore visibile nello store view selezionato dopo aver considerato il fallback di Magento.
store_override_only esporta solo il valore sovrascritto per lo store view selezionato. Se il valore è ereditato dal default scope, la cella CSV sarà vuota.
CSV Delimiter
Separatore CSV. Per impostazione predefinita:
,
È possibile usare un altro separatore se il file sarà modificato in uno strumento che richiede, ad esempio, il punto e virgola.
Attributes
Elenco degli attributi categoria disponibili in Magento.
Il modulo recupera gli attributi dinamicamente da EAV, quindi nell elenco possono comparire anche attributi categoria personalizzati aggiunti nel progetto.
Le colonne di sistema vengono aggiunte automaticamente e non devono essere selezionate.
Colonne di sistema nell esportazione
L esportazione dovrebbe sempre contenere le colonne di sistema:
store_view_code,entity_id,parent_entity_id,category_path,parent_path,level,position,attribute_set_id.
Queste colonne servono per identificare le categorie, validare lo store view e gestire la struttura ad albero.
Configurazione dell importazione
La vista di importazione consente di caricare un CSV e salvare i dati delle categorie.
Campi di importazione
Store View
Seleziona lo store view in cui verranno salvati i valori.
Questo campo determina lo store_id numerico utilizzato durante il salvataggio nelle tabelle Magento.
La colonna store_view_code del CSV non viene convertita direttamente in store_id. Viene usata per validare che il file corrisponda allo store view selezionato.
Esempio:
- nel modulo selezioni uno store view con
store_id = 1, - nel CSV deve esserci
store_view_code corrispondente a quello store view, - il modulo salva i dati usando
store_id = 1.
Import Mode
Modalità disponibili:
update aggiorna le categorie esistenti.
insert crea nuove categorie.
CSV File
File CSV con intestazioni nella prima riga.
Il file deve essere codificato in UTF-8.
CSV Delimiter
Separatore CSV. Deve corrispondere al separatore utilizzato nel file.
Unknown Columns Policy
Definisce il comportamento per le colonne che non sono né colonne di sistema né attributi categoria noti.
Varianti disponibili:
error - l importazione segnala un errore per le colonne sconosciute.ignore - le colonne sconosciute vengono ignorate.
Variante consigliata:
error
Empty Values Policy
Definisce come il modulo interpreta le celle CSV vuote.
Varianti disponibili:
skip_empty,clear_value,use_default.
skip_empty significa che una cella vuota non modifica il valore attuale.
clear_value significa che una cella vuota cancella il valore dell attributo.
use_default significa che una cella vuota rimuove la sovrascrittura dello store view e consente a Magento di usare il valore predefinito.
Variante consigliata per l importazione di aggiornamento:
skip_empty
URL Key Strategy
Definisce il modo di gestire l attributo url_key.
Varianti disponibili:
use_csv_value,generate_from_name,keep_existing,magento_default.
use_csv_value salva url_key dal CSV.
generate_from_name genera url_key sulla base del valore name.
keep_existing mantiene l attuale url_key in modalità update.
magento_default lascia la gestione degli URL al meccanismo standard di Magento.
Create permanent redirect for URL key changes
L opzione definisce se Magento deve creare un permanent redirect in caso di modifica di url_key.
Vale la pena abilitarla quando la modifica dell URL della categoria deve mantenere i redirect SEO dai vecchi indirizzi.
Images Base Directory
Directory di base per l importazione delle immagini categoria rispetto a pub/media.
Per impostazione predefinita:
import/categories
Percorso completo in Magento:
pub/media/import/categories
Se nel CSV indichi:
gear/bags.jpg
il modulo cercherà il file:
pub/media/import/categories/gear/bags.jpg
Error Policy
Definisce il comportamento dell importazione in caso di errori.
Varianti disponibili:
skip_invalid_rows,stop_on_first_error,all_or_nothing.
skip_invalid_rows ignora le righe errate e continua l importazione.
stop_on_first_error interrompe l importazione al primo errore.
all_or_nothing richiede la correttezza dell intero file; se si verifica un errore, l importazione non dovrebbe salvare i dati.
Variante consigliata per file di grandi dimensioni:
skip_invalid_rows
Batch Size
Numero di righe elaborate in un singolo lotto.
Per impostazione predefinita:
100
Un valore più basso riduce il consumo di memoria. Un valore più alto può velocizzare l importazione su ambienti più potenti.
Attributes to Import
Elenco degli attributi da importare.
L importazione aggiorna solo gli attributi selezionati. Se una colonna esiste nel CSV ma l attributo non viene selezionato nel modulo, il modulo non dovrebbe salvarlo.
Dry Run
Modalità di validazione senza salvataggio dei dati.
Si consiglia di eseguire dry-run prima dell importazione effettiva, soprattutto per file di grandi dimensioni o modifiche SEO.
Modalità import/update
La modalità update serve per aggiornare le categorie esistenti.
Dati richiesti
Il CSV deve contenere:
store_view_code,entity_id oppure category_path,- almeno una colonna di un attributo selezionato.
Come funziona l identificazione delle categorie
Il modulo prova a trovare la categoria tramite:
entity_id,category_path, se entity_id è vuoto.
entity_id è il miglior identificatore quando l importazione avviene nello stesso ambiente Magento.
category_path è più portabile tra ambienti, ma deve essere univoco.
Esempio di aggiornamento delle traduzioni
store_view_code,entity_id,category_path,name,url_key,meta_title,meta_descriptionpl,13,Default Category/Gear/Bags,Torby,torby,Torby,Torby i akcesoriapl,14,Default Category/Gear/Gloves,Rekawiczki,rekawiczki,Rekawiczki,Rekawiczki sportowe
Impostazioni di importazione:
Store View: store view polacco,Import Mode: update,Attributes to Import: name, url_key, meta_title, meta_description,URL Key Strategy: use_csv_value,Empty Values Policy: skip_empty,- prima
Dry Run, poi l importazione effettiva.
Modalità import/insert
La modalità insert serve per creare nuove categorie.
Dati richiesti
Il CSV deve contenere:
store_view_code,category_path,parent_entity_id oppure parent_path,name,- almeno una colonna di un attributo selezionato.
entity_id non è richiesto, perché Magento lo assegna automaticamente.
Esempio di creazione di categorie
store_view_code,parent_entity_id,parent_path,category_path,name,url_key,is_active,include_in_menudefault,12,Default Category/Gear,Default Category/Gear/Helmets,Helmets,helmets,1,1default,12,Default Category/Gear,Default Category/Gear/Gloves,Gloves,gloves,1,1
Impostazioni di importazione:
Store View: default store view,Import Mode: insert,Attributes to Import: name, url_key, is_active, include_in_menu,URL Key Strategy: use_csv_value oppure generate_from_name,Error Policy: skip_invalid_rows,- prima
Dry Run.
Lavorare con select e multiselect
Il modulo supporta select e multiselect tramite le label delle opzioni.
Non è necessario fornire gli ID tecnici delle opzioni.
Esempio:
store_view_code,entity_id,category_path,display_mode,available_sort_by,default_sort_bydefault,13,Default Category/Gear/Bags,Products only,Position|Product Name|Price,Position
Per multiselect più valori vengono separati dal separatore:
|
Se la label non esiste o è ambigua, l importazione segnalerà un errore.
Importazione delle immagini categoria
Prima di importare le immagini, inserisci i file nella directory:
pub/media/import/categories
Esempio di CSV:
store_view_code,entity_id,category_path,image,thumbnaildefault,13,Default Category/Gear/Bags,gear/bags.jpg,gear/bags-thumb.jpg
Impostazioni di importazione:
Images Base Directory: import/categories,- attributi selezionati:
image, thumbnail.
Il modulo verificherà che i file esistano e abbiano estensioni supportate.
Report di importazione
Dopo l importazione il modulo genera un report CSV.
Il report contiene:
- numero di riga,
- identificatore della categoria,
- stato,
- messaggio,
- attributi modificati.
Gli stati possono includere:
success,error,skipped_no_change,skipped_existing.
Cronologia delle importazioni
La cronologia delle importazioni è disponibile in:
System > Data Transfer > Export/Import Categories > Import History
La cronologia contiene:
- data dell importazione,
- utente admin,
- store view,
- modalità di importazione,
- nome del file,
- numero di righe,
- numero di successi,
- numero di errori,
- informazione su
dry-run, - link per scaricare il report.
Processo di lavoro consigliato
Importazione di aggiornamento sicura
- Esegui l esportazione delle categorie attuali.
- Conserva il file originale come backup.
- Prepara le modifiche in una copia del CSV.
- Assicurati che
store_view_code corrisponda allo store view di destinazione. - Seleziona l importazione
update. - Seleziona solo gli attributi che desideri modificare.
- Imposta
Empty Values Policy su skip_empty. - Esegui
Dry Run. - Controlla il report.
- Esegui l importazione effettiva.
- Svuota la cache se le modifiche non sono immediatamente visibili.
Importazione sicura di nuove categorie
- Prepara un CSV con
category_path, parent_path oppure parent_entity_id. - Assicurati che i genitori esistano o compaiano prima nel file.
- Seleziona l importazione
insert. - Seleziona almeno
name e gli altri attributi richiesti. - Esegui
Dry Run. - Correggi gli errori dal report.
- Esegui l importazione effettiva.
Cache e indici
Dopo aver importato modifiche alle categorie, è consigliabile aggiornare la cache Magento:
bin/magento cache:clean
Se il negozio richiede la reindicizzazione manuale dopo modifiche importanti al catalogo:
bin/magento indexer:reindex
Nelle installazioni Magento tipiche, il salvataggio delle categorie tramite i meccanismi standard di Magento dovrebbe avviare i processi appropriati collegati al modello categoria, ma dopo importazioni di grandi dimensioni è consigliato controllare cache e indici.
Problemi più comuni
L importazione segnala uno store_view_code non coerente
Verifica che il codice nella colonna store_view_code corrisponda allo store view selezionato nel modulo di importazione.
L importazione non modifica i valori
Controlla:
- se l attributo è stato selezionato in
Attributes to Import, - se la cella CSV non è vuota,
- se
Empty Values Policy non è impostato su skip_empty, - se l importazione non è stata eseguita come
Dry Run.
Select o multiselect segnala un errore
Verifica che la label dell opzione nel CSV corrisponda esattamente alla label dell opzione in Magento per lo store view selezionato.
L immagine non viene importata
Controlla:
- se il file esiste in
pub/media/import/categories, - se il percorso nel CSV è corretto,
- se l estensione del file è supportata,
- se l attributo immagine è stato selezionato per l importazione.
Insert segnala genitore mancante
Controlla parent_entity_id oppure parent_path. Il genitore deve esistere in Magento o trovarsi prima nel file di importazione.
Disinstallazione del modulo
Se il modulo è stato installato tramite Composer:
composer remove kowal/module-export-import-categoriesbin/magento setup:upgradebin/magento cache:flush
Prima della disinstallazione assicurati che la cronologia delle importazioni possa essere eliminata. Il modulo crea la tabella:
kowal_export_import_categories_history