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, se recomandă PHP 8.1 sau mai nou.
• Acces la CLI Magento.
• Acces la Composer.
• Drepturi 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-ul Composer.

1. Adăugați repository-ul Composer

Datele de acces la repository-ul Composer adresa de e-mail a clientului și tokenul de licență le veți primi prin e-mail după achiziție. Sunt disponibile și în panoul clientului după autentificarea pe kowal.store. Înlocuiți TWOJ_EMAIL_KLIENTA cu adresa de e-mail a contului dvs., iar TWOJ_TOKEN cu tokenul primit. Executați comenzile în directorul rădăcină Magento.

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

2. Configurați accesul la repository-ul Composer Kowal

Configurați datele de acces la repository-ul Composer Kowal:

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

Î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, deployați resursele statice

Dacă mediul o impune:

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 și:

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.

Localizarea 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âmpuri de export

Store View

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

Dacă selectați un store view lingvistic, exportul poate conține valori specifice pentru acel 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 cu root category a store view-ului selectat.

Store View Value Mode

Definește modul de export al valorilor dependente de store view.

Variante disponibile:

• resolved_value,
• store_override_only.

resolved_value exportă valoarea vizibilă în store view-ul selectat după aplicarea 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 categoriilor disponibile în Magento.

Modulul preia dinamic atributele 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 ar trebui să conțină întotdeauna coloane de sistem:

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

Aceste coloane sunt utilizate pentru identificarea categoriilor, validarea store view-ului și gestionarea structurii arborescente.

Configurarea importului

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

Câmpuri de import

Store View

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

Acest câmp decide valoarea numerică store_id 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 corespunde store view-ului selectat.

Exemplu:

• în formular selectați un store view cu store_id = 1,
• în CSV trebuie să existe store_view_code corespunzător acelui 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.

Variantă recomandată:

error

Empty Values Policy

Definește modul în care modulul interpretează 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ă.

Variantă recomandată pentru importul de actualizare:

skip_empty

URL Key Strategy

Defineș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 un permanent redirect la modificarea url_key.

Merită activată atunci când modificarea URL-ului categoriei trebuie să păstreze redirecționă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 introduceți:

gear/bags.jpg

modulul va căuta fișierul:

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

Error Policy

Definește comportamentul importului în cazul erorilor.

Variante disponibile:

• skip_invalid_rows,
• stop_on_first_error,
• all_or_nothing.

skip_invalid_rows omite rândurile eronate ș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 date.

Variantă recomandată pentru fișiere mari:

skip_invalid_rows

Batch Size

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

Implicit:

100

O valoare mai mică limitează 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 înainte de importul propriu-zis, în special pentru fișiere mari sau modificări SEO.

Modul import/update

Modul update este utilizat pentru actualizarea categoriilor existente.

Date necesare

CSV trebuie să conțină:

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

Cum funcționează identificarea categoriilor

Modulul încearcă să găsească o categorie după:

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

entity_id este cel mai bun identificator atunci când importul se realizează pe același mediu Magento.

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

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.

Modul import/insert

Modul insert este utilizat pentru crearea de categorii noi.

Date necesare

CSV 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 gestionează select și multiselect pe baza labelurilor opțiunilor.

Nu este necesar să furnizați ID-urile 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, valorile multiple se separă cu separatorul:

|

Dacă labelul nu există sau este ambiguu, 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.

Raport 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ții despre dry-run,
• link pentru descărcarea raportului.

Proces de lucru recomandat

Import de actualizare sigur

1. Efectuați exportul categoriilor actuale.
2. Păstrați fișierul original ca backup.
3. Pregătiți modificările într-o copie a CSV-ului.
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 indexuri

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 ample ale catalogului:

bin/magento indexer:reindex

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

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ă labelul opțiunii din CSV corespunde exact labelului 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ă calea 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