Installations- und Konfigurationsanleitung für das Modul Kowal_ExportImportCategories

Dieses Dokument beschreibt die Installation, Konfiguration und Nutzung des Moduls Kowal_ExportImportCategories für Magento 2. Die Anleitung berücksichtigt Informationen aus der Datei README.md sowie die im Modul implementierten Funktionen.

Anforderungen

• Magento 2.
• PHP kompatibel mit der Magento-Installation, empfohlen PHP 8.1 oder neuer.
• Zugriff auf Magento CLI.
• Zugriff auf Composer.
• Magento-Administratorrechte.
• Zugriff auf das Modul-Repository.
• Für den Bildimport: Möglichkeit, Dateien im Verzeichnis pub/media/import/categories abzulegen.

Installation über Composer

Das Modul ist über ein Composer-Repository verfügbar.

1. Composer-Repository hinzufügen

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

2. Zugriffstoken für das private GitHub-Repository hinzufügen

Wenn das Repository privat ist, konfigurieren Sie den GitHub-Token:

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

Ersetzen Sie  durch Ihren eigenen Zugriffstoken.

3. Modul installieren

composer require kowal/module-export-import-categories

4. Modul in Magento aktivieren

bin/magento module:enable Kowal_ExportImportCategories

5. Magento-Update ausführen

bin/magento setup:upgrade

6. Cache leeren

bin/magento cache:flush

7. Optional DI-Kompilierung ausführen

Auf Produktionsumgebungen oder im production-Modus:

bin/magento setup:di:compile

8. Optional statische Assets bereitstellen

Wenn die Umgebung dies erfordert:

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

Manuelle Installation in app/code

Alternativ kann das Modul manuell im Verzeichnis abgelegt werden:

app/code/Kowal/ExportImportCategories

Nach dem Kopieren der Dateien führen Sie aus:

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

Im production-Modus führen Sie zusätzlich aus:

bin/magento setup:di:compile

Installation prüfen

Prüfen Sie nach der Installation, ob das Modul aktiv ist:

bin/magento module:status Kowal_ExportImportCategories

Das Modul sollte in der Liste der aktiven Module enthalten sein.

Gehen Sie im Adminbereich zu:

System > Data Transfer > Export/Import Categories

Es sollten drei Einträge sichtbar sein:

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

ACL-Berechtigungen

Das Modul fügt separate Administratorberechtigungen hinzu:

• Zugriff auf den Hauptbereich Export/Import Categories,
• Kategorieexport,
• Kategorieimport,
• Importhistorie.

Wenn ein Admin-Benutzer das Modulmenü nicht sieht, prüfen Sie die Benutzerrolle unter:

System > Permissions > User Roles

Vergeben Sie anschließend die entsprechenden Berechtigungen für die Modulressourcen.

Position des Moduls im Adminbereich

Das Modul ist verfügbar unter:

System > Data Transfer > Export/Import Categories

Ansichten:

• Export Categories - Export von Kategorien nach CSV.
• Import Categories - Import von Kategorien aus CSV.
• Import History - Importhistorie und Berichte.

Exportkonfiguration

Die Exportansicht ermöglicht die Erstellung einer CSV-Datei mit Kategorien.

Exportfelder

Store View

Wählt die Store View aus, aus der die Werte der Kategorieattribute gelesen werden.

Wenn Sie eine Sprach-Store-View auswählen, kann der Export je nach Wertemodus entweder spezifische Werte für diese Store View oder aus dem Default Scope geerbte Werte enthalten.

Start Category ID

Optionales Feld, mit dem der Export auf eine ausgewählte Kategorie und ihren Unterbaum beschränkt werden kann.

Wenn das Feld leer bleibt, exportiert das Modul Kategorien ab der Root Category der ausgewählten Store View.

Store View Value Mode

Legt fest, wie von der Store View abhängige Werte exportiert werden.

Verfügbare Varianten:

• resolved_value,
• store_override_only.

resolved_value exportiert den in der ausgewählten Store View sichtbaren Wert unter Berücksichtigung des Magento-Fallbacks.

store_override_only exportiert nur den für die ausgewählte Store View überschriebenen Wert. Wenn der Wert aus dem Default Scope geerbt wird, bleibt die CSV-Zelle leer.

CSV Delimiter

CSV-Trennzeichen. Standardmäßig:

,

Es kann ein anderes Trennzeichen verwendet werden, wenn die Datei in einem Tool bearbeitet wird, das z. B. ein Semikolon erfordert.

Attributes

Liste der in Magento verfügbaren Kategorieattribute.

Das Modul liest Attribute dynamisch aus EAV aus, daher können in der Liste auch eigene Kategorieattribute erscheinen, die im Projekt hinzugefügt wurden.

Systemspalten werden automatisch hinzugefügt und müssen nicht ausgewählt werden.

Systemspalten im Export

Der Export sollte immer Systemspalten enthalten:

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

Diese Spalten dienen der Identifikation von Kategorien, der Validierung der Store View und der Verarbeitung der Baumstruktur.

Importkonfiguration

Die Importansicht ermöglicht das Einlesen einer CSV-Datei und das Speichern von Kategoriedaten.

Importfelder

Store View

Wählt die Store View aus, in der die Werte gespeichert werden.

Dieses Feld bestimmt die numerische store_id, die beim Speichern in Magento-Tabellen verwendet wird.

Die Spalte store_view_code aus der CSV wird nicht direkt in store_id umgewandelt. Sie wird zur Validierung verwendet, ob die Datei zur ausgewählten Store View passt.

Beispiel:

• im Formular wählen Sie eine Store View mit store_id = 1,
• in der CSV muss store_view_code enthalten sein, der dieser Store View entspricht,
• das Modul speichert die Daten unter Verwendung von store_id = 1.

Import Mode

Verfügbare Modi:

• update,
• insert.

update aktualisiert bestehende Kategorien.

insert erstellt neue Kategorien.

CSV File

CSV-Datei mit Headern in der ersten Zeile.

Die Datei sollte in UTF-8 kodiert sein.

CSV Delimiter

CSV-Trennzeichen. Es muss dem in der Datei verwendeten Trennzeichen entsprechen.

Unknown Columns Policy

Legt das Verhalten für Spalten fest, die weder Systemspalten noch bekannte Kategorieattribute sind.

Verfügbare Varianten:

• error - der Import meldet einen Fehler für unbekannte Spalten.
• ignore - unbekannte Spalten werden ignoriert.

Empfohlene Variante:

error

Empty Values Policy

Legt fest, wie das Modul leere CSV-Zellen interpretiert.

Verfügbare Varianten:

• skip_empty,
• clear_value,
• use_default.

skip_empty bedeutet, dass eine leere Zelle den aktuellen Wert nicht ändert.

clear_value bedeutet, dass eine leere Zelle den Attributwert löscht.

use_default bedeutet, dass eine leere Zelle die Store-View-Überschreibung entfernt und Magento erlaubt, den Standardwert zu verwenden.

Empfohlene Variante für Aktualisierungsimporte:

skip_empty

URL Key Strategy

Legt fest, wie das Attribut url_key behandelt wird.

Verfügbare Varianten:

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

use_csv_value speichert url_key aus der CSV.

generate_from_name generiert url_key auf Basis des Werts name.

keep_existing behält im Modus update den bestehenden url_key bei.

magento_default überlässt die URL-Behandlung dem Standardmechanismus von Magento.

Create permanent redirect for URL key changes

Diese Option legt fest, ob Magento bei einer Änderung von url_key einen Permanent Redirect erstellen soll.

Es lohnt sich, sie zu aktivieren, wenn eine Änderung der Kategorie-URL SEO-Weiterleitungen von alten Adressen erhalten soll.

Images Base Directory

Basisverzeichnis für den Import von Kategoriebildern relativ zu pub/media.

Standardmäßig:

import/categories

Vollständiger Pfad in Magento:

pub/media/import/categories

Wenn Sie in der CSV Folgendes angeben:

gear/bags.jpg

sucht das Modul nach der Datei:

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

Error Policy

Legt das Importverhalten bei Fehlern fest.

Verfügbare Varianten:

• skip_invalid_rows,
• stop_on_first_error,
• all_or_nothing.

skip_invalid_rows überspringt fehlerhafte Zeilen und setzt den Import fort.

stop_on_first_error stoppt den Import nach dem ersten Fehler.

all_or_nothing erfordert die Korrektheit der gesamten Datei; wenn ein Fehler auftritt, sollte der Import keine Daten speichern.

Empfohlene Variante für große Dateien:

skip_invalid_rows

Batch Size

Anzahl der in einem Batch verarbeiteten Zeilen.

Standardmäßig:

100

Ein niedrigerer Wert reduziert den Speicherverbrauch. Ein höherer Wert kann den Import auf leistungsfähigeren Umgebungen beschleunigen.

Attributes to Import

Liste der Attribute, die importiert werden sollen.

Der Import aktualisiert nur die ausgewählten Attribute. Wenn eine Spalte in der CSV vorhanden ist, das Attribut im Formular jedoch nicht ausgewählt wurde, sollte das Modul es nicht speichern.

Dry Run

Validierungsmodus ohne Datenspeicherung.

Es wird empfohlen, dry-run vor dem eigentlichen Import auszuführen, insbesondere bei großen Dateien oder SEO-Änderungen.

Modus import/update

Der Modus update dient zur Aktualisierung bestehender Kategorien.

Erforderliche Daten

Die CSV muss enthalten:

• store_view_code,
• entity_id oder category_path,
• mindestens eine Spalte eines ausgewählten Attributs.

So funktioniert die Kategorieidentifikation

Das Modul versucht, die Kategorie zu finden über:

1. entity_id,
2. category_path, wenn entity_id leer ist.

entity_id ist der beste Identifikator, wenn der Import in derselben Magento-Umgebung erfolgt.

category_path ist zwischen Umgebungen besser übertragbar, muss jedoch eindeutig sein.

Beispiel für die Aktualisierung von Übersetzungen

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

Importeinstellungen:

• Store View: polnische 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,
• zuerst Dry Run, danach der eigentliche Import.

Modus import/insert

Der Modus insert dient zur Erstellung neuer Kategorien.

Erforderliche Daten

Die CSV muss enthalten:

• store_view_code,
• category_path,
• parent_entity_id oder parent_path,
• name,
• mindestens eine Spalte eines ausgewählten Attributs.

entity_id ist nicht erforderlich, da Magento sie automatisch vergibt.

Beispiel für die Erstellung von Kategorien

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

Importeinstellungen:

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

Arbeiten mit select und multiselect

Das Modul unterstützt select und multiselect über Optionslabels.

Technische Options-IDs müssen nicht angegeben werden.

Beispiel:

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

Bei multiselect werden mehrere Werte durch das Trennzeichen getrennt:

|

Wenn das Label nicht existiert oder nicht eindeutig ist, meldet der Import einen Fehler.

Import von Kategoriebildern

Legen Sie vor dem Import von Bildern die Dateien im Verzeichnis ab:

pub/media/import/categories

CSV-Beispiel:

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

Importeinstellungen:

• Images Base Directory: import/categories,
• ausgewählte Attribute: image, thumbnail.

Das Modul prüft, ob die Dateien existieren und unterstützte Erweiterungen haben.

Importbericht

Nach dem Import generiert das Modul einen CSV-Bericht.

Der Bericht enthält:

• Zeilennummer,
• Kategorie-ID,
• Status,
• Meldung,
• geänderte Attribute.

Statuswerte können umfassen:

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

Importhistorie

Die Importhistorie ist verfügbar unter:

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

Die Historie enthält:

• Importdatum,
• Admin-Benutzer,
• Store View,
• Importmodus,
• Dateiname,
• Anzahl der Zeilen,
• Anzahl der erfolgreichen Vorgänge,
• Anzahl der Fehler,
• Information zu dry-run,
• Download-Link für den Bericht.

Empfohlener Arbeitsprozess

Sicherer Aktualisierungsimport

1. Exportieren Sie die aktuellen Kategorien.
2. Bewahren Sie die Originaldatei als Backup auf.
3. Bereiten Sie Änderungen in einer Kopie der CSV vor.
4. Stellen Sie sicher, dass store_view_code der Ziel-Store-View entspricht.
5. Wählen Sie den Import update.
6. Wählen Sie nur die Attribute aus, die Sie ändern möchten.
7. Setzen Sie Empty Values Policy auf skip_empty.
8. Führen Sie Dry Run aus.
9. Prüfen Sie den Bericht.
10. Führen Sie den eigentlichen Import aus.
11. Leeren Sie den Cache, wenn die Änderungen nicht sofort sichtbar sind.

Sicherer Import neuer Kategorien

1. Bereiten Sie eine CSV mit category_path, parent_path oder parent_entity_id vor.
2. Stellen Sie sicher, dass die übergeordneten Kategorien existieren oder früher in der Datei vorkommen.
3. Wählen Sie den Import insert.
4. Wählen Sie mindestens name sowie andere erforderliche Attribute aus.
5. Führen Sie Dry Run aus.
6. Korrigieren Sie die Fehler aus dem Bericht.
7. Führen Sie den eigentlichen Import aus.

Cache und Indizes

Nach dem Import von Kategorieänderungen empfiehlt es sich, den Magento-Cache zu aktualisieren:

bin/magento cache:clean

Wenn der Shop nach größeren Katalogänderungen eine manuelle Reindizierung erfordert:

bin/magento indexer:reindex

In typischen Magento-Installationen sollte das Speichern von Kategorien über die Standardmechanismen von Magento die entsprechenden Prozesse im Zusammenhang mit dem Kategoriemodell auslösen, nach großen Importen wird jedoch eine Kontrolle von Cache und Indizes empfohlen.

Häufige Probleme

Der Import meldet einen nicht übereinstimmenden store_view_code

Prüfen Sie, ob der Code in der Spalte store_view_code der im Importformular ausgewählten Store View entspricht.

Der Import ändert keine Werte

Prüfen Sie:

• ob das Attribut in Attributes to Import ausgewählt wurde,
• ob die CSV-Zelle nicht leer ist,
• ob Empty Values Policy nicht auf skip_empty gesetzt ist,
• ob der Import nicht als Dry Run ausgeführt wurde.

Select oder multiselect meldet einen Fehler

Prüfen Sie, ob das Optionslabel in der CSV exakt dem Optionslabel in Magento für die ausgewählte Store View entspricht.

Das Bild wird nicht importiert

Prüfen Sie:

• ob die Datei in pub/media/import/categories existiert,
• ob der Pfad in der CSV korrekt ist,
• ob die Dateierweiterung unterstützt wird,
• ob das Bildattribut für den Import ausgewählt wurde.

Insert meldet einen fehlenden Parent

Prüfen Sie parent_entity_id oder parent_path. Der Parent muss in Magento existieren oder früher in der Importdatei enthalten sein.

Deinstallation des Moduls

Wenn das Modul über Composer installiert wurde:

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

Stellen Sie vor der Deinstallation sicher, ob die Importhistorie gelöscht werden darf. Das Modul erstellt die Tabelle:

kowal_export_import_categories_history