Ein Produktfeld mit definiertem Geltungsbereich mit PrestaShop-9.2-Eigenschaften erstellen

Eine sinnvolle erste Integration von Extra Properties verfolgt ein Feld von seiner Definition bis zu jeder Oberfläche, die es verwendet. So lassen sich wichtigere Probleme erkennen als durch die gleichzeitige Registrierung vieler Felder: Werte, die im falschen Shop gespeichert werden, an der falschen Stelle erscheinen oder bei einem Vorgang im Modullebenszyklus verloren gehen.

Das Beispiel behandelt ein shopspezifisches Produktdatum, das ein Katalogteam intern verwendet. Es ist eine begrenzte Integrationsübung für 9.2 RC1 und keine vollständige Anleitung zur Modulerstellung. Die offiziellen Entwicklerhinweise kennzeichnen das neue System als experimentell. Legen Sie daher die genaue Implementierung fest und prüfen Sie sie, bevor Sie langfristige Kompatibilität zusagen. Entwicklerhinweise zu 9.2.

Klären Sie vor der Implementierung das Datenmodell von Extra Properties; korrekter Integrationscode kann ein mehrdeutiges Zuständigkeits- oder Übersetzungsmodell nicht reparieren.

Das offizielle Beispiel als versionierte Referenz verwenden

Beginnen Sie mit demoextrafield im offiziellen Repository example-modules. Der Quellcode zeigt die Registrierung über registerExtraProperty() und Definitionen mit den Extra-Property-Klassen. Der Standardbranch des Repositorys kann sich ändern. Notieren Sie den für Ihr Experiment verwendeten Commit und vergleichen Sie seine Konstruktorargumente mit der RC-Installation. Quellcode des Beispiels.

Die folgenden Shell-Befehle dienen ausschließlich der lesenden Prüfung in Ihren bereits heruntergeladenen Repository-Arbeitskopien. Sie installieren kein Modul und verändern keinen Shop:

rg -n 'registerExtraProperty|ExtraPropertyDefinition' demoextrafield
rg -n 'associatedForms|associatedGrids|associatedApis' demoextrafield
rg -n 'unregisterExtraProperty|uninstall' demoextrafield

Suchen Sie auf dieselbe Weise im Kern der Kandidatenversion nach der Definitionsklasse und der Registrierungsmethode. Prüfen Sie Signatur, Validierungspfad und Rückgabeverhalten, bevor Sie das Beispiel anpassen. Das ist besonders wichtig, wenn das Beispiel neuere Kompatibilitätsanpassungen enthält als das getestete Archiv.

Ändern Sie keine Kernklassen, um ein inkompatibles Beispiel zu laden. Verwenden Sie entweder eine passende Revision des Beispiels oder passen Sie nach Klärung des Unterschieds nur den kleinen Integrationsbereich an.

Vor der Registrierung einen Feldvertrag festlegen

Definieren Sie für diese Übung ein Produktprüfdatum, das je nach Shop unterschiedlich sein kann. Es ist optional, intern und wird als Kalenderdatum statt als Zeitpunkt in einer Zeitzone interpretiert. Ein fehlender Wert bedeutet, dass kein Datum zugewiesen wurde. Er bedeutet nicht heute.

Dieser Vertrag legt unmittelbar sinnvolle Testfälle fest: ein Datum speichern, es löschen, einen ungültigen Wert ablehnen und einen anderen Wert in einem anderen Shop erhalten. Außerdem verhindert er, dass ein Import ohne ausdrücklich festgelegte Umwandlungsregeln einen Zeitstempel einsetzt.

Die folgende Struktur ist ein Beispiel einer moduleigenen Spezifikation, keine Registrierungs-API von PrestaShop. Sie soll die Anforderungen prüfbar machen, bevor diese dem verifizierten Konstruktor zugeordnet werden:

<?php
return [
    'business_name' => 'catalog_review_date',
    'entity' => 'product',
    'value_semantics' => 'calendar_date',
    'varies_by_shop' => true,
    'optional' => true,
    'public_output' => false,
    'owner' => 'catalog_team',
];

Halten Sie diese Unterscheidung in Ihrer Implementierung klar. Das Kopieren eines plausiblen Konfigurationsarrays in ein Modul registriert nichts, solange Sie nicht ausdrücklich den Adapter implementieren, der dieses Array verarbeitet.

Den Vertrag auf die unterstützte Definition abbilden

Der offizielle Quellcode importiert ExtraPropertyDefinition, ExtraPropertyScope und ExtraPropertyType aus PrestaShop\PrestaShop\Core\ExtraProperty\Definition. Verwenden Sie das Produktdatum mit Shop-Geltungsbereich aus dem passenden Beispiel als Integrationsreferenz, statt einen Feldtyp oder Methodennamen zu erfinden. Registrierungsbeispiel.

Passen Sie jeweils eine Definition an. Wählen Sie die von der Kandidatenversion unterstützte Entität, den Eigenschaftsnamen, den Typ und den Geltungsbereich. Legen Sie die vorgesehenen administrativen Zuordnungen und Sichtbarkeitseinstellungen anhand der geprüften Signatur fest. Weisen Sie Beschriftungen und Beschreibungen einer Übersetzungsdomäne Ihres Moduls zu.

Behandeln Sie Registrierungsfehler ausdrücklich in der vorhandenen Lebenszykluslogik des Moduls. Eine Teilinstallation darf nicht allein deshalb als erfolgreich gemeldet werden, weil der Moduleintrag existiert. Legen Sie fest, wie bereits registrierte Definitionen behandelt werden, wenn eine spätere Registrierung scheitert, und testen Sie einen erneuten Installationsversuch mit einer entbehrlichen Datenbank.

Gehen Sie nicht davon aus, dass die allgemeine Liste unterstützter Entitäten eine automatische Integration in jedes Formular oder Datenraster bedeutet. Entitätsidentität, Formularbezeichner und Rasterbezeichner sind separate Verträge. Eine nicht unterstützte Zuordnung erfordert gezielte Integrationsarbeit, keinen geratenen Bezeichner.

Ein gezielter Registrierungsabschnitt

Nachdem Sie bestätigt haben, dass der Konstruktor des Beispiels zu Ihrer Kandidatenversion passt, können Sie diesen Abschnitt in die bestehende Modulklasse übernehmen. Die Imports gehören auf Dateiebene, die Methode in diese Klasse. Der Abschnitt passt das offizielle Datumsfeldmuster an ein internes Prüffeld an und ordnet absichtlich keine API-Ressourcen zu.

use PrestaShop\PrestaShop\Core\ExtraProperty\Definition\ExtraPropertyDefinition;
use PrestaShop\PrestaShop\Core\ExtraProperty\Definition\ExtraPropertyScope;
use PrestaShop\PrestaShop\Core\ExtraProperty\Definition\ExtraPropertyType;
use PrestaShopBundle\Form\Admin\Type\DatePickerType;
use Symfony\Component\Validator\Constraints as Assert;

private function registerCatalogReviewDate(): bool
{
    $definition = new ExtraPropertyDefinition(
        entityName: 'product',
        propertyName: 'catalog_review_date',
        type: ExtraPropertyType::DATE,
        scope: ExtraPropertyScope::SHOP,
        nullable: true,
        displayFront: false,
        associatedForms: ['product'],
        associatedGrids: ['product'],
        formType: DatePickerType::class,
        constraints: [new Assert\Date()],
        labelWording: 'Catalog review date',
        labelDomain: 'Modules.Catalogreview.Admin'
    );

    return $this->registerExtraProperty($definition);
}

Die Übersetzungsdomäne in diesem Beispiel gehört zu einem Modul namens catalogreview; verwenden Sie die tatsächliche Domäne Ihres Moduls. Rufen Sie die Methode im bestehenden Installations- oder Aktualisierungsablauf auf und behandeln Sie ein false-Ergebnis gemäß dessen Rücksetzungsregeln. Stellen Sie diesen Abschnitt nicht als vollständiges installierbares Modul dar.

SHOP beschreibt den Geltungsbereich des Werts, während displayFront: false die beabsichtigte Darstellung beschreibt. Beides ersetzt nicht die oben beschriebenen Tests mit zwei Shops und zur Datenoffenlegung. Die Registrierung muss auf der passenden Kandidatenversion erprobt werden; dieser Artikel berichtet über keinen Laufzeittest des Abschnitts.

Formularspeicherung und Rasterverhalten getrennt prüfen

Erstellen Sie ein Produkt, wählen Sie Shop A, speichern Sie ein Prüfdatum und öffnen Sie das Produkt erneut. Der zurückgegebene Wert muss dem übermittelten Datum entsprechen. Wiederholen Sie dies mit einem vorhandenen Produkt und mit einem leeren Wert.

Prüfen Sie anschließend ungültige Eingaben über den unterstützten Schreibpfad. Ein Datumswähler im Browser kann gewöhnliche Benutzer daran hindern, einen fehlerhaft formatierten Wert einzugeben. Das beweist jedoch keine serverseitige Validierung. Testen Sie den vom Modul unterstützten Übermittlungs- oder Integrationsweg und bestätigen Sie, dass ein ungültiger Wert abgelehnt wird, ohne den vorherigen Wert zu beschädigen.

Ist das Feld einem Raster zugeordnet, prüfen Sie Darstellung, Filterung und Sortierung nur dort, wo diese Vorgänge tatsächlich unterstützt werden. Eine sichtbare Zelle beweist nicht, dass die Filterung denselben Shop-Geltungsbereich wie das Formular verwendet. Verwenden Sie zwei Produkte mit unterschiedlichen Daten sowie einen nicht gesetzten Wert, damit Sortierung und Verhalten leerer Werte beobachtbar sind.

Testen Sie Änderungen der Mitarbeitersprache getrennt von Änderungen gespeicherter Werte. Die Übersetzung einer Beschriftung darf das Datum nicht überschreiben. Fügen Sie später eine Eigenschaft mit Sprach-Geltungsbereich hinzu, geben Sie ihren Werten eigene Tests, statt die Übersetzung der Beschriftung als ausreichende Abdeckung anzusehen.

Testdaten mit zwei Shops verwenden, um Geltungsbereichsfehler aufzudecken

Ordnen Sie das Testprodukt den Shops A und B zu. Speichern Sie ein Datum in A und ein anderes in B. Öffnen Sie jeden Shop unabhängig und prüfen Sie alle API- oder Export-Lesezugriffe, die das Feld verwenden.

Testen Sie anschließend ein Produkt, das nur einem Shop zugeordnet ist. Eine fehlende Zuordnung darf nicht stillschweigend als Erlaubnis gelten, den Wert eines Standardshops zu verwenden. Dokumentieren Sie die Reaktion der Integration, wenn ein Aufrufer einen nicht anwendbaren Geltungsbereich auswählt.

Die Verfügbarkeit der Definition ist eine weitere Dimension. Die RC-Arbeiten ergänzen Einschränkungen, die eine Definition auf bestimmte Shops begrenzen können. Testen Sie das unabhängig von den Werten je Shop: Bestätigen Sie zuerst, wo das Feld existiert, und anschließend, welcher Wert in jedem zulässigen Kontext gelesen wird. Shop-Einschränkungen für Definitionen.

Ein administrativer Kontext für alle Shops verdient einen eigenen Testfall. Leiten Sie nicht selbst ab, ob er Werte überschreiben, einen gemeinsamen Wert anzeigen oder eine ausdrückliche Auswahl verlangen sollte. Prüfen Sie das Verhalten der Kandidatenversion und entscheiden Sie, ob Ihr Modul diesen Vorgang sicher anbieten kann. Ist die geschäftliche Aktion nur für einen Shop sinnvoll, verlangen Sie dessen Auswahl.

Die API-Offenlegung als separaten Vertrag prüfen

Ein Feld, das intern bleiben soll, muss auf jeder aktivierten Antwortoberfläche geprüft werden. Gehört die API-Offenlegung zur Funktion, untersuchen Sie das generierte Schema und die tatsächliche Antwort des installierten Ressourcenmoduls. Verwenden Sie die dokumentierten Routen der Kandidatenversion; leiten Sie keine Endpunkte aus dem Eigenschaftsnamen ab.

Dokumentieren Sie das Lese- und Schreibverhalten für einen gültigen, einen leeren und einen ungültigen Wert. Prüfen Sie, dass der richtige Shop-Kontext die Entitätsoperation erreicht. Bestätigen Sie außerdem, dass ein Client ohne Berechtigung für die übergeordnete Operation diese nicht allein deshalb ausführen kann, weil der Wert eine zusätzliche Eigenschaft ist.

Behandeln Sie eine von einer anderen Modulversion aufgezeichnete API-Antwort nicht als allgemeingültig. Bewahren Sie einen kleinen Vertrags-Testdatensatz mit dem Versionspaar und der erwarteten Struktur auf. Bei einer zukünftigen Aktualisierung sollten Schema und Verhalten verglichen werden, bevor ein Client neu generiert wird.

Belegen Sie für den Zugriff über die Shopoberfläche die Nichtoffenlegung, wenn das Feld intern ist: Prüfen Sie die gerenderte Seite und relevante Datenstrukturen auf versehentliche Ausgabe. Eine rein administrative Absicht garantiert allein nicht, dass das Feld auf jedem Darstellungspfad fehlt.

Einschränkungen und Entfernung benötigen Aktualisierungstests

Während des RC-Zyklus änderte das Projekt die Speicherung der Einschränkungen hin zu einer DSL-Darstellung anstelle der PHP-Serialisierung. Das ist ein Grund, den nativen Definitionslebenszyklus zu verwenden, statt manuell geschriebene serialisierte Werte im Speicher zu pflegen. Änderung der Speicherung von Einschränkungen.

Testen Sie eine Modulaktualisierung mit vorhandenen Werten. Wird das Feld restriktiver, identifizieren Sie vor der Durchsetzung der Regel die Datensätze, die ihr nicht mehr entsprechen. Eine gewöhnliche Produktbearbeitung darf nicht unerwartet scheitern, weil ein alter Wert nie migriert wurde.

Das Umbenennen einer Eigenschaft ist eine Datenmigration und nicht lediglich eine neue Beschriftung. Planen Sie, wie Werte übertragen und Lesezugriffe umgestellt werden. Nutzen externe Clients die Eigenschaft, betrifft die Änderung auch deren Vertrag.

Testen Sie schließlich Deaktivierung, erneute Aktivierung und Deinstallation unabhängig voneinander. Ein kommerzielles Modul sollte dokumentierte Regeln zur Datenaufbewahrung besitzen. Exportieren Sie die Testwerte, führen Sie das vorgesehene Entfernen aus und prüfen Sie, was übrig bleibt. Übernehmen Sie keine destruktive Bereinigung aus einer Demo allein deshalb, weil sie eine Testinstallation aufräumt.

Das Ergebnis dieser Übung sollte eine kleine Integration mit ausdrücklichem Geltungsbereich, geprüfter Speicherung und bekanntem Lebenszyklus sein. Sobald dieses eine Feld korrekt funktioniert, können weitere Eigenschaften dieselbe Entwurfsdisziplin nutzen, ohne die Erkundungsarbeit zu wiederholen oder auf ungeprüften API-Annahmen aufzubauen.

Zum grundlegenden Plattformkontext lesen Sie unseren Leitfaden zur Modulentwicklung für PrestaShop 9 und wenden Sie die oben beschriebenen versionsspezifischen Prüfungen auf die untersuchte Installation an.

Bei der Auswahl einer Erweiterung sehen Sie sich die PrestaShop-9-Module von PrestaSuite an und vergleichen Sie die dokumentierte Versionsunterstützung und die Integrationsanforderungen mit Ihren eigenen Testergebnissen.