Guida all'installazione e alla configurazione del modulo Kowal_ExportImportCategories

Questo documento descrive l'installazione, la configurazione e l'utilizzo del moduloKowal_ExportImportCategoriesper Magento 2. La guida include le informazioni del fileREADME.mde le funzionalità implementate nel modulo.

Requisiti

• Magento 2.
• PHP compatibile con l'installazione Magento, PHP8.1o 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 directorypub/media/import/categories.

Installazione tramite Composer

Il modulo è disponibile tramite repository Composer.

1. Aggiungi il repository Composer

I dati di accesso al repository Composer, ovvero l indirizzo e-mail del cliente e il token di licenza, saranno inviati via e-mail dopo l acquisto. Sono disponibili anche nel pannello cliente dopo 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<YOUR_TOKEN>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:deploy
bin/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_ExportImportCategories
bin/magento setup:upgrade
bin/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 principaleExport/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_valueesporta il valore visibile nello store view selezionato dopo aver applicato il fallback di Magento.

store_override_onlyesporta 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 numericostore_idutilizzato durante il salvataggio nelle tabelle Magento.

La colonnastore_view_codedel CSV non viene convertita direttamente instore_id. Viene utilizzata per validare se il file corrisponde allo store view selezionato.

Esempio:

• nel modulo selezioni uno store view constore_id = 1,
• nel CSV deve essere presentestore_view_codecorrispondente a quello store view,
• il modulo salva i dati utilizzandostore_id = 1.

Import Mode

Modalità disponibili:

• update,
• insert.

updateaggiorna le categorie esistenti.

insertcrea 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_emptysignifica che una cella vuota non modificherà il valore attuale.

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

use_defaultsignifica 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'attributourl_key.

Varianti disponibili:

• use_csv_value,
• generate_from_name,
• keep_existing,
• magento_default.

use_csv_valuesalvaurl_keydal CSV.

generate_from_namegeneraurl_keyin base al valorename.

keep_existingmantiene l'url_keyesistente in modalitàupdate.

magento_defaultlascia 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 cambiaurl_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 apub/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_rowssalta le righe non valide e continua l'importazione.

stop_on_first_errorinterrompe l'importazione al primo errore.

all_or_nothingrichiede 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.

Predefinita:

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 eseguiredry-runprima dell'importazione effettiva, soprattutto per file di grandi dimensioni o modifiche SEO.

Modalità import/update

La modalitàupdateserve ad aggiornare categorie esistenti.

Dati richiesti

Il CSV deve contenere:

• store_view_code,
• entity_idoppurecategory_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, seentity_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_description
pl,13,Default Category/Gear/Bags,Torby,torby,Torby,Torby i akcesoria
pl,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,
• primaDry Run, poi l'importazione effettiva.

Modalità import/insert

La modalitàinsertserve a creare nuove categorie.

Dati richiesti

Il CSV deve contenere:

• store_view_code,
• category_path,
• parent_entity_idoppureparent_path,
• name,
• almeno una colonna dell'attributo selezionato.

entity_idnon è 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_menu
default,12,Default Category/Gear,Default Category/Gear/Helmets,Helmets,helmets,1,1
default,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_valueoppuregenerate_from_name,
• Error Policy:skip_invalid_rows,
• primaDry Run.

Utilizzo di select e multiselect

Il modulo gestisceselectemultiselecttramite 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_by
default,13,Default Category/Gear/Bags,Products only,Position|Product Name|Price,Position

Permultiselect 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,thumbnail
default,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 sudry-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 chestore_view_codecorrisponda allo store view di destinazione.
5. Seleziona l'importazioneupdate.
6. Seleziona solo gli attributi che desideri modificare.
7. ImpostaEmpty Values Policysuskip_empty.
8. EseguiDry 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 concategory_path,parent_pathoppureparent_entity_id.
2. Assicurati che le categorie padre esistano o compaiano prima nel file.
3. Seleziona l'importazioneinsert.
4. Seleziona almenonamee gli altri attributi richiesti.
5. EseguiDry 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ù frequenti

L'importazione segnala uno store_view_code non corrispondente

Verifica che il codice nella colonnastore_view_codecorrisponda allo store view selezionato nel modulo di importazione.

L'importazione non modifica i valori

Controlla:

• se l'attributo è stato selezionato inAttributes to Import,
• se la cella CSV non è vuota,
• seEmpty Values Policynon è impostato suskip_empty,
• se l'importazione non è stata eseguita comeDry 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 inpub/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

Verificaparent_entity_idoppureparent_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-categories
bin/magento setup:upgrade
bin/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