Aangepaste velden bij de WooCommerce-checkout: van aankoop tot backoffice

Een veld dat aan de checkout is toegevoegd, is niet klaar zodra het op het scherm verschijnt. Om nuttig te zijn, moet het aan een concrete behoefte voldoen, op de server worden gevalideerd, aan de bestelling worden gekoppeld en terechtkomen bij de mensen of processen die het nodig hebben. Elke stap kan afzonderlijk misgaan.

De implementatie hangt ook af van de actieve checkoutflow. Hooks voor de klassieke checkout voegen niet vanzelf velden toe aan de Checkout Block. Bepaal voordat je gaat programmeren welke variant de winkel gebruikt en ontwerp het volledige traject van de gegevens.

Bepalen of de gegevens bij de checkout horen

Breng in kaart voor welke taak de gegevens nodig zijn en wanneer ze beschikbaar moeten zijn. Als ze noodzakelijk zijn om de bestelling te berekenen, te bepalen of de bestelling in aanmerking komt of de levering voor te bereiden, moet je ze mogelijk vóór het afronden van de aankoop opvragen. Als ze alleen helpen bij de verdere afhandeling, overweeg dan om ze later op te vragen, zodat je geen onnodige frictie toevoegt.

Leg het doel vast, wie het veld gebruikt, of het verplicht is en hoe lang de gegevens moeten worden bewaard. Controleer of WooCommerce al een standaardveld voor die informatie heeft: een adres of telefoonnummer dupliceren zonder vast te leggen welke waarde leidend is, veroorzaakt tegenstrijdigheden. Beperk bij gevoelige gegevens of gegevens met grote impact de verzameling en toegang, en controleer welke privacyverplichtingen van toepassing zijn.

De checkoutflow bepalen en het veld toevoegen

Controleer op de afrekenpagina of de klassieke shortcode [woocommerce_checkout] of de Checkout Block wordt gebruikt. Bekijk ook de templates en extensies die deze pagina aanpassen. Alleen het ontwerp herkennen is niet genoeg: een extensie kan de flow of verwerking wijzigen. Implementeer en test het bijbehorende mechanisme en ga er niet van uit dat een veld dat voor de ene flow is gemaakt ook in de andere werkt.

Klassieke checkout: hooks voor velden en bestellingen

Bij de klassieke checkout kun je velden aanpassen met woocommerce_checkout_fields, valideren met woocommerce_after_checkout_validation en opslaan tijdens het aanmaken van de bestelling met woocommerce_checkout_create_order. Dit voorbeeld registreert een optioneel veld, weigert niet-scalare invoer en beperkt de tekst tot 120 Unicode-tekens:

add_filter('woocommerce_checkout_fields', function ($fields) {
    $fields['order']['delivery_instructions'] = [
        'type'      => 'text',
        'label'     => 'Bezorginstructies',
        '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', 'De waarde moet tekst zijn.');
        return;
    }

    $value = trim(sanitize_text_field((string) $raw));
    if (preg_match_all('/./us', $value, $matches) === false) {
        $errors->add('delivery_instructions', 'De tekst heeft geen geldige indeling.');
        return;
    }
    if (count($matches[0]) > 120) {
        $errors->add('delivery_instructions', 'De tekst mag niet langer zijn dan 120 tekens.');
    }
}, 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);

Het attribuut maxlength legt een beperking op in de browser, maar vervangt de validatie op de server niet. Het voorbeeld telt Unicode-codepoints met een UTF-8-compatibele expressie; sommige tekens, zoals bepaalde emoji, nemen in de browser meer dan één UTF-16-code-eenheid in beslag. Als die moeten worden toegestaan, definieer en test dan expliciet de lengteregel, zodat de klantervaring en de server niet van elkaar afwijken.

Het voorbeeld slaat alleen een geldige, niet-lege waarde op. Als het veld verplicht wordt, valideer dan ook of de waarde ontbreekt en geef een foutmelding voordat de bestelling wordt aangemaakt. Gebruik een stabiele interne naam en wijzig die niet zonder een migratie van bestaande gegevens te plannen.

Checkout Block: API voor extra velden

Gebruik voor de Checkout Block de API voor extra velden van WooCommerce in plaats van HTML in het formulier te injecteren. Registreer het veld vanuit een compatibele plugin of thema, bijvoorbeeld tijdens 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'    => 'Bezorginstructies',
        'location' => 'order',
        'type'     => 'text',
        'required' => false,
    ]);
});

De API integreert het veld met de blokflow en de bijbehorende opslag aan de bestelling. Als je specifieke regels nodig hebt, raadpleeg dan welke opties voor sanitization en validatie door de API worden ondersteund in de betreffende installatie en test de foutafhandeling van begin tot eind. Sla dezelfde waarde niet daarnaast op met een ander mechanisme zonder te bepalen welke bron leidend is.

Controleer vóór de uitrol of de registratiefunctie bestaat en raadpleeg de documentatie voor de geïnstalleerde versie. Als de functie niet beschikbaar is, simuleer dan geen compatibiliteit met JavaScript: werk bij of kies een alternatief dat compatibel is met de gebruikte checkout en test in een stagingomgeving.

Valideren, normaliseren en opslaan op de server

Validatie in de browser verbetert de gebruikerservaring, maar is geen beveiligingsmaatregel. Controleer op de server of een verplichte waarde aanwezig is, en controleer het type, de lengte, de indeling en of de waarde tot de toegestane opties behoort. Valideer bij gesloten keuzelijsten bekende identifiers, geen willekeurige tekst die door de client is verstuurd. Bepaal bij optionele gegevens of afwezig en leeg hetzelfde betekenen. Geef bij een ongeldige waarde een begrijpelijke foutmelding en bevestig de bestelling niet als daardoor een noodzakelijk gegeven ontbreekt.

In de klassieke flow gebruikt $order->update_meta_data() de CRUD-API voor bestellingen. Die API vermijdt directe schrijftoegang tot tabellen en voorkomt afhankelijkheid van een specifieke opslagstructuur. Laat in de Checkout Block de API voor extra velden de koppeling met de bestelling beheren en lees de waarde op via de bestel-API of het gedocumenteerde mechanisme voor die integratie; ga niet uit van een interne metadatasleutel.

Controleer voor compatibiliteit in de WooCommerce-instellingen of opslag van bestellingen met hoge prestaties (HPOS) of opslag op basis van de posts-tabellen actief is. Maak in een testomgeving met dezelfde configuratie voor elke flow een bestelling aan, lees die als WC_Order-object uit met wc_get_order($order_id) en controleer de gegevens via de CRUD-API, bijvoorbeeld met $order->get_meta('_delivery_instructions') voor het klassieke veld. Werk de bestelling bij en lees die opnieuw uit; gebruik geen rechtstreekse SQL-query's op interne tabellen. Herhaal de controles nadat je de opslag hebt gewijzigd of extensies hebt bijgewerkt die invloed hebben op de checkout.

De gegevens in de backoffice bekijken

De operationele verificatie bestaat eruit een testbestelling te maken, WooCommerce > Bestellingen te openen, de bestelling te bewerken en de weergegeven waarde te vergelijken met de verzonden waarde. Als de metagegevens voor de klassieke checkout niet zichtbaar zijn op het scherm dat het team gebruikt, kun je ze administratief weergeven met de volgende hook voor bestelgegevens:

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

Deze hook en de metagegevens uit het voorbeeld horen bij de klassieke checkout; controleer hoe ze worden weergegeven op het administratieve scherm dat in de winkel is ingeschakeld. Controleer bij HPOS en op het op blokken gebaseerde scherm voor het bewerken van bestellingen het daadwerkelijke resultaat: ga er niet van uit dat een extensie voor het klassieke beheerpaneel automatisch ook de nieuwe interface ondersteunt. Gebruik altijd het bestelobject en de CRUD-API om gegevens te lezen of te bewerken.

Velden die met de API van de Checkout Block zijn geregistreerd, kunnen worden geïntegreerd in de bestelgegevens. Controleer dit in WooCommerce > Bestellingen met een testbestelling. Als andere code de waarde moet uitlezen, bepaal dan in de API-documentatie welke locatie en welk leesmechanisme gelden voor de geïnstalleerde versie; raad de metadatasleutel niet. Als de waarde niet wordt weergegeven, voeg dan een administratieve weergave toe die compatibel is met dat scherm en test zowel met de geconfigureerde opslag als met de geïnstalleerde beheerextensies.

Als bewerken nodig is, definieer dan welke rollen hiervoor bevoegd zijn en sla wijzigingen op via de CRUD-API voor bestellingen. Geef de gegevens niet automatisch weer in e-mails, documenten, exports of openbare schermen: voeg ze alleen toe aan een bestemming als daar een operationele behoefte voor bestaat, beperk de toegang en escape de uitvoer altijd.

De volledige cyclus testen en regressies voorkomen

Een test die alleen controleert of het veld wordt weergegeven, is onvoldoende. Controleer het volledige traject van het formulier tot het latere gebruik en dek minimaal het volgende af:

• Geldige bestelling met ingevuld veld: valideren, opslaan bij de juiste bestelling en bekijken in de backoffice.
• Optioneel veld leeg en verplicht veld niet ingevuld: controleer het vastgelegde gedrag voor elk geval.
• Gemanipuleerde, niet-scalare of te lange invoer, of invoer buiten de toegestane opties: bevestig dat de server deze weigert.
• Tekst met accenten en multibyte-tekens, inclusief de exacte limiet; controleer ook de interactie met maxlength.
• Bestelling bijwerken: controleer wat er verandert, wie dat mag doen en hoe de wijziging wordt doorgegeven.
• Klassieke checkout en Checkout Block: test de actieve flow en eventuele geplande wijzigingen van checkoutvariant.
• Toegangsrechten en blootstelling: controleer dat alleen bevoegde gebruikers en processen de waarde ontvangen.

Neem regressietests op voor totalen, validaties en het aanmaken van de bestelling. Als een automatisering het veld gebruikt, test dan ook wat er gebeurt als de waarde ontbreekt of niet wordt doorgestuurd. Een duidelijk diagnostisch signaal is dat de gegevens wel in de browser verschijnen, maar niet in de bestelling of in het proces dat ze had moeten gebruiken.

Checklist vóór de uitrol

• Het doel van de gegevens en het moment waarop ze worden opgevraagd, zijn gedocumenteerd.
• Het mechanisme past bij de actieve checkout: hooks voor de klassieke flow of de API voor extra velden voor de Block.
• De server valideert type, indeling en lengte; niet-scalare invoer wordt geweigerd en voor ontbrekende, lege en ongeldige waarden is het gedrag vastgelegd.
• De installatie en de opslag van bestellingen zijn vastgesteld; lezen en bijwerken zijn getest met de CRUD-API.
• Een testbestelling bevestigt dat de gegevens kunnen worden gelezen op het gebruikte backofficescherm en dat de toegang beperkt is.
• De tests omvatten Unicode-tekens, updates, fouten, integraties en regressies in de checkout.