PrestaShop Entity Selector: Auswahlregeln und sichere Integration

Entitäten und Auswahlmethoden wählen

Verwenden Sie Entity Selector, wenn ein Modul eine gespeicherte Auswahlregel benötigt, etwa Produkte aus einer Kategorie mit bestimmten Ausschlüssen. Suchen und wählen Sie einzelne Datensätze oder definieren Sie eine Bedingung, die anhand des aktuellen Katalogs aufgelöst wird.

Das einbindende Modul entscheidet, welche Entitätsblöcke und Methoden Sie verwenden können. Ein vorhandener Provider im gemeinsamen Paket macht nicht jede Entität in jedem Formular verfügbar.

Die Besucherauswahl beschreibt Besucherbedingungen zur Laufzeit. Sie verspricht keinen Export identifizierbarer anonymer Käufer. Attributwerte, Eigenschaftswerte und Tags dienen außerdem als Suchziele für Produktbedingungen. Module können zusätzliche Provider registrieren.

Produktmethoden umfassen ausdrücklich ausgewählte Produkte, Kategorien, Hersteller, Lieferanten, Tags, Attribut- oder Eigenschaftswerte, Kombinationen, Zustand, Sichtbarkeit, Bestand und Aktivstatus. Mustermethoden decken Felder wie Name, Referenz und Beschreibung ab. Bereichsmethoden umfassen IDs, Preis, Gewicht, Menge, Position und Datumsangaben. Der Mustervergleich unterstützt *-Platzhalter und eine Option zur Groß-/Kleinschreibung. Verfügbare Methoden und akzeptierte Werte hängen vom gewählten Block ab.

Gruppen, Ausschlüsse und Ergebnismodifikatoren aufbauen

Jede Gruppe hat eine Einschlussbedingung, optionale Ausschlüsse und optionale Modifikatoren. Produktgruppen werden mit ODER verknüpft. Ausschlüsse gehören zu der Gruppe, in der Sie sie eingetragen haben: Eine andere Gruppe kann dasselbe Produkt wieder einschließen.

Wählen Sie beispielsweise Produkte aus Kategorie 3, schließen Sie die Produkte 42 und 99 aus, sortieren Sie nach den neuesten und behalten Sie zehn. Eine zweite Gruppe kann unabhängig davon fünf bestimmte Produkte auswählen. Ihr Limit ändert das Limit der ersten Gruppe nicht.

Bei der typisierten Produktauflösung lautet die Reihenfolge: Einschluss, optionale Kombinationsfilterung und Erweiterung, Ausschlüsse, Deduplizierung, Sortierung und Gruppenlimit. Anschließend werden die Gruppen der Reihe nach zusammengeführt, wobei das erste Vorkommen jedes Ziels erhalten bleibt. Sie können auch Blockmodifikatoren an resolveTargets() übergeben, um das zusammengeführte Ergebnis nach Anwendung der separaten Gruppeneinstellungen zu sortieren oder zu begrenzen.

Unterstützte Produktsortierfelder umfassen ID, Name, Preis, Menge, Referenz, Erstellungsdatum, Änderungsdatum, Kategorieposition und Verkäufe. Ein Limit von null oder ein ausgelassenes Limit bedeutet keine Gruppenbegrenzung innerhalb der Ressourcengrenzen des Resolvers. Der maßgebliche typisierte Resolver weist eine Zufallssortierung zurück.

Die Produktsortierung nach Preis verwendet in diesem Resolver den Nettobasispreis des Shops zuzüglich der Preisänderung der gewählten Variante, ohne Rabatte oder Währungsumrechnung. Die Verkaufssortierung verwendet Bruttostückzahlen aus gültigen Bestellungen im aktuellen Shop. Diese Bedeutungen können von den Preisspalten in einer Auswahlansicht abweichen.

Produkte und Kombinationen unterscheiden

Eine Produkt-ID und eine Kombinations-ID sind unterschiedliche Identitäten, auch bei gleichen Zahlen. Erhalten Sie diese Unterscheidung beim Speichern und Ausführen einer Auswahl.

Die maßgebliche Produkt-API ist ProductConditionResolver::resolveTargets($groups, $expansionMode, $maxTargets = 10000, $modifiers = []). Jeder zurückgegebene Eintrag enthält nur die Schlüssel id_product und id_product_attribute mit ganzzahligen Werten. Eine Attribut-ID von null kennzeichnet ein Produktziel.

Verwenden Sie expand, wenn Sie die Varianten eines Produkts außer einer bestimmten Kombination einschließen müssen. Der Ausschluss eines übergeordneten Produkts entfernt dessen repräsentierte Varianten innerhalb dieser Gruppe. Der Ausschluss einer genauen Kombination entfernt nur diese Variante. Ein genauer Ausschluss kann keine einzelne Variante von einem übergeordneten Produkt abziehen, das nie erweitert wurde.

Die Auflösung prüft die Zugehörigkeit von Produkten und Kombinationen sowie die Mitgliedschaft im aktuellen Shop. Behandeln Sie den Inaktivstatus gemäß der ausgewählten Methode: Ein ausdrücklich ausgewähltes vorhandenes Produkt kann sich von der Auswahl aktiver Produkte durch all unterscheiden.

Regelvorschau prüfen und Layout wählen

Suchergebnisse können Metadaten wie Produktvorschaubilder, Referenzen, Bestand und Preise anzeigen. Ausgewählte Einträge erscheinen als Chips. Anzahlen und seitenweise Vorschauen helfen Ihnen, eine Regel vor dem Speichern zu prüfen. Die genauen Spalten hängen von der Entität und der Konfiguration des einbindenden Moduls ab.

Verwenden Sie für ausführungsrelevante Produktanzahlen ohne Blockmodifikatoren previewTargets() mit denselben Gruppen, demselben Erweiterungsmodus und derselben Zielobergrenze wie resolveTargets(). Seine Anzahl berücksichtigt Gruppenmodifikatoren, akzeptiert aber keine zusätzlichen Blockmodifikatoren. Wenn die Ausführung Blockmodifikatoren verwendet, zählen und paginieren Sie das Ergebnis desselben Aufrufs von resolveTargets(). Eine seitenweise Auswahlvorschau sollte nicht als vollständige Menge der Ausführungsziele betrachtet werden.

Verwenden Sie die Übersetzungsintegration des einbindenden Moduls für Beschriftungen und prüfen Sie Ihre unterstützten Sprachen. Geben Sie jedem Selektor auf einer Seite eine eindeutige ID und einen eindeutigen Eingabenamen. Der einfache Modus kann eine leere oder einfache konkrete Auswahl als Suche und Chips mit einem Bedienelement für weitere Optionen darstellen. Verwenden Sie den vollständigen Modus, wenn Bedingungen, Ausschlüsse oder Modifikatoren im Formular sofort sichtbar sein müssen.

Die Komponente in einen Backoffice-Controller integrieren

Stimmen Sie Rendering, Anfrageverteilung und Ausführung aufeinander ab. Die Komponenten-API verwendet MyPrestaRocks\EntitySelector\Component\EntitySelector. Bestehende Trait-Integrationen verwenden MyPrestaRocks\EntitySelector\EntitySelector.

1. Deklarieren Sie genau die Entitäten, die das Formular anbietet. Die Komponente verwendet standardmäßig Produkte, wenn entities fehlt.
2. Registrieren Sie Assets während setMedia() nach dem Elternaufruf. Rendern Sie den Selektor mit seinen gespeicherten Daten.
3. Wenn der Selektor über AJAX geladen wird, geben Sie die von getClientConfigPayload() gelieferte Map zusammen mit dem HTML zurück, damit der Client die Konfiguration registrieren kann.
4. Leiten Sie Selektoranfragen an handleAjax() oder handleEntitySelectorAjax() des älteren Traits weiter.
5. Speichern und validieren Sie die übermittelte Auswahl über den normalen Schreibweg des einbindenden Formulars.
6. Lösen Sie sie bei Ausführung der Funktion im richtigen Shop und in der richtigen Sprache auf.

Verwenden Sie EntitySelectorRequest::isAddressed(), um Anfragen mit trait=EntitySelector zu erkennen. Sowohl JSON-Bodys als auch gewöhnliche Formularanfragen werden unterstützt. Der Suchtext verwendet entity_query. Eine adressierte Anfrage gibt JSON zurück und beendet die Ausführung; nur eine Anfrage außerhalb des Selektor-Namensraums gibt false zurück.

Wenn Sie eine aktionsabhängige Autorisierung für das einbindende Modul ergänzen, lesen Sie EntitySelectorRequest::action(), autorisieren Sie diesen Wert und übergeben Sie denselben Wert an den Handler. Der Dispatcher unterstützt nur seine reinen Leserouten für Suche, Hydrierung, Zählung und Vorschau. Er speichert nicht die Funktionskonfiguration des Moduls.

Einbindende Module mit älteren Traits leiten ihre Dispatch-Berechtigungen aus den aktuellen Blockdeklarationen ab. Halten Sie diese Deklarationen beim Rendern und bei AJAX-Anfragen konsistent. Ein anderswo registrierter Provider autorisiert keine nicht deklarierte Entität.

Gespeichertes JSON validieren und Berechtigungen durchsetzen

Das versteckte Formulareingabefeld enthält serialisierbares JSON. Erhalten Sie Entitätsblock, Gruppen, Einschlussmethode, Werte, Ausschlüsse und Modifikatoren. Das folgende Beispiel wählt bis zu zehn Produkte aus Kategorie 3 und schließt dabei Produkt 42 aus.

{
  "products": {
    "groups": [
      {
        "name": "Category selection",
        "include": {"method": "by_category", "values": [3]},
        "excludes": [{"method": "specific", "values": [42]}],
        "modifiers": {"limit": 10, "sort_by": "date_add", "sort_dir": "DESC"}
      }
    ]
  }
}

Validieren Sie die JSON-Struktur und methodenspezifischen Werte auf dem Server. Weisen Sie unbekannte Schlüssel, nicht unterstützte Methoden und ungültige Bereiche zurück. Ein verstecktes clientseitiges Feld kann im Browser bearbeitet werden; autorisieren Sie die übermittelte Auswahl daher auf dem Server.

Behalten Sie die normale PrestaShop-Admin-Authentifizierung, Tokens und Zugriffsprüfungen des einbindenden Controllers bei. Entity Selector beschränkt Entitäten zusätzlich auf die Serverdeklaration und prüft den Zugriff auf ihre Backoffice-Ansichten. Such- und Vorschauzugriff erteilen keine Berechtigung zum Speichern, Löschen oder Ändern ausgewählter Entitäten.

Speichern Sie unter den normalen Bearbeitungsberechtigungs- und CSRF-Prüfungen des Formulars. Übergeben Sie bei der Auflösung zur Laufzeit ausdrücklich Shop- und Sprachumfang. Erhalten Sie Kombinationsidentitäten und behandeln Sie eine leere oder fehlgeschlagene Auflösung, ohne sie stillschweigend auf alle Produkte auszuweiten.

Nutzendes Modul und Paket gemeinsam testen

Der Selektor ist eine gemeinsam genutzte Komponente. Ein Paketupdate nützt einem verwendenden Modul erst, wenn dieses das aktualisierte Paket erhält und lädt. Testen Sie die tatsächlich im Modul enthaltenen Versionen, die von dessen PrestaShop- und PHP-Laufzeit unterstützt werden.

• Speichern, laden und bearbeiten Sie eine ausdrückliche Auswahl und eine bedingte Gruppe.
• Prüfen Sie Ausschlüsse, Reihenfolge und Limits je Gruppe mit bekannten Datensätzen.
• Testen Sie Produkte und Kombinationen mit übereinstimmenden numerischen IDs.
• Prüfen Sie mehrere Selektoren auf derselben Seite und jedes verwendete Layout.
• Testen Sie einen Mitarbeiter mit Anzeige-, aber ohne Bearbeitungsrecht sowie eine Anfrage für eine nicht deklarierte Entität.
• Testen Sie Multistore-Grenzen, gelöschte Datensätze und Datensätze außerhalb des ausgewählten Shops.
• Vergleichen Sie die maßgebliche Vorschau mit den von der tatsächlichen Funktion verwendeten Zielen.

Lösen Sie erneut auf, wenn die Ausführung die aktuelle Katalogzugehörigkeit benötigt. Eine gespeicherte bedingte Regel kann nach Änderungen an Bestand, Kategorien oder Produkten berechtigterweise andere Ergebnisse liefern. Benötigt eine Funktion eine eingefrorene Auswahl, legen Sie diese Momentaufnahmeregel im verwendenden Modul ausdrücklich fest.