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

Что делает фильтр woocommerce_order_item_product и когда он нужен

Фильтр woocommerce_order_item_product позволяет изменить объект товара (WC_Product), связанный с элементом заказа (WC_Order_Item_Product). Это полезно, когда нужно динамически добавлять или переопределять данные продукта в контексте конкретного заказа — например, добавить пользовательские метаданные, которые не сохраняются в стандартном объекте товара, но нужны при отображении или обработке заказа.

Пример: вы хотите отображать в заказе дополнительные свойства товара, которые зависят от выбора покупателя или внешних данных, не сохранённых в базе как атрибуты товара.

Диагностика проблемы: почему фильтр может не работать

• Фильтр добавлен, но изменения не видны в админке или на фронтенде.
• Данные, добавленные к объекту товара, не сохраняются и пропадают после перезагрузки.
• Ошибка типов: передается не объект WC_Product, а другой тип данных.
• Конфликт с другими плагинами, которые переопределяют этот же объект позднее.

Пошаговое решение: как корректно использовать фильтр woocommerce_order_item_product

1. Добавьте фильтр в файл functions.php вашей темы или в кастомный плагин.

add_filter('woocommerce_order_item_product', 'wpplugin_add_custom_data_to_order_product', 10, 3);
function wpplugin_add_custom_data_to_order_product($product, $item, $order) {
    // Проверяем, что это именно объект WC_Product
    if (!is_a($product, 'WC_Product')) {
        return $product;
    }

    // Получаем ID товара
    $product_id = $product->get_id();

    // Получаем дополнительные данные из метаполя заказа
    $custom_value = $item->get_meta('custom_order_meta_key');

    if ($custom_value) {
        // Добавляем эти данные в объект товара как новое свойство
        $product->custom_order_data = $custom_value;
    }

    return $product;
}

2. Убедитесь, что метаданные custom_order_meta_key действительно сохранены в элементах заказа. Их можно добавить при обработке корзины или в момент оформления заказа.

add_action('woocommerce_checkout_create_order_line_item', 'wpplugin_save_custom_meta_to_order_item', 10, 4);
function wpplugin_save_custom_meta_to_order_item($item, $cart_item_key, $values, $order) {
    if (!empty($values['custom_cart_data'])) {
        $item->add_meta_data('custom_order_meta_key', sanitize_text_field($values['custom_cart_data']));
    }
}

3. Для отображения кастомных данных в шаблонах, например, в списке товаров заказа, используйте добавленное свойство custom_order_data:

$order = wc_get_order($order_id);
foreach ($order->get_items() as $item) {
    $product = apply_filters('woocommerce_order_item_product', $item->get_product(), $item, $order);
    if (!empty($product->custom_order_data)) {
        echo 'Доп. данные: ' . esc_html($product->custom_order_data);
    }
}

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

• Создайте заказ с кастомными данными в корзине, например, через программное добавление или расширение формы товара.
• Откройте заказ в админке WooCommerce, проверьте, что метаданные корректно сохранены в элементах заказа (вкладка "Метаданные" в редактировании заказа).
• Отобразите заказ на фронтенде с использованием фильтра — проверьте, что дополнительная информация выводится корректно.
• Убедитесь, что после обновления страницы данные не пропадают.

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

• Ошибка: Добавление данных к объекту товара, но они не отображаются.
  Причина: Не применён фильтр при выводе или данные добавлены не к тому объекту.
  Решение: Используйте фильтр woocommerce_order_item_product именно при выводе товаров заказа, не просто получайте объект напрямую.
• Ошибка: Данные не сохраняются в элементе заказа.
  Причина: Метаданные не добавлены в хук woocommerce_checkout_create_order_line_item.
  Решение: Добавьте сохранение метаданных именно в этот хук.
• Ошибка: Конфликт с другими плагинами, перезаписывающими объект товара.
  Решение: Попробуйте установить приоритет фильтра выше (например, 20), чтобы применить ваши изменения позже.

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

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

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