Champs personnalisés dans le checkout WooCommerce : de l’achat au back-office

Un champ ajouté au checkout n’est pas correctement implémenté simplement parce qu’il apparaît à l’écran. Pour être utile, il doit répondre à un besoin précis, être validé côté serveur, être enregistré avec la commande et être accessible aux personnes ou processus qui en ont besoin. Chacune de ces étapes peut échouer indépendamment des autres.

La mise en œuvre dépend également du flux de checkout actif. Les hooks du checkout classique n’ajoutent pas à eux seuls des champs au Checkout Block. Avant de programmer, identifiez le flux utilisé par la boutique et concevez le parcours complet de la donnée.

Déterminer si la donnée doit être recueillie au checkout

Identifiez la tâche qui nécessite cette donnée et le moment où elle doit être disponible. Si elle est indispensable pour calculer la commande, déterminer son éligibilité ou préparer la livraison, il peut être nécessaire de la demander avant de confirmer l’achat. Si elle facilite uniquement une opération ultérieure, envisagez de la recueillir plus tard afin de ne pas ajouter de friction inutile.

Documentez la finalité, les personnes qui utilisent le champ, son caractère obligatoire ou non et la durée de conservation requise. Vérifiez si WooCommerce dispose déjà d’un champ standard pour cette information : dupliquer une adresse ou un numéro de téléphone sans définir lequel fait foi crée des incohérences. Pour les données sensibles ou à fort impact, limitez leur collecte et leur accès, et vérifiez les obligations de confidentialité applicables.

Identifier le flux et ajouter le champ

Vérifiez sur la page de commande si le shortcode classique [woocommerce_checkout] ou le Checkout Block est utilisé. Examinez également les templates et les extensions qui modifient cette page. Il ne suffit pas de reconnaître la mise en page : une extension peut modifier le flux ou le traitement. Implémentez et testez le mécanisme correspondant, sans supposer qu’un champ créé pour un flux fonctionnera dans l’autre.

Checkout classique : hooks pour les champs et la commande

Le checkout classique permet de modifier les champs avec woocommerce_checkout_fields, de les valider avec woocommerce_after_checkout_validation et de les enregistrer lors de la création de la commande avec woocommerce_checkout_create_order. Cet exemple enregistre un champ facultatif, rejette les valeurs qui ne sont pas scalaires et limite le texte à 120 caractères Unicode :

add_filter('woocommerce_checkout_fields', function ($fields) {
    $fields['order']['delivery_instructions'] = [
        'type'      => 'text',
        'label'     => 'Instructions de livraison',
        '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', 'La valeur doit être du texte.');
        return;
    }

    $value = trim(sanitize_text_field((string) $raw));
    if (preg_match_all('/./us', $value, $matches) === false) {
        $errors->add('delivery_instructions', 'Le texte n’a pas un format valide.');
        return;
    }
    if (count($matches[0]) > 120) {
        $errors->add('delivery_instructions', 'Le texte ne peut pas dépasser 120 caractères.');
    }
}, 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);

L’attribut maxlength impose une limite dans le navigateur ; il ne remplace pas la validation côté serveur. L’exemple compte les points de code Unicode à l’aide d’une expression compatible UTF-8 ; certains caractères, comme certains emoji, occupent plus d’une unité UTF-16 dans le navigateur. S’ils doivent être acceptés, définissez et testez explicitement la règle de longueur afin d’éviter toute divergence entre l’expérience client et le serveur.

L’exemple n’enregistre qu’une valeur valide et non vide. Si le champ devient obligatoire, validez également son absence et renvoyez une erreur avant la création de la commande. Utilisez un nom interne stable et ne le modifiez pas sans prévoir la migration des données existantes.

Checkout Block : API des champs supplémentaires

Pour le Checkout Block, utilisez l’API des champs supplémentaires de WooCommerce au lieu d’injecter du HTML dans le formulaire. Enregistrez le champ depuis une extension ou un thème compatible, par exemple lors de 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'    => 'Instructions de livraison',
        'location' => 'order',
        'type'     => 'text',
        'required' => false,
    ]);
});

L’API intègre le champ au flux de blocs et à son stockage associé à la commande. Si vous avez besoin de règles spécifiques, consultez les options de sanitisation et de validation prises en charge par l’API dans l’installation concernée, puis testez l’erreur de bout en bout. N’enregistrez pas la même valeur en parallèle avec un autre mécanisme sans avoir défini la source de vérité.

Avant le déploiement, vérifiez que la fonction d’enregistrement existe et consultez la documentation correspondant à la version installée. Si elle n’est pas disponible, ne simulez pas la compatibilité avec JavaScript : mettez à jour ou choisissez une solution compatible avec le checkout utilisé, et testez-la dans un environnement de staging.

Valider, normaliser et persister côté serveur

La validation dans le navigateur améliore l’expérience, mais ne constitue pas un contrôle de sécurité. Côté serveur, vérifiez la présence de la donnée lorsqu’elle est obligatoire, son type, sa longueur, son format et son appartenance aux options autorisées. Pour les listes fermées, validez des identifiants connus, et non du texte arbitraire envoyé par le client. Si la donnée est facultative, définissez si l’absence et une valeur vide ont la même signification. En cas de valeur non valide, affichez une erreur compréhensible et ne confirmez pas la commande en omettant silencieusement une donnée nécessaire.

Dans le flux classique, $order->update_meta_data() utilise l’API CRUD des commandes et évite d’écrire directement dans les tables ou de dépendre d’une structure de stockage spécifique. Dans le Checkout Block, laissez l’API des champs supplémentaires gérer l’association du champ et consultez sa valeur via l’API des commandes ou le mécanisme documenté pour cette intégration ; ne présumez pas qu’une clé interne de métadonnées est utilisée.

Pour vérifier la compatibilité, consultez les réglages WooCommerce afin de déterminer si le stockage haute performance des commandes (HPOS) ou le stockage basé sur les tables des publications est activé. Dans un environnement de test configuré de la même façon, créez une commande pour chaque flux, lisez-la comme objet WC_Order au moyen de wc_get_order($order_id) et vérifiez la donnée avec l’API CRUD, par exemple avec $order->get_meta('_delivery_instructions') pour le champ classique. Mettez la commande à jour, puis relisez-la ; n’utilisez pas de requêtes SQL directes sur les tables internes. Répétez ces vérifications après un changement de stockage ou la mise à jour d’extensions intervenant dans le checkout.

Consulter la donnée dans le back-office

La procédure de vérification opérationnelle consiste à créer une commande de test, à ouvrir WooCommerce > Commandes, à accéder à sa page de modification et à comparer la valeur affichée à celle qui a été envoyée. Pour le checkout classique, si la métadonnée n’apparaît pas dans l’écran utilisé par l’équipe, vous pouvez ajouter un affichage administratif à l’aide du hook de données de commande suivant :

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

Ce hook et la métadonnée de l’exemple concernent le checkout classique ; vérifiez leur affichage dans l’écran d’administration activé sur la boutique. Avec HPOS et l’écran de modification des commandes basé sur des blocs, vérifiez le résultat réel : ne supposez pas qu’une extension du panneau classique prend automatiquement en charge la nouvelle interface. Utilisez toujours l’objet de commande et l’API CRUD pour lire ou modifier les données.

Les champs enregistrés par l’API du Checkout Block peuvent être intégrés aux détails de la commande. Vérifiez-le dans WooCommerce > Commandes à l’aide d’une commande de test. Si un autre code doit consulter la valeur, repérez dans la documentation de l’API l’emplacement et le mécanisme de lecture correspondant à la version installée ; ne devinez pas la clé de métadonnées. Si la valeur ne s’affiche pas, ajoutez un affichage administratif compatible avec cet écran et testez-le avec le stockage configuré ainsi qu’avec les extensions d’administration installées.

Si la modification est nécessaire, définissez les rôles autorisés et enregistrez les changements à l’aide de l’API CRUD des commandes. N’affichez pas automatiquement la donnée dans les e-mails, les documents, les exportations ou les écrans publics : n’ajoutez chaque destination que si elle répond à un besoin opérationnel, limitez l’accès et échappez toujours les valeurs en sortie.

Tester le cycle complet et éviter les régressions

Un test qui vérifie uniquement que le champ est rendu ne suffit pas. Vérifiez le parcours du formulaire jusqu’à l’utilisation ultérieure et couvrez au minimum les cas suivants :

• Commande valide avec une donnée renseignée : valider, enregistrer avec la bonne commande et consulter dans le back-office.
• Champ facultatif vide et champ obligatoire absent : vérifier le comportement défini pour chaque cas.
• Entrée falsifiée, non scalaire, trop longue ou en dehors des options autorisées : confirmer son rejet côté serveur.
• Texte avec accents et caractères Unicode multioctets, y compris à la limite exacte ; vérifier également l’interaction avec maxlength.
• Mise à jour de la commande : vérifier ce qui change, qui peut le modifier et comment la mise à jour est propagée.
• Checkout classique et Checkout Block : tester le flux actif ainsi que tout changement de mode prévu.
• Autorisations et exposition : vérifier que seuls les utilisateurs et processus autorisés reçoivent la valeur.

Incluez des tests de régression des totaux, des validations et de la création de la commande. Si une automatisation utilise le champ, testez également ce qui se passe si sa valeur manque ou si son envoi échoue. Un signe de diagnostic clair est que la donnée apparaisse dans le navigateur, mais pas dans la commande ni dans le processus censé l’utiliser.

Liste de contrôle avant le déploiement

• La finalité de la donnée et le moment où elle est recueillie sont documentés.
• Le mécanisme correspond au checkout actif : hooks du flux classique ou API des champs supplémentaires pour le Block.
• Le serveur valide le type, le format et la longueur ; les entrées non scalaires sont rejetées et le traitement des valeurs absentes, vides et non valides est défini.
• L’installation et le stockage des commandes ont été identifiés ; la lecture et la mise à jour sont testées avec l’API CRUD.
• Une commande de test confirme la lecture dans l’écran de back-office utilisé et l’accès est limité.
• Les tests couvrent les caractères Unicode, les mises à jour, les erreurs, les intégrations et les régressions du checkout.