Instrucțiuni de instalare și configurare a modulului Kowal_ExportImportCategories

Acest document descrie instalarea, configurarea și utilizarea modulului Kowal_ExportImportCategories pentru Magento 2. Instrucțiunile includ informații din fișierul README.md și funcțiile implementate în modul.

Cerințe

• Magento 2.
• PHP compatibil cu instalarea Magento, PHP 8.1 sau mai nou recomandat.
• Acces la CLI Magento.
• Acces la Composer.
• Permisiuni de administrator Magento.
• Acces la repository-ul modulului.
• Pentru importul imaginilor: posibilitatea de a plasa fișiere în directorul pub/media/import/categories.

Instalare prin Composer

Modulul este disponibil prin repository Composer.

1. Adăugați repository-ul Composer

composer config repositories.export.import.categories vcs https://github.com/kowalco/export-import-categories

2. Adăugați tokenul de acces pentru repository-ul privat GitHub

Dacă repository-ul este privat, configurați tokenul GitHub:

composer config --global --auth github-oauth.github.com 

Înlocuiți cu propriul token de acces.

3. Instalați modulul

composer require kowal/module-export-import-categories

4. Activați modulul în Magento

bin/magento module:enable Kowal_ExportImportCategories

5. Rulați actualizarea Magento

bin/magento setup:upgrade

6. Goliți cache-ul

bin/magento cache:flush

7. Opțional, rulați compilarea DI

Pe mediile de producție sau în modul production:

bin/magento setup:di:compile

8. Opțional, implementați resursele statice

Dacă mediul o cere:

bin/magento setup:static-content:deploybin/magento cache:flush

Instalare manuală în app/code

Alternativ, modulul poate fi plasat manual în directorul:

app/code/Kowal/ExportImportCategories

După copierea fișierelor, rulați:

bin/magento module:enable Kowal_ExportImportCategoriesbin/magento setup:upgradebin/magento cache:flush

În modul production, rulați de asemenea:

bin/magento setup:di:compile

Verificarea instalării

După instalare, verificați dacă modulul este activ:

bin/magento module:status Kowal_ExportImportCategories

Modulul ar trebui să se afle pe lista modulelor active.

În panoul de administrare, accesați:

System > Data Transfer > Export/Import Categories

Ar trebui să fie vizibile trei poziții:

• Export Categories,
• Import Categories,
• Import History.

Permisiuni ACL

Modulul adaugă permisiuni administrative separate:

• acces la secțiunea principală Export/Import Categories,
• exportul categoriilor,
• importul categoriilor,
• istoricul importurilor.

Dacă utilizatorul admin nu vede meniul modulului, verificați rolul utilizatorului în:

System > Permissions > User Roles

Apoi acordați permisiunile corespunzătoare pentru resursele modulului.

Locația modulului în panou

Modulul este disponibil la:

System > Data Transfer > Export/Import Categories

Vizualizări:

• Export Categories - exportul categoriilor în CSV.
• Import Categories - importul categoriilor din CSV.
• Import History - istoricul importurilor și rapoarte.

Configurarea exportului

Vizualizarea de export permite generarea unui fișier CSV cu categorii.

Câmpurile exportului

Store View

Selectează store view-ul din care vor fi citite valorile atributelor categoriilor.

Dacă selectați un store view lingvistic, exportul poate conține valori specifice acestui store view sau valori moștenite din scope-ul implicit, în funcție de modul valorilor.

Start Category ID

Câmp opțional care permite limitarea exportului la categoria selectată și subarborele acesteia.

Dacă acest câmp rămâne gol, modulul exportă categoriile începând de la root category a store view-ului selectat.

Store View Value Mode

Stabilește cum sunt exportate valorile dependente de store view.

Variante disponibile:

• resolved_value,
• store_override_only.

resolved_value exportă valoarea vizibilă în store view-ul selectat după luarea în considerare a fallback-ului Magento.

store_override_only exportă doar valoarea suprascrisă pentru store view-ul selectat. Dacă valoarea este moștenită din default scope, celula CSV va fi goală.

CSV Delimiter

Separator CSV. Implicit:

,

Se poate utiliza un alt separator dacă fișierul va fi editat într-un instrument care necesită, de exemplu, punct și virgulă.

Attributes

Lista atributelor de categorie disponibile în Magento.

Modulul preia atributele dinamic din EAV, astfel încât în listă pot apărea și atribute proprii ale categoriilor adăugate în proiect.

Coloanele de sistem sunt adăugate automat și nu trebuie selectate.

Coloane de sistem în export

Exportul trebuie să conțină întotdeauna coloanele de sistem:

• store_view_code,
• entity_id,
• parent_entity_id,
• category_path,
• parent_path,
• level,
• position,
• attribute_set_id.

Aceste coloane servesc la identificarea categoriilor, validarea store view-ului și gestionarea structurii arborelui.

Configurarea importului

Vizualizarea de import permite încărcarea unui CSV și salvarea datelor categoriilor.

Câmpurile importului

Store View

Selectează store view-ul în care vor fi salvate valorile.

Acest câmp decide store_id numeric utilizat la salvarea în tabelele Magento.

Coloana store_view_code din CSV nu este convertită direct în store_id. Este utilizată pentru validarea faptului că fișierul se potrivește cu store view-ul selectat.

Exemplu:

• în formular selectați un store view cu store_id = 1,
• în CSV trebuie să existe store_view_code corespunzător acestui store view,
• modulul salvează datele folosind store_id = 1.

Import Mode

Moduri disponibile:

• update,
• insert.

update actualizează categoriile existente.

insert creează categorii noi.

CSV File

Fișier CSV cu antete în primul rând.

Fișierul trebuie să fie codificat în UTF-8.

CSV Delimiter

Separator CSV. Trebuie să corespundă separatorului utilizat în fișier.

Unknown Columns Policy

Definește comportamentul pentru coloanele care nu sunt nici coloane de sistem, nici atribute cunoscute ale categoriilor.

Variante disponibile:

• error - importul raportează o eroare pentru coloanele necunoscute.
• ignore - coloanele necunoscute sunt ignorate.

Varianta recomandată:

error

Empty Values Policy

Stabilește cum interpretează modulul celulele CSV goale.

Variante disponibile:

• skip_empty,
• clear_value,
• use_default.

skip_empty înseamnă că o celulă goală nu va modifica valoarea curentă.

clear_value înseamnă că o celulă goală va șterge valoarea atributului.

use_default înseamnă că o celulă goală va elimina suprascrierea store view-ului și va permite Magento să utilizeze valoarea implicită.

Varianta recomandată pentru importul de actualizare:

skip_empty

URL Key Strategy

Stabilește modul de gestionare a atributului url_key.

Variante disponibile:

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

use_csv_value salvează url_key din CSV.

generate_from_name generează url_key pe baza valorii name.

keep_existing păstrează url_key existent în modul update.

magento_default lasă gestionarea URL-ului mecanismului standard Magento.

Create permanent redirect for URL key changes

Opțiunea stabilește dacă Magento trebuie să creeze permanent redirect la schimbarea url_key.

Merită activată atunci când schimbarea URL-ului categoriei trebuie să păstreze redirectările SEO de la adresele vechi.

Images Base Directory

Directorul de bază pentru importul imaginilor categoriilor, relativ la pub/media.

Implicit:

import/categories

Calea completă în Magento:

pub/media/import/categories

Dacă în CSV indicați:

gear/bags.jpg

modulul va căuta fișierul:

pub/media/import/categories/gear/bags.jpg

Error Policy

Definește comportamentul importului la erori.

Variante disponibile:

• skip_invalid_rows,
• stop_on_first_error,
• all_or_nothing.

skip_invalid_rows omite rândurile greșite și continuă importul.

stop_on_first_error oprește importul după prima eroare.

all_or_nothing necesită ca întregul fișier să fie corect; dacă apare o eroare, importul nu ar trebui să salveze datele.

Varianta recomandată pentru fișiere mari:

skip_invalid_rows

Batch Size

Numărul de rânduri procesate într-un singur lot.

Implicit:

100

O valoare mai mică reduce consumul de memorie. O valoare mai mare poate accelera importul pe medii mai puternice.

Attributes to Import

Lista atributelor care urmează să fie importate.

Importul actualizează doar atributele selectate. Dacă o coloană există în CSV, dar atributul nu este bifat în formular, modulul nu ar trebui să îl salveze.

Dry Run

Mod de validare fără salvarea datelor.

Se recomandă rularea dry-run înaintea importului propriu-zis, în special pentru fișiere mari sau modificări SEO.

Mod import/update

Modul update servește la actualizarea categoriilor existente.

Date necesare

CSV-ul trebuie să conțină:

• store_view_code,
• entity_id sau category_path,
• cel puțin o coloană a atributului selectat.

Cum funcționează identificarea categoriei

Modulul încearcă să găsească categoria după:

1. entity_id,
2. category_path, dacă entity_id este gol.

entity_id este cel mai bun identificator atunci când importul are loc în același mediu Magento.

category_path este mai portabil între medii, dar trebuie să fie neechivoc.

Exemplu de actualizare a traducerilor

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

Setări de import:

• Store View: store view polonez,
• Import Mode: update,
• Attributes to Import: name, url_key, meta_title, meta_description,
• URL Key Strategy: use_csv_value,
• Empty Values Policy: skip_empty,
• mai întâi Dry Run, apoi importul propriu-zis.

Mod import/insert

Modul insert servește la crearea de categorii noi.

Date necesare

CSV-ul trebuie să conțină:

• store_view_code,
• category_path,
• parent_entity_id sau parent_path,
• name,
• cel puțin o coloană a atributului selectat.

entity_id nu este necesar, deoarece Magento îl atribuie automat.

Exemplu de creare a categoriilor

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

Setări de import:

• 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 sau generate_from_name,
• Error Policy: skip_invalid_rows,
• mai întâi Dry Run.

Lucrul cu select și multiselect

Modulul acceptă select și multiselect pe baza etichetelor opțiunilor.

Nu este necesară indicarea ID-urilor tehnice ale opțiunilor.

Exemplu:

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

Pentru multiselect, mai multe valori se separă cu separatorul:

|

Dacă eticheta nu există sau este ambiguă, importul va raporta o eroare.

Importul imaginilor categoriilor

Înainte de importul imaginilor, plasați fișierele în directorul:

pub/media/import/categories

Exemplu CSV:

store_view_code,entity_id,category_path,image,thumbnaildefault,13,Default Category/Gear/Bags,gear/bags.jpg,gear/bags-thumb.jpg

Setări de import:

• Images Base Directory: import/categories,
• atribute bifate: image, thumbnail.

Modulul va verifica dacă fișierele există și au extensii acceptate.

Raportul de import

După import, modulul generează un raport CSV.

Raportul conține:

• numărul rândului,
• identificatorul categoriei,
• statusul,
• mesajul,
• atributele modificate.

Statusurile pot include:

• success,
• error,
• skipped_no_change,
• skipped_existing.

Istoricul importurilor

Istoricul importurilor este disponibil în:

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

Istoricul conține:

• data importului,
• utilizatorul admin,
• store view,
• modul de import,
• numele fișierului,
• numărul de rânduri,
• numărul de succese,
• numărul de erori,
• informația despre dry-run,
• link pentru descărcarea raportului.

Proces de lucru recomandat

Import de actualizare sigur

1. Exportați categoriile curente.
2. Păstrați fișierul original ca backup.
3. Pregătiți modificările într-o copie CSV.
4. Asigurați-vă că store_view_code corespunde store view-ului țintă.
5. Selectați importul update.
6. Selectați doar atributele pe care doriți să le modificați.
7. Setați Empty Values Policy la skip_empty.
8. Rulați Dry Run.
9. Verificați raportul.
10. Rulați importul propriu-zis.
11. Goliți cache-ul dacă modificările nu sunt vizibile imediat.

Import sigur de categorii noi

1. Pregătiți CSV-ul cu category_path, parent_path sau parent_entity_id.
2. Asigurați-vă că părinții există sau apar mai devreme în fișier.
3. Selectați importul insert.
4. Bifați cel puțin name și alte atribute necesare.
5. Rulați Dry Run.
6. Corectați erorile din raport.
7. Rulați importul propriu-zis.

Cache și indici

După importul modificărilor în categorii, este recomandat să reîmprospătați cache-ul Magento:

bin/magento cache:clean

Dacă magazinul necesită reindexare manuală după modificări mai mari ale catalogului:

bin/magento indexer:reindex

În instalările Magento tipice, salvarea categoriilor prin mecanismele standard Magento ar trebui să declanșeze procesele corespunzătoare asociate modelului de categorie, însă după importurile mari se recomandă verificarea cache-ului și a indicilor.

Cele mai frecvente probleme

Importul raportează un store_view_code incompatibil

Verificați dacă codul din coloana store_view_code corespunde store view-ului selectat în formularul de import.

Importul nu modifică valorile

Verificați:

• dacă atributul a fost bifat în Attributes to Import,
• dacă celula CSV nu este goală,
• dacă Empty Values Policy nu este setat la skip_empty,
• dacă importul nu a fost rulat ca Dry Run.

Select sau multiselect raportează o eroare

Verificați dacă eticheta opțiunii din CSV corespunde exact etichetei opțiunii din Magento pentru store view-ul selectat.

Imaginea nu se importă

Verificați:

• dacă fișierul există în pub/media/import/categories,
• dacă ruta din CSV este corectă,
• dacă extensia fișierului este acceptată,
• dacă atributul imaginii a fost bifat pentru import.

Insert raportează lipsa părintelui

Verificați parent_entity_id sau parent_path. Părintele trebuie să existe în Magento sau să se afle mai devreme în fișierul de import.

Dezinstalarea modulului

Dacă modulul a fost instalat prin Composer:

composer remove kowal/module-export-import-categoriesbin/magento setup:upgradebin/magento cache:flush

Înainte de dezinstalare, asigurați-vă că istoricul importurilor poate fi șters. Modulul creează tabelul:

kowal_export_import_categories_history