Benutzerdefinierte Felder im WooCommerce-Checkout: vom Kauf bis zum Backoffice

Ein Feld, das dem Checkout hinzugefügt wurde, ist nicht allein dadurch fertig, dass es auf dem Bildschirm erscheint. Damit es nützlich ist, muss es einem konkreten Bedarf entsprechen, serverseitig validiert, der Bestellung zugeordnet gespeichert und den Personen oder Prozessen zugänglich gemacht werden, die es benötigen. Jeder dieser Schritte kann unabhängig von den anderen fehlschlagen.

Die Implementierung hängt außerdem vom aktiven Checkout-Ablauf ab. Hooks für den klassischen Checkout fügen nicht automatisch Felder zum Checkout Block hinzu. Ermitteln Sie vor der Programmierung, welchen Ablauf der Shop verwendet, und planen Sie den gesamten Weg des Werts.

Entscheiden, ob der Wert in den Checkout gehört

Ermitteln Sie, welche Aufgabe den Wert erfordert und wann er verfügbar sein muss. Ist er für die Berechnung der Bestellung, die Prüfung, ob die Bestellung die erforderlichen Voraussetzungen erfüllt, oder die Vorbereitung der Lieferung unerlässlich, muss er möglicherweise vor dem Kaufabschluss abgefragt werden. Dient er nur der späteren Bearbeitung, sollten Sie erwägen, ihn erst danach zu erheben, um unnötige Reibung zu vermeiden.

Dokumentieren Sie den Zweck, wer das Feld verwendet, ob es erforderlich ist und wie lange es aufbewahrt werden muss. Prüfen Sie, ob WooCommerce bereits über ein Standardfeld für diese Information verfügt: Eine Adresse oder Telefonnummer zu duplizieren, ohne festzulegen, welcher Wert maßgeblich ist, führt zu Abweichungen. Beschränken Sie bei sensiblen oder besonders folgenreichen Daten die Erhebung und den Zugriff und prüfen Sie die geltenden Datenschutzpflichten.

Den Ablauf ermitteln und das Feld hinzufügen

Prüfen Sie auf der Seite zum Bestellabschluss, ob der klassische Shortcode [woocommerce_checkout] oder der Checkout Block verwendet wird. Überprüfen Sie auch die Templates und Erweiterungen, die diese Seite verändern. Das Design allein zu erkennen, reicht nicht aus: Eine Erweiterung kann den Ablauf oder die Verarbeitung ändern. Implementieren und testen Sie den passenden Mechanismus und gehen Sie nicht davon aus, dass ein für einen Ablauf erstelltes Feld auch im anderen funktioniert.

Klassischer Checkout: Feld- und Bestell-Hooks

Im klassischen Checkout lassen sich Felder mit woocommerce_checkout_fields ändern, mit woocommerce_after_checkout_validation validieren und während der Erstellung der Bestellung mit woocommerce_checkout_create_order speichern. Dieses Beispiel registriert ein optionales Feld, weist nichtskalare Eingaben zurück und begrenzt den Text auf 120 Unicode-Zeichen:

add_filter('woocommerce_checkout_fields', function ($fields) {
    $fields['order']['delivery_instructions'] = [
        'type'      => 'text',
        'label'     => 'Lieferanweisungen',
        'required'  => false,
        'priority'  => 25,
        'maxlength' => 120,
        'class'     => ['form-row-wide'],
    ];
    return $fields;
});

add_action('woocommerce_after_checkout_validation', function ($data, $errors) {
    $raw = $data['delivery_instructions'] ?? '';
    if (! is_scalar($raw)) {
        $errors->add('delivery_instructions', 'Der Wert muss Text sein.');
        return;
    }

    $value = trim(sanitize_text_field((string) $raw));
    if (preg_match_all('/./us', $value, $matches) === false) {
        $errors->add('delivery_instructions', 'Der Text hat kein gültiges Format.');
        return;
    }
    if (count($matches[0]) > 120) {
        $errors->add('delivery_instructions', 'Der Text darf höchstens 120 Zeichen umfassen.');
    }
}, 10, 2);

add_action('woocommerce_checkout_create_order', function ($order, $data) {
    $raw = $data['delivery_instructions'] ?? '';
    if (! is_scalar($raw)) {
        return;
    }
    $value = trim(sanitize_text_field((string) $raw));
    if ($value !== '') {
        $order->update_meta_data('_delivery_instructions', $value);
    }
}, 10, 2);

Das Attribut maxlength setzt eine Einschränkung im Browser, ersetzt aber nicht die serverseitige Validierung. Das Beispiel zählt Unicode-Codepoints mithilfe eines UTF-8-kompatiblen Ausdrucks; einige Zeichen, etwa bestimmte Emojis, belegen im Browser mehr als eine UTF-16-Einheit. Sollen diese Zeichen zulässig sein, legen Sie die Längenregel ausdrücklich fest und testen Sie sie, damit das Kundenerlebnis und der Server nicht voneinander abweichen.

Das Beispiel speichert nur einen gültigen, nicht leeren Wert. Wird das Feld verpflichtend, validieren Sie auch, ob es fehlt, und geben Sie vor der Erstellung der Bestellung einen Fehler zurück. Verwenden Sie einen stabilen internen Namen und ändern Sie ihn nicht, ohne eine Migration vorhandener Daten zu planen.

Checkout Block: API für zusätzliche Felder

Verwenden Sie für den Checkout Block die API für zusätzliche WooCommerce-Checkout-Felder, statt HTML in das Formular einzuschleusen. Registrieren Sie das Feld über ein kompatibles Plugin oder Theme, beispielsweise während woocommerce_init:

add_action('woocommerce_init', function () {
    if (! function_exists('woocommerce_register_additional_checkout_field')) {
        return;
    }

    woocommerce_register_additional_checkout_field([
        'id'       => 'mi-plugin/delivery-instructions',
        'label'    => 'Lieferanweisungen',
        'location' => 'order',
        'type'     => 'text',
        'required' => false,
    ]);
});

Die API integriert das Feld in den Block-Ablauf und die zugehörige Speicherung an der Bestellung. Wenn Sie spezifische Regeln benötigen, prüfen Sie die von der API unterstützten Optionen für Bereinigung und Validierung in der jeweiligen Installation und testen Sie die Fehlerbehandlung durchgängig. Speichern Sie denselben Wert nicht parallel über einen anderen Mechanismus, ohne festzulegen, welche Quelle maßgeblich ist.

Prüfen Sie vor der Bereitstellung, ob die Registrierungsfunktion vorhanden ist, und konsultieren Sie die Dokumentation für die installierte Version. Ist sie nicht verfügbar, sollten Sie die Kompatibilität nicht mit JavaScript simulieren: Aktualisieren Sie die Installation oder wählen Sie eine mit dem verwendeten Checkout kompatible Alternative und testen Sie sie in einer Staging-Umgebung.

Serverseitig validieren, normalisieren und speichern

Die Validierung im Browser verbessert die Benutzerfreundlichkeit, ist aber keine Sicherheitsmaßnahme. Prüfen Sie auf dem Server, ob ein Wert vorhanden ist, sofern er verpflichtend ist, und validieren Sie Typ, Länge, Format und Zugehörigkeit zu den zulässigen Optionen. Bei geschlossenen Auswahlmöglichkeiten validieren Sie bekannte Kennungen und keinen beliebigen, vom Client übermittelten Text. Ist der Wert optional, legen Sie fest, ob „nicht vorhanden“ und „leer“ dasselbe bedeuten. Zeigen Sie bei einem ungültigen Wert eine verständliche Fehlermeldung an und bestätigen Sie die Bestellung nicht, indem Sie einen erforderlichen Wert stillschweigend weglassen.

Im klassischen Ablauf verwendet $order->update_meta_data() die CRUD-API der Bestellung und vermeidet direkte Schreibzugriffe auf Tabellen oder die Abhängigkeit von einer bestimmten Speicherstruktur. Überlassen Sie es im Checkout Block der API für zusätzliche Felder, das Feld der Bestellung zuzuordnen. Rufen Sie den Wert über die Bestell-API oder den für diese Integration dokumentierten Mechanismus ab; setzen Sie keinen internen Metadatenschlüssel voraus.

Prüfen Sie zur Kompatibilitätskontrolle in den WooCommerce-Einstellungen, ob High-Performance Order Storage (HPOS) oder die Speicherung in den Beitragstabellen aktiviert ist. Erstellen Sie in einer Testumgebung mit derselben Konfiguration für jeden Ablauf eine Bestellung, lesen Sie sie als WC_Order-Objekt mit wc_get_order($order_id) aus und prüfen Sie den Wert über die CRUD-API, beim klassischen Feld beispielsweise mit $order->get_meta('_delivery_instructions'). Aktualisieren Sie die Bestellung und lesen Sie sie erneut aus; verwenden Sie keine direkten SQL-Abfragen auf interne Tabellen. Wiederholen Sie die Prüfungen nach einer Änderung der Speicherung oder einer Aktualisierung von Erweiterungen, die am Checkout beteiligt sind.

Den Wert im Backoffice aufrufen

Der operative Prüfpfad besteht darin, eine Testbestellung anzulegen, WooCommerce > Bestellungen zu öffnen, die Bestellung zu bearbeiten und den angezeigten Wert mit dem übermittelten zu vergleichen. Wird das Metadatum des klassischen Checkouts nicht auf dem vom Team verwendeten Bildschirm angezeigt, lässt sich eine administrative Anzeige mit dem folgenden Bestelldaten-Hook hinzufügen:

add_action('woocommerce_admin_order_data_after_billing_address', function ($order) {
    $value = $order->get_meta('_delivery_instructions');
    if ($value !== '') {
        echo '<p><strong>Lieferanweisungen:</strong> '
            . esc_html($value) . '</p>';
    }
});

Dieser Hook und das Metadatum im Beispiel gehören zum klassischen Checkout; prüfen Sie die Anzeige im in Ihrem Shop aktivierten Verwaltungsbildschirm. Überprüfen Sie bei HPOS und im blockbasierten Bildschirm zur Bestellbearbeitung das tatsächliche Ergebnis: Gehen Sie nicht davon aus, dass eine Erweiterung für das klassische Dashboard automatisch auch die neue Oberfläche abdeckt. Verwenden Sie zum Lesen oder Bearbeiten von Daten stets das Bestellobjekt und die CRUD-API.

Über die API registrierte Felder des Checkout Block können in die Bestelldetails integriert werden. Prüfen Sie das anhand einer Testbestellung unter WooCommerce > Bestellungen. Wenn anderer Code den Wert abfragen muss, ermitteln Sie in der API-Dokumentation den Speicherort und den Abrufmechanismus für die installierte Version; raten Sie nicht, welcher Metadatenschlüssel verwendet wird. Wird der Wert nicht angezeigt, ergänzen Sie eine mit diesem Bildschirm kompatible administrative Anzeige und testen Sie sie sowohl mit der konfigurierten Speicherung als auch mit den installierten Verwaltungs-Erweiterungen.

Wenn eine Bearbeitung erforderlich ist, legen Sie die berechtigten Rollen fest und speichern Sie Änderungen über die CRUD-API der Bestellung. Zeigen Sie den Wert nicht automatisch in E-Mails, Dokumenten, Exporten oder öffentlichen Ansichten an: Nehmen Sie jedes Ziel nur bei einem betrieblichen Bedarf auf, beschränken Sie den Zugriff und escapen Sie die Ausgabe stets.

Den gesamten Ablauf testen und Regressionen vermeiden

Ein Test, der nur prüft, ob das Feld gerendert wird, reicht nicht aus. Überprüfen Sie den Weg vom Formular bis zur späteren Verwendung und decken Sie mindestens Folgendes ab:

• Gültige Bestellung mit eingegebenem Wert: validieren, in der richtigen Bestellung speichern und im Backoffice aufrufen.
• Leeres optionales Feld und fehlendes Pflichtfeld: das für jeden Fall festgelegte Verhalten überprüfen.
• Manipulierte, nichtskalare oder zu lange Eingaben sowie Werte außerhalb der zulässigen Optionen: die Zurückweisung auf dem Server bestätigen.
• Text mit Akzentzeichen und mehrbyteigen Zeichen einschließlich des exakten Grenzwerts; auch das Zusammenspiel mit maxlength prüfen.
• Aktualisierung der Bestellung: prüfen, was sich ändert, wer es ändern darf und wie die Änderung weitergegeben wird.
• Klassischer Checkout und Checkout Block: den aktiven Ablauf und alle geplanten Ablaufwechsel testen.
• Berechtigungen und Offenlegung: überprüfen, dass nur berechtigte Benutzer und Prozesse den Wert erhalten.

Beziehen Sie Regressionstests für Summen, Validierungen und die Erstellung der Bestellung ein. Wenn eine Automatisierung das Feld verwendet, testen Sie auch, was geschieht, wenn der Wert fehlt oder seine Übermittlung fehlschlägt. Ein klares Diagnosesignal ist, wenn der Wert im Browser erscheint, aber nicht in der Bestellung oder im Prozess, der ihn verwenden sollte.

Checkliste vor der Bereitstellung

• Der Zweck des Werts und der Zeitpunkt seiner Erhebung sind dokumentiert.
• Der Mechanismus entspricht dem aktiven Checkout: Hooks für den klassischen Ablauf oder die API für zusätzliche Felder im Block.
• Der Server validiert Typ, Format und Länge; nichtskalare Eingaben werden abgewiesen und für fehlende, leere und ungültige Werte ist jeweils ein Verhalten festgelegt.
• Installation und Bestellspeicherung sind ermittelt; Lesen und Aktualisieren wurden mit der CRUD-API getestet.
• Eine Testbestellung bestätigt, dass sich der Wert auf dem verwendeten Backoffice-Bildschirm aufrufen lässt und der Zugriff beschränkt ist.
• Die Tests decken Unicode-Zeichen, Aktualisierungen, Fehler, Integrationen und Regressionen im Checkout ab.