Wenn Sie lange genug mit Shopware gearbeitet haben, stoßen Sie auf die gleiche Hürde, auf die jeder Entwickler stößt: Die Standard-Entitätsfelder decken nicht alles ab, was Ihr Shop benötigt. Möglicherweise müssen Sie einen Lieferantencode auf einem Produkt speichern, einem Kunden eine Steuerbefreiungskennzeichnung hinzufügen oder ein benutzerdefiniertes Attribut bei Bestellungen verfolgen. Genau dafür sind die benutzerdefinierten Felder von Shopware 6 konzipiert.
Dieser Leitfaden führt Sie durch den gesamten Prozess – von der Einrichtung Ihrer Shopware Entitätsdefinition bis hin zur Bearbeitung Ihres benutzerdefinierten Felds im Administrationsbereich. Egal, ob Sie Ihr erstes Shopware Plugin erstellen oder ein bestehendes erweitern, dies ist die Referenz, die Sie brauchen.
Was sind benutzerdefinierte Felder in Shopware 6?
Bevor Sie Code schreiben, sollten Sie verstehen, was benutzerdefinierte Felder eigentlich sind und wann Sie sie verwenden.
Shopware 6 Custom Fields sind zusätzliche, benutzerdefinierte Datenfelder, mit denen Sie die Standard-Datenbankstruktur Ihres E-Commerce-Shops erweitern können, ohne die Kerncodebasis zu ändern. Sie funktionieren wie flexible „Metadaten-Container“, die zusätzliche Informationen zu Kerneinheiten wie Produkten, Kategorien, Bestellungen oder Kunden hinzufügen.
Voraussetzungen
- Eine funktionierende Shopware 6 Entwicklungsumgebung
- Ein Basic Shopware Plugin Einrichten und Ausführen (das Plugin Base Guide deckt dies ab)
- Vertrautheit mit dem Data Abstraction Layer (DAL) von Shopware
- Eine vorhandene benutzerdefinierte Entität – idealerweise gemäß der Anleitung zum Hinzufügen benutzerdefinierter komplexer Daten erstellt
#1 Hinzufügen von benutzerdefinierter Feldunterstützung zu Ihrer Entität
Shopware Entitätsdefinition – Hinzufügen des CustomFields-Felds
Der erste Schritt besteht darin, Ihre Shopware Entitätsdefinition so zu aktualisieren, dass sie das CustomFields-DAL-Feld enthält. Öffnen Sie Ihre Entitätsdefinitionsdatei und fügen Sie sie der FieldCollection hinzu.
So sieht eine grundlegende Entitätsdefinition mit hinzugefügter Unterstützung für benutzerdefinierte Felder aus:
// <plugin root>/src/Core/Content/Example/ExampleDefinition.php
use Shopware\Core\Framework\DataAbstractionLayer\Field\CustomFields;
class ExampleDefinition extends EntityDefinition
{
protected function defineFields(): FieldCollection
{
return new FieldCollection([
(new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
(new StringField('name', 'name')),
(new StringField('description', 'description')),
(new BoolField('active', 'active')),
new CustomFields()
]);
}
}
Das Neue CustomFields() Auf der Definitionsebene genügt eine Zeile am Ende. Dieser eine Zusatz teilt Shopware mit, dass diese Entität benutzerdefinierte Felder unterstützt.
#2 Hinzufügen von benutzerdefinierter Feldunterstützung zu Ihrer Entität
Die Änderung der Entitätsdefinition allein reicht nicht aus – Sie benötigen auch eine entsprechende Spalte „custom_fields“ in Ihrer Datenbanktabelle. Dies geschieht durch eine Migration.
Fügen Sie in Ihrer vorhandenen Migrationsdatei die Spalte „custom_fields“ als JSON-Typ mit dem Standardwert NULL hinzu:
// <plugin root>/src/Migration/Migration1611664789Example.php
public function update(Connection $connection): void
{
$sql = <<<SQL
CREATE TABLE IF NOT EXISTS `swag_example` (
`id` BINARY(16) NOT NULL,
`name` VARCHAR(255) COLLATE utf8mb4_unicode_ci,
`description` VARCHAR(255) COLLATE utf8mb4_unicode_ci,
`active` TINYINT(1) COLLATE utf8mb4_unicode_ci,
`custom_fields` json DEFAULT NULL,
`created_at` DATETIME(3) NOT NULL,
`updated_at` DATETIME(3),
PRIMARY KEY (`id`)
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE = utf8mb4_unicode_ci;
SQL;
$connection->executeStatement($sql);
}
Die Spalte muss vom Typ JSON sein und sollte standardmäßig NULL sein. Nicht jede Entitätsinstanz verfügt über benutzerdefinierte Felddaten, daher ist NULL der korrekte Standardwert und nicht ein leeres JSON-Objekt.
#3 Hinzufügen eines übersetzbaren benutzerdefinierten Felds – Shopware Entity-Extension-Ansatz
Wenn Ihr Shop in mehreren Sprachen betrieben wird, möchten Sie, dass Ihre benutzerdefinierten Felder übersetzbar sind. Hier kommt ein Shopware Entity-Extension-Ansatz mit TranslatedField ins Spiel.
Tauschen Sie in Ihrer Entitätsdefinition CustomFields gegen TranslatedField aus:
// <plugin root>/src/Core/Content/Example/ExampleDefinition.php
use Shopware\Core\Framework\DataAbstractionLayer\Field\TranslatedField;
protected function defineFields(): FieldCollection
{
return new FieldCollection([
(new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
(new StringField('name', 'name')),
(new StringField('description', 'description')),
(new BoolField('active', 'active')),
new TranslatedField('customFields'),
]);
}
Fügen Sie dann in Ihrer Übersetzungsdefinition das Feld „CustomFields“ hinzu:
// ExampleTranslationDefinition.php
use Shopware\Core\Framework\DataAbstractionLayer\Field\CustomFields;
protected function defineFields(): FieldCollection
{
return new FieldCollection([
(new StringField('name', 'name'))->addFlags(new Required()),
new CustomFields()
]);
}
Dieses Muster ist der standardmäßige Anpassungsansatz des Shopware 6 Plugins für übersetzbare Entitäten – das TranslatedField befindet sich in der Hauptdefinition und das eigentliche CustomFields-Feld befindet sich in der Übersetzungsdefinition.
Teil 2: Daten in benutzerdefinierte Felder schreiben
So fügen Sie benutzerdefinierte Felder in Shopware 6 hinzu – Werte über die DAL schreiben
Sobald Ihre Entität benutzerdefinierte Felder unterstützt, können Sie sofort damit beginnen, Daten in diese Felder zu schreiben, noch bevor Sie einen formellen benutzerdefinierten Feldsatz definieren. Shopware validiert benutzerdefinierte Felddaten erst, wenn Sie das Feld in einem Set definieren, sodass Sie jeden gültigen JSON-Wert direkt schreiben können.
Als führendes Shopware Entwicklungsunternehmen in Stuttgart, Deutschland, iCreative Technologies ist seit 2014 ein vertrauenswürdiger Shopware Entwicklungspartner und liefert erfolgreich 280 Projekte auf Unternehmensebene über verschiedene Branchen hinweg.
Mit der Shopware Bronze-Partner-Zertifizierung und aktiven Beiträgen zur Shopware Community hat sich iCreative Technologies als vertrauenswürdige Shopware Entwicklungsagentur und zertifizierter Shopware Lösungsanbieter in Deutschland etabliert. Das Unternehmen ist für die Bereitstellung skalierbarer, leistungsstarker E-Commerce-Lösungen bekannt, die auf die besonderen Bedürfnisse von Unternehmen weltweit zugeschnitten sind.
So schreiben Sie mit Ihrem Entitäts-Repository einen benutzerdefinierten Feldwert:
$this->swagExampleRepository->upsert([[
'id' => '<your ID here>',
'customFields' => ['swag_example_size' => 15]
]], $context);
Dadurch wird das benutzerdefinierte Feld gespeichert swag_example_size mit dem Wert 15 für Ihre Entität. Zu diesem Zeitpunkt ist keine vorherige Felddefinition erforderlich.
Sie können auch mehrere Werte in einem Vorgang schreiben:
$this->swagExampleRepository->upsert([[
'id' => '<your ID here>',
'customFields' => ['foo' => 'bar', 'baz' => []]
]], $context);
Beide werden fehlerfrei ausgeführt, da noch keine Validierung erfolgt. Die Daten gehen direkt in die JSON-Spalte.
Teil 3: Benutzerdefinierte Felder für die Verwaltung definieren
Shopware benutzerdefiniertes Feld hinzufügen – im Admin-Bereich bearbeitbar machen
Das Schreiben von Daten per Code ist nützlich für automatisierte Prozesse und Entwicklung individueller Shopware Geschäftslogik, aber in den meisten realen Szenarien muss Ihr Shop-Administrator diese Felder über das Administrationspanel bearbeiten. Dazu müssen Sie einen benutzerdefinierten Feldsatz formal definieren.
Hier ist die custom_field_set.repository kommt rein. Benutze es erstellen Methode zum Registrieren Ihres Feldsatzes:
use Shopware\Core\System\CustomField\CustomFieldTypes;
$this->customFieldSetRepository->create([
[
'name' => 'swag_example_set',
'config' => [
'label' => [
'en-GB' => 'English custom field set label',
'de-DE' => 'German custom field set label'
]
],
'customFields' => [
[
'name' => 'swag_example_size',
'type' => CustomFieldTypes::INT,
'config' => [
'label' => [
'en-GB' => 'English custom field label',
'de-DE' => 'German custom field label'
],
'customFieldPosition' => 1
]
]
]
]
], $context);
Hier ein paar Dinge, die es zu beachten gilt:
- Der Feldtyp ist wichtig. Der Typwert teilt der Verwaltung mit, welche Eingabe gerendert werden soll. CustomFieldTypes::INT rendert eine Zahleneingabe. Verwenden Sie den richtigen Typ für Ihre Daten – der Administrator erzwingt ihn beim Schreiben von Werten.
- Übersetzte Etiketten. Sowohl der Feldsatz als auch einzelne Felder unterstützen übersetzte Beschriftungen über
en-GB,de-DEund andere Gebietsschemaschlüssel. Fügen Sie immer Beschriftungen hinzu – unbenannte Felder im Admin-Bereich führen zu einer schlechten Erfahrung für Filialleiter - Feldbestellung. Der
customFieldPositionEigenschaftssteuerelemente zeigen die Reihenfolge an, wenn Sie mehrere benutzerdefinierte Felder in einem Satz haben. Legen Sie dies bewusst fest, anstatt sich auf die Einfügereihenfolge zu verlassen.
Ein wichtiger Hinweis: Benutzerdefinierte Feldsätze können vom Shop-Administrator über das Admin-Panel gelöscht werden. Schreiben Sie keinen Code, der davon ausgeht, dass ein benutzerdefinierter Feldsatz immer vorhanden ist, und bauen Sie ihn defensiv auf.
Benutzerdefinierte Shopware Regeln und benutzerdefinierte Felder – wo sie sich überschneiden
Benutzerdefinierte Shopware Regeln sind ein separates, aber verwandtes Konzept, das es wert ist, im Kontext verstanden zu werden. Während benutzerdefinierte Felder Daten zu Entitäten speichern, verwenden benutzerdefinierte Regeln diese Daten (und andere Bedingungen), um die Geschäftslogik voranzutreiben – Preisregeln, Versandbeschränkungen, Produktsichtbarkeit und mehr.
Ein häufiges Muster in Entwicklungsdienstleistungen für Shopware Plugins Die Arbeit besteht darin, beides zu kombinieren: über benutzerdefinierte Felder ein benutzerdefiniertes Attribut für eine Kundenentität zu speichern und dann in einer benutzerdefinierten Regel auf dieses Attribut zu verweisen, um die Preisgestaltung oder das Checkout-Verhalten zu steuern. Der Regelbereich ermöglicht Ihnen den Zugriff auf Entitätsdaten zum Zeitpunkt der Regelauswertung.
public function match(RuleScope $scope): bool
{
// Access customer custom fields here to evaluate your condition
$isCurrentlyLunarEclipse = $this->isCurrentlyLunarEclipse();
if ($this->isLunarEclipse) {
// your logic
}
}
Suchen Sie einen vertrauenswürdigen Shopware 6 Partner für Ihren Shop?
Lasst uns die Hände schütteln! 🤝iCreative Technologies ist Ihr vertrauenswürdiger Shopware Bronze-Partner und aktives Shopware Community-Mitglied und unterstützt Unternehmen in ganz Deutschland, den Niederlanden und der nordischen Region beim Aufbau, der Migration, Optimierung und Skalierung ihrer Shopware Shops.
Shopware Twig Extension – Anzeige benutzerdefinierter Felder in der Storefront
Sobald Ihre benutzerdefinierten Felddaten gespeichert sind, möchten Sie sie wahrscheinlich in der Storefront anzeigen. Hier kommt die Shopware Twig-Erweiterung ins Spiel.
Shopware verwendet Twig als Template-Engine und auf benutzerdefinierte Felder, die in Entitäten gespeichert sind, kann in Vorlagen über die Eigenschaft „customFields“ zugegriffen werden. Beispiel: Auf einer Produktdetailseite:
{% block page_product_detail_custom %}
{% if page.product.customFields.swag_example_size %}
<div class="custom-field-size">
Size: {{ page.product.customFields.swag_example_size }}
</div>
{% endif %}
{% endblock %}
Ein richtiges Tutorial zur Shopware Twig-Erweiterung würde Blocküberschreibungen ausführlich behandeln, aber der entscheidende Punkt ist, dass auf benutzerdefinierte Feldwerte direkt auf dem Entitätsobjekt in jeder Vorlage zugegriffen werden kann, die Zugriff auf diese Entität hat. Überprüfen Sie vor der Ausgabe immer, ob Null vorhanden ist – nicht bei jeder Entitätsinstanz wird das Feld ausgefüllt.
Für eine komplexere Anzeigelogik können Sie in Ihrem eine Twig-Erweiterungsklasse erstellen Shopware Plugin das benutzerdefinierte Twig-Funktionen oder -Filter registriert und Ihren Vorlagen Zugriff auf verarbeitete benutzerdefinierte Felddaten statt auf Rohwerte gibt.
Shopware 6 Tutorial zu benutzerdefinierten Feldern – Häufige Fehler, die Sie vermeiden sollten
Nach der Durcharbeitung der Implementierung treten folgende Probleme am häufigsten auf:
- Fehlende Migration: Benutzerdefinierte Felder hinzufügen, ohne das zu erstellen
benutzerdefinierte_FelderDie JSON-Spalte verursacht Laufzeitfehler. - Definitions- und Migrationssynchronisierung: Entitätsdefinition und Datenbankmigration müssen immer übereinstimmen.
- Fehlender Feldsatz: Benutzerdefinierte Felder werden im Admin-Bereich nur angezeigt, wenn ein benutzerdefinierter Feldsatz erstellt wird.
- Falscher Feldtyp: Der benutzerdefinierte Feldtyp muss mit dem gespeicherten Wert übereinstimmen (z. B. INT für Zahlen, STRING für Text).
- Keine Nullprüfungen: Benutzerdefinierte Feldsätze können von Administratoren gelöscht werden. Überprüfen Sie daher immer, ob ein Feld vorhanden ist, bevor Sie darauf zugreifen.
- Problem bei der Administratorbearbeitung: Ohne eine ordnungsgemäße Feldsatzdefinition können benutzerdefinierte Felder nur über Code verwaltet werden.
Wenn benutzerdefinierte Felder nicht ausreichen – Shopware Entity Extension
Benutzerdefinierte Felder verarbeiten Skalardaten gut, es gibt jedoch Einschränkungen. Wenn Sie Folgendes benötigen:
- Erstellen Sie Verknüpfungen zwischen Entitäten (Produkt zu Lieferant, Bestellung zu externer Referenz).
- Speichern Sie strukturierte relationale Daten mit eigenen Abfrage- und Filterfunktionen
- Erstellen Sie komplexe verschachtelte Datenstrukturen
..dann benötigen Sie eine vollständige Shopware Entitätserweiterung anstelle benutzerdefinierter Felder. Der Entity-Extension-Ansatz umfasst die Erstellung neuer Entity-Definitionen, neuer Datenbanktabellen und die ordnungsgemäße Registrierung der Zuordnung im DAL von Shopware. Es ist mehr Arbeit, aber es ist die richtige Architektur für komplexe Datenanforderungen.
Most Entwicklungsunternehmen für Shopware Erweiterungen Bei der Arbeit geht es darum, zu wissen, welcher Ansatz den Anforderungen entspricht – benutzerdefinierte Felder für die einfache Attributspeicherung, Entitätserweiterungen für relationale Daten.
Letztes Wort
Shopware 6 Custom Fields sind eines der praktischsten Tools in der Shopware Plugin-Entwicklung. Sie lassen sich schnell implementieren, sind flexibel genug für die meisten Anpassungsanforderungen im Geschäft und lassen sich problemlos sowohl in die DAL als auch in das Administrationspanel integrieren.
Wenn Ihr Shop eine komplexere Anpassung des Shopware 6 Plugins benötigt, bietet iCreative Technologies professionelle Lösungen an Entwicklungsdienstleistungen für Shopware Plugins nach Shopware Standards gebaut. Kontaktieren Sie uns, um Ihr Projekt zu besprechen.
