Guida all'installazione e alla configurazione del modulo Kowal_ExportImportCategories

Questo documento descrive l'installazione, la configurazione e l'utilizzo del modulo Kowal_ExportImportCategories per Magento 2. La guida include 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 versioni successive consigliato.
• Accesso alla CLI di 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

Riceverai via e-mail, dopo l'acquisto, i dati di accesso al repository Composer, ovvero l'indirizzo e-mail del cliente e il token di licenza. Sono disponibili anche nell'area cliente dopo aver effettuato l'accesso su kowal.store. Sostituisci TWOJ_EMAIL_KLIENTA con l'indirizzo e-mail del tuo account e TWOJ_TOKEN con il token ricevuto. Esegui i comandi nella directory principale di Magento.

composer config repositories.kowal composer https://repo.kowal.store

2. Configura l'accesso al repository Composer Kowal

Configura i dati di accesso al repository Composer Kowal:

composer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'

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 essere presente 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,
• storico delle importazioni.

Se l'utente admin non vede il menu del modulo, controlla il ruolo dell'utente in:

System > Permissions > User Roles

Quindi assegna le autorizzazioni appropriate per le 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 - storico 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 delle categorie.

Se selezioni uno store view linguistico, l'esportazione può contenere valori specifici per quello store view oppure 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 relativo sottoalbero.

Se il campo viene lasciato vuoto, il modulo esporta le categorie a partire 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 applicato 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. Predefinito:

,

È possibile utilizzare un separatore diverso se il file sarà modificato in uno strumento che richiede, ad esempio, il punto e virgola.

Attributes

Elenco degli attributi di categoria disponibili in Magento.

Il modulo recupera gli attributi dinamicamente da EAV, quindi nell'elenco possono comparire anche attributi di 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 il valore numerico store_id utilizzato durante il salvataggio nelle tabelle Magento.

La colonna store_view_code del CSV non viene convertita direttamente in store_id. Viene utilizzata per validare se il file corrisponde allo store view selezionato.

Esempio:

• nel modulo selezioni uno store view con store_id = 1,
• nel CSV deve essere presente store_view_code corrispondente a quello store view,
• il modulo salva i dati utilizzando 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 di 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 modificherà il valore attuale.

clear_value significa che una cella vuota cancellerà il valore dell'attributo.

use_default significa che una cella vuota rimuoverà la sovrascrittura dello store view e consentirà a Magento di utilizzare 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 in base al valore name.

keep_existing mantiene l'url_key esistente in modalità update.

magento_default lascia la gestione dell'URL al meccanismo standard di Magento.

Create permanent redirect for URL key changes

L'opzione definisce se Magento deve creare un permanent redirect quando cambia 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 di categoria relativa a pub/media.

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 salta le righe non valide 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 dati.

Variante consigliata per file di grandi dimensioni:

skip_invalid_rows

Batch Size

Numero di righe elaborate in un singolo batch.

Predefinito:

100

Un valore più basso limita il consumo di memoria. Un valore più alto può accelerare l'importazione su ambienti più potenti.

Attributes to Import

Elenco degli attributi da importare.

L'importazione aggiorna solo gli attributi selezionati. Se la 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.

È consigliato eseguire dry-run prima dell'importazione effettiva, soprattutto per file di grandi dimensioni o modifiche SEO.

Modalità import/update

La modalità update serve ad aggiornare categorie esistenti.

Dati richiesti

Il CSV deve contenere:

• store_view_code,
• entity_id oppure category_path,
• almeno una colonna dell'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 a creare nuove categorie.

Dati richiesti

Il CSV deve contenere:

• store_view_code,
• category_path,
• parent_entity_id oppure parent_path,
• name,
• almeno una colonna dell'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.

Utilizzo di select e multiselect

Il modulo gestisce select e multiselect tramite le label delle opzioni.

Non è necessario indicare 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 con il separatore:

|

Se la label non esiste o è ambigua, l'importazione segnalerà un errore.

Importazione delle immagini di 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à se i file esistono e hanno 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.

Storico delle importazioni

Lo storico delle importazioni è disponibile in:

System > Data Transfer > Export/Import Categories > Import History

Lo storico 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 subito visibili.

Importazione sicura di nuove categorie

1. Prepara un CSV con category_path, parent_path oppure parent_entity_id.
2. Assicurati che le categorie padre 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 indicati nel report.
7. Esegui l'importazione effettiva.

Cache e indici

Dopo aver importato modifiche alle categorie, è consigliabile aggiornare la cache di Magento:

bin/magento cache:clean

Se lo store richiede una reindicizzazione manuale dopo modifiche rilevanti 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 di categoria, ma dopo importazioni di grandi dimensioni è consigliato controllare cache e indici.

Problemi più comuni

L'importazione segnala uno store_view_code non corrispondente

Verifica che il codice nella colonna store_view_code corrisponda allo store view selezionato nel modulo di importazione.

L'importazione non modifica i valori

Verifica:

• 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

Verifica:

• 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 un genitore mancante

Verifica parent_entity_id oppure parent_path. La categoria padre deve esistere in Magento oppure 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 lo storico delle importazioni possa essere rimosso. Il modulo crea la tabella:

kowal_export_import_categories_history