Как использовать хук WooCommerce add_to_cart для кастомизации поведения корзины

Диагностика задачи: зачем использовать хук add_to_cart в WooCommerce

В WooCommerce хук woocommerce_add_to_cart позволяет запускать дополнительную логику сразу после добавления товара в корзину. Это помогает реализовать различные кейсы: добавление сопутствующих товаров, проверка условий корзины, изменение данных сессии пользователя и многое другое.

Часто пользователи сталкиваются с необходимостью изменить стандартное поведение корзины, например, автоматически добавлять бесплатный подарок при покупке определённого товара или ограничивать добавление товара по определённым правилам. Этот хук — оптимальное место для таких изменений.

Как правильно использовать хук woocommerce_add_to_cart

Хук срабатывает после того, как товар был добавлен в корзину. Его сигнатура:

do_action( 'woocommerce_add_to_cart', $cart_item_key, $product_id, $quantity, $variation_id, $variation, $cart_item_data );

Параметры:

• $cart_item_key — уникальный ключ позиции в корзине;
• $product_id — ID добавленного товара;
• $quantity — количество;
• $variation_id — ID вариации, если есть;
• $variation — массив вариаций;
• $cart_item_data — дополнительные данные элемента корзины.

Пример 1: Автоматическое добавление подарочного товара

Если покупатель добавляет товар с ID 123, автоматически добавим в корзину подарок с ID 456:

add_action('woocommerce_add_to_cart', 'add_gift_on_product_add', 10, 6);
function add_gift_on_product_add($cart_item_key, $product_id, $quantity, $variation_id, $variation, $cart_item_data) {
    if ($product_id == 123) {
        $gift_id = 456;
        // Проверяем, что подарок уже не в корзине
        foreach (WC()->cart->get_cart() as $key => $item) {
            if ($item['product_id'] == $gift_id) {
                return; // подарок уже есть
            }
        }
        WC()->cart->add_to_cart($gift_id, 1);
    }
}

Пример 2: Блокировка добавления товара при превышении лимита

Если в корзине уже есть 3 и более единиц товара с ID 789, блокируем добавление нового:

add_action('woocommerce_add_to_cart', 'limit_product_quantity_in_cart', 10, 6);
function limit_product_quantity_in_cart($cart_item_key, $product_id, $quantity, $variation_id, $variation, $cart_item_data) {
    if ($product_id == 789) {
        $total_qty = 0;
        foreach (WC()->cart->get_cart() as $item) {
            if ($item['product_id'] == 789) {
                $total_qty += $item['quantity'];
            }
        }
        if ($total_qty > 3) {
            WC()->cart->remove_cart_item($cart_item_key);
            wc_add_notice('Вы не можете добавить более 3 единиц этого товара.', 'error');
        }
    }
}

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

• Добавьте в корзину товар с ID 123 — должен автоматически появиться подарок с ID 456.
• Попробуйте добавить товар с ID 789 более 3 раз — появится сообщение об ошибке, товар не добавится.
• Проверьте корзину в админке и на фронтенде, убедитесь, что логика сработала.
• Для отладки можно временно добавить error_log() или использовать плагин Query Monitor.

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

• Добавление товара без проверки дубликатов. В результате подарок добавляется несколько раз — решается проверкой наличия товара в корзине перед добавлением.
• Удаление позиции корзины внутри хука без правильного cart_item_key. Может привести к ошибкам или бесконечным циклам. Всегда используйте $cart_item_key текущего элемента.
• Отсутствие сообщений для пользователя. Если блокируете добавление, обязательно добавляйте wc_add_notice() для информирования.
• Использование хуков с неправильным приоритетом или без указания количества аргументов. Вызовите add_action с нужными параметрами, иначе функции не получат все аргументы.

Практические советы по оптимизации и безопасности

• Не выполняйте тяжелые операции в хуках добавления в корзину — это может замедлить процесс и ухудшить UX.
• При работе с сессиями и корзиной всегда проверяйте, что объект WC()->cart инициализирован.
• Избегайте конфликтов с другими плагинами, которые тоже могут использовать этот хук. Для этого используйте уникальные имена функций и проверяйте существование товаров в корзине.
• Для сложной логики лучше создавать отдельные сервисные классы и вызывать их из функции-обработчика.

Сравнение вариантов реализации