Instrukcja instalacji i konfiguracji modułu Kowal_ExportImportCategories

Ten dokument opisuje instalację, konfigurację oraz korzystanie z modułu Kowal_ExportImportCategories dla Magento 2. Instrukcja uwzględnia informacje z pliku README.md oraz funkcje zaimplementowane w module.

Wymagania

• Magento 2.
• PHP zgodny z instalacją Magento, rekomendowane PHP 8.1 lub nowsze.
• Dostęp do CLI Magento.
• Dostęp do Composer.
• Uprawnienia administratora Magento.
• Dostęp do repozytorium modułu.
• Dla importu obrazków: możliwość umieszczania plików w katalogu pub/media/import/categories.

Instalacja przez Composer

Moduł jest dostępny przez repozytorium Composer.

1. Dodaj repozytorium Composer

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

2. Dodaj token dostępu do prywatnego repozytorium GitHub

Jeżeli repozytorium jest prywatne, skonfiguruj token GitHub:

composer config --global --auth github-oauth.github.com <YOUR_TOKEN>

Zastąp <YOUR_TOKEN> własnym tokenem dostępu.

3. Zainstaluj moduł

composer require kowal/module-export-import-categories

4. Włącz moduł w Magento

bin/magento module:enable Kowal_ExportImportCategories

5. Uruchom aktualizację Magento

bin/magento setup:upgrade

6. Wyczyść cache

bin/magento cache:flush

7. Opcjonalnie uruchom kompilację DI

Na środowiskach produkcyjnych albo w trybie production:

bin/magento setup:di:compile

8. Opcjonalnie wdróż statyczne zasoby

Jeżeli środowisko tego wymaga:

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

Instalacja ręczna w app/code

Alternatywnie moduł można umieścić ręcznie w katalogu:

app/code/Kowal/ExportImportCategories

Po skopiowaniu plików uruchom:

bin/magento module:enable Kowal_ExportImportCategories
bin/magento setup:upgrade
bin/magento cache:flush

W trybie production uruchom również:

bin/magento setup:di:compile

Sprawdzenie instalacji

Po instalacji sprawdź, czy moduł jest aktywny:

bin/magento module:status Kowal_ExportImportCategories

Moduł powinien znajdować się na liście aktywnych modułów.

W panelu administracyjnym przejdź do:

System > Data Transfer > Export/Import Categories

Powinny być widoczne trzy pozycje:

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

Uprawnienia ACL

Moduł dodaje osobne uprawnienia administracyjne:

• dostęp do głównej sekcji Export/Import Categories,
• eksport kategorii,
• import kategorii,
• historia importów.

Jeżeli użytkownik admina nie widzi menu modułu, sprawdź rolę użytkownika w:

System > Permissions > User Roles

Następnie nadaj odpowiednie uprawnienia dla zasobów modułu.

Lokalizacja modułu w panelu

Moduł jest dostępny pod:

System > Data Transfer > Export/Import Categories

Widoki:

• Export Categories - eksport kategorii do CSV.
• Import Categories - import kategorii z CSV.
• Import History - historia importów i raporty.

Konfiguracja eksportu

Widok eksportu pozwala wygenerować plik CSV z kategoriami.

Pola eksportu

Store View

Wybiera store view, z którego zostaną odczytane wartości atrybutów kategorii.

Jeżeli wybierzesz store view językowy, eksport może zawierać wartości specyficzne dla tego store view albo wartości odziedziczone z domyślnego scope, zależnie od trybu wartości.

Start Category ID

Opcjonalne pole pozwalające ograniczyć eksport do wybranej kategorii i jej poddrzewa.

Jeżeli pole zostanie puste, moduł eksportuje kategorie od root category wybranego store view.

Store View Value Mode

Określa, jak eksportować wartości zależne od store view.

Dostępne warianty:

• resolved_value,
• store_override_only.

resolved_value eksportuje wartość widoczną w wybranym store view po uwzględnieniu fallbacku Magento.

store_override_only eksportuje tylko wartość nadpisaną dla wybranego store view. Jeżeli wartość jest dziedziczona z default scope, komórka CSV będzie pusta.

CSV Delimiter

Separator CSV. Domyślnie:

,

Można użyć innego separatora, jeżeli plik będzie edytowany w narzędziu wymagającym np. średnika.

Attributes

Lista atrybutów kategorii dostępnych w Magento.

Moduł pobiera atrybuty dynamicznie z EAV, dlatego na liście mogą pojawić się również własne atrybuty kategorii dodane w projekcie.

Kolumny systemowe są dodawane automatycznie i nie trzeba ich wybierać.

Kolumny systemowe w eksporcie

Eksport zawsze powinien zawierać kolumny systemowe:

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

Kolumny te służą do identyfikacji kategorii, walidacji store view oraz obsługi struktury drzewa.

Konfiguracja importu

Widok importu pozwala wczytać CSV i zapisać dane kategorii.

Pola importu

Store View

Wybiera store view, do którego zostaną zapisane wartości.

To pole decyduje o numerycznym store_id używanym przy zapisie w tabelach Magento.

Kolumna store_view_code z CSV nie jest bezpośrednio zamieniana na store_id. Jest używana do walidacji, czy plik pasuje do wybranego store view.

Przykład:

• w formularzu wybierasz store view o store_id = 1,
• w CSV musi być store_view_code odpowiadający temu store view,
• moduł zapisuje dane z użyciem store_id = 1.

Import Mode

Dostępne tryby:

• update,
• insert.

update aktualizuje istniejące kategorie.

insert tworzy nowe kategorie.

CSV File

Plik CSV z nagłówkami w pierwszym wierszu.

Plik powinien być zakodowany w UTF-8.

CSV Delimiter

Separator CSV. Musi odpowiadać separatorowi użytemu w pliku.

Unknown Columns Policy

Określa zachowanie dla kolumn, które nie są ani kolumnami systemowymi, ani znanymi atrybutami kategorii.

Dostępne warianty:

• error - import zgłasza błąd dla nieznanych kolumn.
• ignore - nieznane kolumny są ignorowane.

Rekomendowany wariant:

error

Empty Values Policy

Określa, jak moduł interpretuje puste komórki CSV.

Dostępne warianty:

• skip_empty,
• clear_value,
• use_default.

skip_empty oznacza, że pusta komórka nie zmieni obecnej wartości.

clear_value oznacza, że pusta komórka wyczyści wartość atrybutu.

use_default oznacza, że pusta komórka usunie nadpisanie store view i pozwoli Magento użyć wartości domyślnej.

Rekomendowany wariant dla importu aktualizacyjnego:

skip_empty

URL Key Strategy

Określa sposób obsługi atrybutu url_key.

Dostępne warianty:

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

use_csv_value zapisuje url_key z CSV.

generate_from_name generuje url_key na podstawie wartości name.

keep_existing zachowuje istniejący url_key w trybie update.

magento_default zostawia obsługę URL standardowemu mechanizmowi Magento.

Create permanent redirect for URL key changes

Opcja określa, czy Magento ma utworzyć permanent redirect przy zmianie url_key.

Warto ją włączyć, gdy zmiana URL kategorii ma zachować przekierowania SEO ze starych adresów.

Images Base Directory

Katalog bazowy dla importu obrazków kategorii względem pub/media.

Domyślnie:

import/categories

Pełna ścieżka w Magento:

pub/media/import/categories

Jeżeli w CSV podasz:

gear/bags.jpg

moduł będzie szukał pliku:

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

Error Policy

Określa zachowanie importu przy błędach.

Dostępne warianty:

• skip_invalid_rows,
• stop_on_first_error,
• all_or_nothing.

skip_invalid_rows pomija błędne wiersze i kontynuuje import.

stop_on_first_error zatrzymuje import po pierwszym błędzie.

all_or_nothing wymaga poprawności całego pliku; jeżeli wystąpi błąd, import nie powinien zapisać danych.

Rekomendowany wariant dla dużych plików:

skip_invalid_rows

Batch Size

Liczba wierszy przetwarzanych w jednej partii.

Domyślnie:

100

Niższa wartość ogranicza zużycie pamięci. Wyższa wartość może przyspieszyć import na mocniejszych środowiskach.

Attributes to Import

Lista atrybutów, które mają zostać zaimportowane.

Import aktualizuje tylko wybrane atrybuty. Jeżeli kolumna istnieje w CSV, ale atrybut nie zostanie zaznaczony w formularzu, moduł nie powinien go zapisać.

Dry Run

Tryb walidacji bez zapisu danych.

Rekomendowane jest uruchomienie dry-run przed właściwym importem, szczególnie dla dużych plików albo zmian SEO.

Tryb import/update

Tryb update służy do aktualizacji istniejących kategorii.

Wymagane dane

CSV musi zawierać:

• store_view_code,
• entity_id albo category_path,
• co najmniej jedną kolumnę wybranego atrybutu.

Jak działa identyfikacja kategorii

Moduł próbuje znaleźć kategorię po:

1. entity_id,
2. category_path, jeżeli entity_id jest puste.

entity_id jest najlepszym identyfikatorem, gdy import odbywa się na tym samym środowisku Magento.

category_path jest bardziej przenośny między środowiskami, ale musi być jednoznaczny.

Przykład aktualizacji tłumaczeń

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

Ustawienia importu:

• Store View: polski store view,
• Import Mode: update,
• Attributes to Import: name, url_key, meta_title, meta_description,
• URL Key Strategy: use_csv_value,
• Empty Values Policy: skip_empty,
• najpierw Dry Run, potem właściwy import.

Tryb import/insert

Tryb insert służy do tworzenia nowych kategorii.

Wymagane dane

CSV musi zawierać:

• store_view_code,
• category_path,
• parent_entity_id albo parent_path,
• name,
• co najmniej jedną kolumnę wybranego atrybutu.

entity_id nie jest wymagane, ponieważ Magento nadaje je automatycznie.

Przykład tworzenia kategorii

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

Ustawienia importu:

• 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 albo generate_from_name,
• Error Policy: skip_invalid_rows,
• najpierw Dry Run.

Praca z select i multiselect

Moduł obsługuje select i multiselect po labelach opcji.

Nie trzeba podawać technicznych ID opcji.

Przykład:

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

Dla multiselect wiele wartości rozdziela się separatorem:

|

Jeżeli label nie istnieje albo jest niejednoznaczny, import zgłosi błąd.

Import obrazków kategorii

Przed importem obrazków umieść pliki w katalogu:

pub/media/import/categories

Przykład CSV:

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

Ustawienia importu:

• Images Base Directory: import/categories,
• zaznaczone atrybuty: image, thumbnail.

Moduł sprawdzi, czy pliki istnieją i mają obsługiwane rozszerzenia.

Raport importu

Po imporcie moduł generuje raport CSV.

Raport zawiera:

• numer wiersza,
• identyfikator kategorii,
• status,
• komunikat,
• zmienione atrybuty.

Statusy mogą obejmować:

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

Historia importów

Historia importów jest dostępna w:

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

Historia zawiera:

• datę importu,
• użytkownika admina,
• store view,
• tryb importu,
• nazwę pliku,
• liczbę wierszy,
• liczbę sukcesów,
• liczbę błędów,
• informację o dry-run,
• link do pobrania raportu.

Zalecany proces pracy

Bezpieczny import aktualizacyjny

1. Wykonaj eksport aktualnych kategorii.
2. Zachowaj oryginalny plik jako backup.
3. Przygotuj zmiany w kopii CSV.
4. Upewnij się, że store_view_code odpowiada docelowemu store view.
5. Wybierz import update.
6. Wybierz tylko atrybuty, które chcesz zmienić.
7. Ustaw Empty Values Policy na skip_empty.
8. Uruchom Dry Run.
9. Sprawdź raport.
10. Uruchom właściwy import.
11. Wyczyść cache, jeżeli zmiany nie są widoczne od razu.

Bezpieczny import nowych kategorii

1. Przygotuj CSV z category_path, parent_path albo parent_entity_id.
2. Upewnij się, że rodzice istnieją albo występują wcześniej w pliku.
3. Wybierz import insert.
4. Zaznacz minimum name oraz inne wymagane atrybuty.
5. Uruchom Dry Run.
6. Popraw błędy z raportu.
7. Uruchom właściwy import.

Cache i indeksy

Po imporcie zmian w kategoriach warto odświeżyć cache Magento:

bin/magento cache:clean

Jeżeli sklep wymaga ręcznej reindeksacji po większych zmianach katalogu:

bin/magento indexer:reindex

W typowych instalacjach Magento zapis kategorii przez standardowe mechanizmy Magento powinien uruchamiać właściwe procesy powiązane z modelem kategorii, ale po dużych importach zalecana jest kontrola cache i indeksów.

Najczęstsze problemy

Import zgłasza niezgodny store_view_code

Sprawdź, czy kod w kolumnie store_view_code odpowiada store view wybranemu w formularzu importu.

Import nie zmienia wartości

Sprawdź:

• czy atrybut został zaznaczony w Attributes to Import,
• czy komórka CSV nie jest pusta,
• czy Empty Values Policy nie jest ustawione na skip_empty,
• czy import nie był uruchomiony jako Dry Run.

Select albo multiselect zgłasza błąd

Sprawdź, czy label opcji w CSV dokładnie odpowiada labelowi opcji w Magento dla wybranego store view.

Obrazek nie importuje się

Sprawdź:

• czy plik istnieje w pub/media/import/categories,
• czy ścieżka w CSV jest poprawna,
• czy rozszerzenie pliku jest obsługiwane,
• czy atrybut obrazka został zaznaczony do importu.

Insert zgłasza brak rodzica

Sprawdź parent_entity_id albo parent_path. Rodzic musi istnieć w Magento albo znajdować się wcześniej w pliku importu.

Odinstalowanie modułu

Jeżeli moduł był instalowany przez Composer:

composer remove kowal/module-export-import-categories
bin/magento setup:upgrade
bin/magento cache:flush

Przed odinstalowaniem upewnij się, czy historia importów może zostać usunięta. Moduł tworzy tabelę:

kowal_export_import_categories_history