Niestandardowe pola w procesie składania zamówienia w WooCommerce: od zakupu do panelu administracyjnego

Dodanie pola do procesu składania zamówienia nie oznacza, że zadanie jest wykonane, nawet jeśli pole pojawia się na ekranie. Aby było przydatne, musi odpowiadać konkretnej potrzebie, przechodzić walidację po stronie serwera, być zapisywane przy zamówieniu i trafiać do osób lub procesów, które go potrzebują. Każdy z tych etapów może zawieść niezależnie.

Sposób implementacji zależy również od aktywnego przepływu składania zamówienia. Hooki klasycznego procesu same z siebie nie dodają pól do Checkout Block. Zanim zaczniesz programować, ustal, z którego rozwiązania korzysta sklep, i zaplanuj pełną drogę danych.

Ustal, czy dane powinny być zbierane podczas składania zamówienia

Ustal, jakie zadanie wymaga tych danych i kiedy muszą być dostępne. Jeśli są niezbędne do obliczenia zamówienia, ustalenia, czy zamówienie spełnia określone warunki, lub przygotowania dostawy, może być konieczne zebranie ich przed potwierdzeniem zakupu. Jeśli służą jedynie do ułatwienia późniejszej obsługi, rozważ zebranie ich później, aby nie wprowadzać niepotrzebnych utrudnień.

Opisz cel pola, jego odbiorców, to, czy jest wymagane, oraz okres przechowywania danych. Sprawdź, czy WooCommerce ma już standardowe pole na te informacje: powielenie adresu lub numeru telefonu bez ustalenia, która wartość jest nadrzędna, prowadzi do rozbieżności. W przypadku danych wrażliwych lub o dużym znaczeniu ogranicz ich zbieranie i dostęp do nich oraz sprawdź obowiązujące wymogi dotyczące prywatności.

Ustal przepływ i dodaj pole

Na stronie składania zamówienia sprawdź, czy używany jest klasyczny shortcode [woocommerce_checkout], czy Checkout Block. Sprawdź też szablony i rozszerzenia modyfikujące tę stronę. Sam wygląd nie wystarczy do rozpoznania przepływu: rozszerzenie może zmieniać jego przebieg lub przetwarzanie danych. Zaimplementuj i przetestuj właściwy mechanizm; nie zakładaj, że pole utworzone dla jednego przepływu zadziała w drugim.

Klasyczny proces składania zamówienia: hooki pól i zamówienia

Klasyczny proces pozwala modyfikować pola za pomocą woocommerce_checkout_fields, walidować je przez woocommerce_after_checkout_validation i zapisywać podczas tworzenia zamówienia za pomocą woocommerce_checkout_create_order. Ten przykład rejestruje opcjonalne pole, odrzuca wartości nieskalarne i ogranicza tekst do 120 znaków Unicode:

add_filter('woocommerce_checkout_fields', function ($fields) {
    $fields['order']['delivery_instructions'] = [
        'type'      => 'text',
        'label'     => 'Instrukcje dostawy',
        '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', 'Wartość musi być tekstem.');
        return;
    }

    $value = trim(sanitize_text_field((string) $raw));
    if (preg_match_all('/./us', $value, $matches) === false) {
        $errors->add('delivery_instructions', 'Tekst ma nieprawidłowy format.');
        return;
    }
    if (count($matches[0]) > 120) {
        $errors->add('delivery_instructions', 'Tekst nie może przekraczać 120 znaków.');
    }
}, 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);

Atrybut maxlength ogranicza długość w przeglądarce, ale nie zastępuje walidacji po stronie serwera. Przykład zlicza punkty kodowe Unicode za pomocą wyrażenia zgodnego z UTF-8; niektóre znaki, na przykład wybrane emoji, zajmują więcej niż jedną jednostkę UTF-16 w przeglądarce. Jeśli mają być dozwolone, jawnie zdefiniuj i przetestuj regułę długości, aby zachowanie widziane przez klienta nie różniło się od walidacji serwerowej.

Przykład zapisuje wyłącznie prawidłową i niepustą wartość. Jeśli pole stanie się wymagane, waliduj również jego brak i zwracaj błąd przed utworzeniem zamówienia. Używaj stabilnej nazwy wewnętrznej i nie zmieniaj jej bez zaplanowania migracji istniejących danych.

Checkout Block: API dodatkowych pól

W przypadku Checkout Block korzystaj z API dodatkowych pól WooCommerce zamiast wstrzykiwać HTML do formularza. Zarejestruj pole w kompatybilnej wtyczce lub motywie, na przykład podczas 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'    => 'Instrukcje dostawy',
        'location' => 'order',
        'type'     => 'text',
        'required' => false,
    ]);
});

API integruje pole z przepływem blokowym i jego przechowywaniem przy zamówieniu. Jeśli potrzebujesz niestandardowych reguł, sprawdź opcje oczyszczania i walidacji obsługiwane przez API w danej instalacji oraz przetestuj obsługę błędów od początku do końca. Nie zapisuj tej samej wartości równolegle przy użyciu innego mechanizmu, dopóki nie ustalisz, które źródło jest nadrzędne.

Przed wdrożeniem sprawdź, czy funkcja rejestrująca jest dostępna, i zapoznaj się z dokumentacją dla zainstalowanej wersji. Jeśli funkcja nie jest dostępna, nie próbuj emulować zgodności za pomocą JavaScript: zaktualizuj instalację albo wybierz rozwiązanie zgodne z używanym procesem składania zamówienia i przetestuj je w środowisku stagingowym.

Waliduj, normalizuj i zapisuj dane po stronie serwera

Walidacja w przeglądarce poprawia komfort użytkowania, ale nie jest zabezpieczeniem. Po stronie serwera sprawdzaj obecność wartości, jeśli pole jest wymagane, a także typ, długość, format i zgodność z dozwolonymi opcjami. W przypadku zamkniętych list weryfikuj znane identyfikatory, a nie dowolny tekst przesłany przez klienta. Jeśli pole jest opcjonalne, określ, czy brak wartości i pusty ciąg oznaczają to samo. W razie nieprawidłowej wartości wyświetl zrozumiały błąd i nie potwierdzaj zamówienia przez ciche pominięcie niezbędnych danych.

W klasycznym przepływie $order->update_meta_data() korzysta z API CRUD zamówień, dzięki czemu nie trzeba zapisywać danych bezpośrednio w tabelach ani polegać na konkretnej strukturze przechowywania. W Checkout Block pozwól, by API dodatkowych pól zarządzało powiązaniem pola z zamówieniem, a wartość odczytuj za pomocą API zamówień lub mechanizmu udokumentowanego dla tej integracji; nie zakładaj, że znasz wewnętrzny klucz metadanych.

Aby sprawdzić zgodność, w ustawieniach WooCommerce sprawdź, czy aktywne jest magazynowanie zamówień o wysokiej wydajności (HPOS), czy magazynowanie oparte na tabelach wpisów. W środowisku testowym z taką samą konfiguracją utwórz zamówienie w każdym przepływie, odczytaj je jako obiekt WC_Order za pomocą wc_get_order($order_id) i sprawdź dane przez API CRUD, na przykład $order->get_meta('_delivery_instructions') dla klasycznego pola. Zaktualizuj zamówienie i odczytaj je ponownie; nie wykonuj bezpośrednich zapytań SQL do tabel wewnętrznych. Powtórz kontrole po zmianie sposobu przechowywania lub aktualizacji rozszerzeń wpływających na proces składania zamówienia.

Odczytuj dane w panelu administracyjnym

Operacyjna ścieżka weryfikacji polega na utworzeniu testowego zamówienia, przejściu do WooCommerce > Zamówienia, otwarciu jego edycji i porównaniu wyświetlanej wartości z przesłaną. W przypadku klasycznego procesu, jeśli metadane nie pojawiają się na ekranie używanym przez zespół, można dodać ich prezentację administracyjną za pomocą następującego hooka danych zamówienia:

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

Ten hook i metadane z przykładu dotyczą klasycznego procesu; sprawdź, jak są prezentowane na ekranie administracyjnym używanym w sklepie. W HPOS i ekranie edycji zamówień opartym na blokach sprawdź rzeczywisty rezultat: nie zakładaj, że rozszerzenie klasycznego panelu automatycznie obsługuje nowy interfejs. Do odczytu i edycji danych zawsze używaj obiektu zamówienia oraz API CRUD.

Pola zarejestrowane przez API Checkout Block mogą być zintegrowane ze szczegółami zamówienia. Sprawdź to w WooCommerce > Zamówienia na podstawie zamówienia testowego. Jeśli inny kod ma odczytywać wartość, znajdź w dokumentacji API informacje o lokalizacji i mechanizmie odczytu dla zainstalowanej wersji; nie zgaduj klucza metadanych. Jeśli wartość się nie wyświetla, dodaj prezentację administracyjną zgodną z danym ekranem i przetestuj ją przy skonfigurowanym magazynowaniu oraz z zainstalowanymi rozszerzeniami administracyjnymi.

Jeśli wymagana jest edycja, określ uprawnione role i zapisuj zmiany za pomocą API CRUD zamówień. Nie wyświetlaj automatycznie danych w wiadomościach e-mail, dokumentach, eksportach ani na ekranach publicznych: dodawaj każde miejsce docelowe tylko wtedy, gdy wynika to z potrzeb operacyjnych, ogranicz dostęp i zawsze odpowiednio koduj dane wyjściowe.

Przetestuj cały cykl i zapobiegaj regresjom

Test, który sprawdza wyłącznie, czy pole jest renderowane, nie wystarczy. Sprawdź całą drogę od formularza po późniejsze wykorzystanie danych i uwzględnij co najmniej:

• Prawidłowe zamówienie z wprowadzoną wartością: walidację, zapis przy właściwym zamówieniu i odczyt w panelu administracyjnym.
• Puste pole opcjonalne i brak pola wymaganego: sprawdzenie zachowania zdefiniowanego dla każdego przypadku.
• Zmodyfikowane dane wejściowe, wartość nieskalarną, zbyt długi tekst lub wartość spoza dozwolonych opcji: potwierdzenie odrzucenia po stronie serwera.
• Tekst z akcentami i znakami wielobajtowymi, również na dokładnej granicy limitu; sprawdzenie interakcji z maxlength.
• Aktualizację zamówienia: sprawdzenie, co się zmienia, kto może to zmienić i jak zmiana jest propagowana.
• Klasyczny proces składania zamówienia i Checkout Block: test aktywnego przepływu oraz każdej planowanej zmiany trybu.
• Uprawnienia i ekspozycję danych: sprawdzenie, czy wartość trafia wyłącznie do uprawnionych użytkowników i procesów.

Uwzględnij testy regresyjne sum, walidacji i tworzenia zamówień. Jeśli z pola korzysta automatyzacja, sprawdź również, co się dzieje, gdy wartość jest nieobecna lub jej przekazanie kończy się niepowodzeniem. Wyraźnym sygnałem diagnostycznym jest sytuacja, w której dane pojawiają się w przeglądarce, ale nie w zamówieniu ani w procesie, który miał z nich korzystać.

Lista kontrolna przed wdrożeniem

• Cel zbierania danych i moment ich pozyskania są udokumentowane.
• Mechanizm odpowiada aktywnemu procesowi składania zamówienia: hooki klasycznego przepływu albo API dodatkowych pól dla Checkout Block.
• Serwer waliduje typ, format i długość; wartości nieskalarne są odrzucane, a sposób obsługi braku wartości, pustego pola i nieprawidłowych danych jest określony.
• Rozpoznano instalację i konfigurację przechowywania zamówień; odczyt i aktualizację przetestowano za pomocą API CRUD.
• Zamówienie testowe potwierdza możliwość odczytu danych na używanym ekranie panelu administracyjnego, a dostęp jest ograniczony.
• Testy obejmują znaki Unicode, aktualizacje, błędy, integracje i regresje procesu składania zamówienia.