WooCommerce: как использовать хуки для добавления дополнительного функционала

Что такое хуки в WooCommerce и зачем они нужны

Хуки (actions и filters) в WooCommerce — это точки расширения функционала без изменения исходных файлов плагина. Они позволяют добавлять, изменять или удалять поведение магазина, не ломая обновления.

Action-хуки выполняют функции в определённые моменты, например, при добавлении товара в корзину. Filter-хуки позволяют модифицировать данные перед выводом или сохранением.

Диагностика: как понять, какой хук использовать

Для интеграции дополнительного функционала необходимо:

• Определить, в какой момент работы WooCommerce нужно вмешаться (отображение, обработка заказа, корзина и т.д.).
• Найти подходящий хук в документации WooCommerce (https://docs.woocommerce.com/wc-apidocs/hook-docs.html).
• Проверить, что хук вызывается именно в нужном месте, например, с помощью временного error_log или вывода на экран.

Пошаговое решение: пример добавления дополнительного поля на страницу товара

Допустим, нужно добавить поле «Номер сертификата» на страницу товара и сохранить его вместе с заказом.

1. Добавляем поле на страницу товара

add_action('woocommerce_before_add_to_cart_button', function() {
    echo '<p class="form-row form-row-wide">
        <label for="certificate_number">Номер сертификата</label>
        <input type="text" id="certificate_number" name="certificate_number" />
    </p>';
});

2. Валидация поля при добавлении в корзину

add_filter('woocommerce_add_to_cart_validation', function($passed, $product_id, $quantity) {
    if (empty($_POST['certificate_number'])) {
        wc_add_notice('Пожалуйста, укажите номер сертификата.', 'error');
        return false;
    }
    return $passed;
}, 10, 3);

3. Сохранение поля в данные корзины

add_filter('woocommerce_add_cart_item_data', function($cart_item_data, $product_id, $variation_id) {
    if (!empty($_POST['certificate_number'])) {
        $cart_item_data['certificate_number'] = sanitize_text_field($_POST['certificate_number']);
        $cart_item_data['unique_key'] = md5(microtime().rand());
    }
    return $cart_item_data;
}, 10, 3);

4. Отображение поля в корзине и оформлении заказа

add_filter('woocommerce_get_item_data', function($item_data, $cart_item) {
    if (!empty($cart_item['certificate_number'])) {
        $item_data[] = array(
            'key' => 'Номер сертификата',
            'value' => wc_clean($cart_item['certificate_number'])
        );
    }
    return $item_data;
}, 10, 2);

5. Сохранение поля в метаданных заказа

add_action('woocommerce_checkout_create_order_line_item', function($item, $cart_item_key, $values, $order) {
    if (!empty($values['certificate_number'])) {
        $item->add_meta_data('Номер сертификата', $values['certificate_number']);
    }
}, 10, 4);

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

1. Откройте страницу товара и убедитесь, что поле «Номер сертификата» отображается под кнопкой «Добавить в корзину».
2. Попробуйте добавить товар без заполнения поля — появится ошибка.
3. Добавьте товар с номером сертификата, перейдите в корзину — в описании товара должно отображаться введённое значение.
4. Оформите заказ и проверьте в админке WooCommerce, что в метаданных заказа у товара есть «Номер сертификата».

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

• Поле не сохраняется в заказе: проверьте, что используется хук woocommerce_checkout_create_order_line_item, а не устаревший woocommerce_add_order_item_meta.
• Ошибка валидации не срабатывает: убедитесь, что функция подключена через фильтр woocommerce_add_to_cart_validation и возвращает false при ошибке.
• Данные не отображаются в корзине: проверьте фильтр woocommerce_get_item_data, он должен добавлять элементы в массив корректно.
• Конфликт с темой или плагином: временно переключитесь на стандартную тему Storefront и отключите другие плагины, чтобы локализовать проблему.

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

• Всегда используйте sanitize_text_field при обработке пользовательского ввода.
• Добавляйте уникальный ключ к данным корзины (unique_key), чтобы WooCommerce корректно различал позиции с разными метаданными.
• Минимизируйте количество тяжелых операций в хуках, чтобы не замедлять загрузку страниц.
• Используйте локальные переменные и кеширование, если обрабатываете данные в циклах.

Сравнение способов добавления пользовательского поля на страницу товара