Smart-Invalidierung im Detail

Smart-Invalidierung ist der Standardmodus. Statt “alles im Zusammenhang mit Produkt X” zu purgen, wenn ein Produkt sich ändert, prüft sie, welche Felder sich tatsächlich geändert haben, und berechnet das minimale Set von Cache-Tags, das sterben muss.

Diese Seite erklärt das Feld-zu-Tag-Mapping, sodass Sie vorhersehen können, was ein bestimmter Save invalidiert — und entscheiden, ob Smart das Richtige für Ihren Shop ist.

Warum Feldebene wichtig ist

Die Standard-Shopware-Invalidierung arbeitet auf Entitätsebene: jede Änderung an Produkt X invalidiert alles, was mit product-X getaggt ist. Dieses Tag hängt typischerweise an:

Der Produktdetailseite
Jeder Kategorieseite, auf der das Produkt erscheint
Jedem Listing-Query, der das Produkt zurückgab
Der Async-Buybox-Komponente
Der Startseite, wenn das Produkt featured ist

Eine einstellige Korrektur in der Beschreibung rendert also Dutzende von Seiten neu — viele zeigen die Beschreibung gar nicht.

Der Smart-Modus zerlegt das Entitäts-Tag in ein Pro-Feld-Tag-Set. Listings tragen product-X.name + product-X.price + product-X.coverImage; Detailseiten das volle Set; Buybox product-X.price + product-X.deliveryTime + product-X.stock. Eine reine Beschreibungsänderung matched nur das Tag-Set der Detailseite, sodass nur dieser eine Eintrag gepurged wird.

Beispiele

Geändertes Feld am Produkt	Smart invalidiert
`name`	Detail + Listings (Name auf Karten) + Kategorieseiten (Breadcrumb-Referenzen)
`description`	Nur Detail
`price`	Detail + Listings + Buybox + Home (wenn featured)
`stock`	Detail + Buybox
`deliveryTime`	Nur Buybox
`coverId` (Cover-Bild)	Detail + Listings
`metaTitle` / `metaDescription` / `keywords`	Nur Detail
`categoryIds` (Zuweisungsänderung)	Detail + jede alte und neue Kategorieseite + Listings
`active`	Detail + Listings + Kategorieseiten
`properties` (Zuweisung)	Detail + Filter-Aggregationen
`visibilities` (Sales-Channel-Zuweisung)	Detail + Listings + Kategorieseiten in betroffenen Channels

Geändertes Feld an der Kategorie	Smart invalidiert
`name`	Kategorieseite + übergeordnete Listings + Navigationsmenüs
`description`	Nur Kategorieseite
`parentId` (Verschieben)	Alte und neue Kategoriebäume + Navigationsmenüs
`active`	Ganzer Baum darunter
`productAssignmentType` / `productStreamId`	Kategorieseite + Listings

Geändertes Feld an einer CMS-Seite	Smart invalidiert
`name` / `sections` / `slots`	Den CMS-Seiteneintrag
Zuweisung zu einer Kategorie	Die Kategorieseite + die CMS-Seite

Custom-Felder

Custom-Felder werden konservativ einsortiert — sie invalidieren die Detailseite plus Listings, wenn das Custom-Feld in einem Property-Block erscheint, der typischerweise auf Karten zu sehen ist.

Wenn Sie ein Custom-Feld haben, das nur die Ausgabe der Detailseite steuert (z. B. ein “Garantie”-Rich-Text-Block), behandelt Smart es trotzdem standardmäßig als listing-relevant, um auf Nummer sicher zu gehen. Überschreiben Sie das Mapping, wenn Sie es besser wissen — siehe unten Smart erweitern.

Wenn Smart überpurged (und wann nicht)

Smart ist konservativ. Im Zweifel purged es mehr, als es Stale-Risiken eingeht. Fälle, in denen es bewusst überpurged:

Massenimport von Produkten per DAL — Shopware feuert Write-Events mit einem einzigen “alles wurde gesetzt”-Payload. Smart kann nicht erkennen, welche Felder sich effektiv geändert haben, und purged alles.
Erster Save nach einer Migration — gleicher Grund.
Ein nicht getracktes Feld, dessen Wert zählt — z. B. ein Twig-Makro im Theme, das ein nicht getracktes Custom-Feld liest. Smart weiß nicht, dass Ihr Theme es liest, und wird Listings nicht purgen, wenn sich dieses Feld ändert.

Für die ersten beiden rechnen Sie nach großen Importen mit einem einmaligen großen Purge. Für den dritten wechseln Sie für diesen einen Save zu Precise oder Extended, oder fügen einen manuellen Purge aus Ihrem Import-Skript hinzu.

Fälle, in denen Smart der falsche Default ist

Sie betreiben eine Content-Seite, keinen Shop — Inhalt ändert sich selten; die Überpurges von Precise / Extended sind den Analyse-Overhead nicht wert.
Sie machen immer Massenänderungen — Smart und Precise werden bei Massenimporten ohnehin den Großteil des Cache purgen; wählen Sie das, was weniger Framework-Overhead bei der Analyse erzeugt.
Ihr Storefront ist stark personalisiert — die meisten Seiten werden ohnehin umgangen; einfachere Modi reichen.

Performance-Kosten

Das Field-Diff wird im Handler des entity-written-Events berechnet. Für einen einzelnen Produkt-Save bedeutet das Sub-Millisekunden-Overhead. Bei Massen-Updates skaliert der Overhead linear mit der Anzahl der Entitäten — meist vernachlässigbar gegenüber dem DB-Write selbst, in Worst-Case-Profilen aber sichtbar.

Wenn die Analyse bei sehr großen Importen zum Bottleneck wird, wechseln Sie für die Dauer des Imports zu Precise und danach wieder zu Smart.

Smart erweitern

Das Field-Mapping von Smart lebt in SmartInvalidationAnalyzer. Erweitern aus einem Custom-Plugin:

Dekorieren Sie P2Lab\Cache\Service\SmartInvalidationAnalyzer mit Ihrer eigenen Implementierung.
Überschreiben Sie die Methoden analyze<Entity>Change(array $changedFields): array, um Ihr eigenes Tag-Set für Felder zurückzugeben, die das Plugin nicht kennt.

Die Standard-Tag-Konventionen sind in Architektur dokumentiert.