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,
• insert.

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:

1. entity_id,
2. 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

1. Esegui l esportazione delle categorie attuali.
2. Conserva il file originale come backup.
3. Prepara le modifiche in una copia del CSV.
4. Assicurati che store_view_code corrisponda allo store view di destinazione.
5. Seleziona l importazione update.
6. Seleziona solo gli attributi che desideri modificare.
7. Imposta Empty Values Policy su skip_empty.
8. Esegui Dry Run.
9. Controlla il report.
10. Esegui l importazione effettiva.
11. Svuota la cache se le modifiche non sono immediatamente visibili.

Importazione sicura di nuove categorie

1. Prepara un CSV con category_path, parent_path oppure parent_entity_id.
2. Assicurati che i genitori esistano o compaiano prima nel file.
3. Seleziona l importazione insert.
4. Seleziona almeno name e gli altri attributi richiesti.
5. Esegui Dry Run.
6. Correggi gli errori dal report.
7. 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