Как использовать фильтр woocommerce_order_item_product для добавления пользовательских данных к товарам заказа в WooCommerce

Что такое фильтр woocommerce_order_item_product и зачем он нужен

Фильтр woocommerce_order_item_product позволяет изменить объект товара, связанного с конкретным элементом заказа (order item) в WooCommerce. Это полезно, когда нужно динамически подставить или модифицировать свойства товара в контексте заказа, например, добавить пользовательские данные, метаданные или вычисленные параметры, которые не хранятся в стандартном объекте товара.

Чаще всего он применяется, если необходимо расширить информацию о товаре при отображении заказов в админке, на страницах пользователя или для дальнейшей логики в плагинах.

Диагностика задачи: почему стандартных данных товара недостаточно

Предположим, у вас есть магазин WooCommerce, где к товарам нужно привязать дополнительные данные, например:

• индивидуальный цвет или гравировка, выбранная пользователем;
• временные скидки, вычисленные на этапе оформления;
• информация о сторонних интеграциях, специфичная для заказа.

Если эти данные не сохраняются в метаданных заказа, то для вывода на странице заказа или в письмах стандартный объект товара не содержит нужной информации. Применение фильтра woocommerce_order_item_product позволяет подменить объект или добавить данные в объект товара для текущего элемента заказа.

Пошаговое решение: добавление пользовательских данных к товарам заказа через фильтр

1. Добавляем пользовательские данные в метаданные позиции заказа при оформлении

add_action('woocommerce_add_order_item_meta', 'add_custom_order_item_meta', 10, 3);
function add_custom_order_item_meta($item_id, $values, $cart_item_key) {
    if (!empty($values['custom_data'])) {
        wc_add_order_item_meta($item_id, 'custom_data', sanitize_text_field($values['custom_data']));
    }
}

Этот код сохраняет пользовательские данные из корзины в метаданные позиции заказа. Предполагается, что в $cart_item['custom_data'] уже есть нужное значение.

2. Используем фильтр woocommerce_order_item_product для добавления данных в объект товара

add_filter('woocommerce_order_item_product', 'add_custom_data_to_order_item_product', 10, 2);
function add_custom_data_to_order_item_product($product, $order_item) {
    $custom_data = $order_item->get_meta('custom_data');
    if ($custom_data) {
        // Добавляем свойство custom_data к объекту продукта
        $product->custom_data = $custom_data;
    }
    return $product;
}

В этом примере мы получаем метаданные custom_data из позиции заказа и добавляем их в объект $product как произвольное свойство.

3. Выводим пользовательские данные в шаблонах

add_action('woocommerce_order_item_meta_end', 'display_custom_data_in_order_item', 10, 3);
function display_custom_data_in_order_item($item_id, $item, $order) {
    if (!empty($item->get_product()->custom_data)) {
        echo '<p><strong>Пользовательские данные:</strong> ' . esc_html($item->get_product()->custom_data) . '</p>';
    }
}

Этот код выводит добавленные данные в блок метаданных позиции заказа, например, в письмах или на странице просмотра заказа.

Проверка результата после внедрения

1. Добавьте товар в корзину, передав в массив товара ключ custom_data с нужным значением, например:

   $cart_item_data['custom_data'] = 'Красный гравировка';

2. Оформите заказ и перейдите в админку WooCommerce → Заказы → выберите заказ → просмотр позиций заказа. Убедитесь, что данные появились в метаданных позиции.
3. Откройте страницу заказа в личном кабинете пользователя или письмо с подтверждением заказа, проверьте, что пользовательские данные выводятся корректно.

Частые ошибки и как их исправить

• Данные не сохраняются в заказе: проверьте, что данные передаются в корзину и обрабатываются через woocommerce_add_order_item_meta. Без этого фильтр woocommerce_order_item_product не сможет получить данные.
• Невозможно получить метаданные через $order_item->get_meta(): возможно, вы используете устаревшие методы (get_order_item_meta) или передали не объект WC_Order_Item_Product. Используйте именно get_meta() у объекта заказа позиции.
• Вывод данных отсутствует в шаблоне: убедитесь, что в шаблоне вызывается woocommerce_order_item_meta_end или аналогичный хук, и что вы используете правильный объект товара из позиции заказа.
• Конфликты с другими плагинами: фильтр меняет объект товара, будьте аккуратны с изменениями, не перезаписывайте важные свойства, чтобы избежать сбоев.

Практические советы по безопасности и производительности

• Всегда фильтруйте данные, получаемые из пользовательского ввода, перед сохранением в метаданные (sanitize_text_field, esc_html).
• Не сохраняйте в метаданных тяжелые или избыточные данные, чтобы не замедлять загрузку заказов и фронтенда.
• Добавленные свойства в объект товара должны быть уникальными, чтобы не конфликтовать с внутренними методами WooCommerce.
• Для массовых заказов или большого количества пользовательских данных рассмотрите возможность кеширования результатов для уменьшения нагрузки.

Сравнение методов добавления пользовательских данных к товарам заказа