WooCommerce 条件赠品管理：安全添加与同步移除购物车商品

/**
 * 功能：当特定商品被添加到购物车时，自动添加免费赠品。
 *
 * @param string $cart_item_key  购物车商品项的唯一键。
 * @param int    $product_id     被添加到购物车的商品ID。
 * @param int    $quantity       被添加到购物车的商品数量。
 * @param int    $variation_id   如果商品是变体，则是变体ID。
 * @param array  $variation      变体数据数组。
 * @param array  $cart_item_data 购物车商品项的额外数据。
 */
function tutorial_add_free_gift_product_to_cart( $cart_item_key, $product_id, $quantity, $variation_id, $variation, $cart_item_data ) {
    $free_product_ids    = array( 20070, 39039 ); // 定义赠品的商品ID数组
    $trigger_product_ids = array( 38162, 38157 ); // 定义触发赠品的商品ID数组

    $cart = WC()->cart;
    $is_free_gift_present     = false;
    $is_trigger_product_present = false;

    // 遍历购物车，检查是否存在赠品和触发商品
    foreach ( $cart->get_cart() as $item_key => $item ) {
        $_product_id = $item['product_id'];

        // 检查是否存在赠品，并通过自定义元数据识别
        if ( in_array( $_product_id, $free_product_ids ) && isset( $item['free_gift_meta'] ) && $item['free_gift_meta'] === 'yes' ) {
            $is_free_gift_present = true;
        }
        // 检查是否存在触发商品
        if ( in_array( $_product_id, $trigger_product_ids ) ) {
            $is_trigger_product_present = true;
        }
    }

    // 如果购物车中存在触发商品但不存在赠品，则添加赠品
    if ( $is_trigger_product_present && ! $is_free_gift_present ) {
        // 关键步骤：在添加商品前，暂时移除当前钩子，防止无限递归
        // 注意：函数名必须与 add_action 中的回调函数名一致
        remove_action( 'woocommerce_add_to_cart', 'tutorial_add_free_gift_product_to_cart', 10, 6 );

        foreach ( $free_product_ids as $free_id ) {
            // 添加赠品，并附带自定义元数据以方便识别和移除
            // 参数说明：$product_id, $quantity, $variation_id, $variation, $cart_item_data
            $cart->add_to_cart( $free_id, 1, 0, array(), array( 'free_gift_meta' => 'yes' ) );
        }

        // 重新添加钩子
        add_action( 'woocommerce_add_to_cart', 'tutorial_add_free_gift_product_to_cart', 10, 6 );
    }
}
// 使用 'woocommerce_add_to_cart' 钩子，它在商品添加到购物车后触发
// 优先级设为10，接受6个参数
add_action( 'woocommerce_add_to_cart', 'tutorial_add_free_gift_product_to_cart', 10, 6 );

/**
 * 功能：在购物车总价计算前，检查并同步移除不再符合条件的免费赠品。
 */
function tutorial_sync_free_gift_on_cart_update() {
    // 确保只在前端和AJAX请求中执行，避免在后台管理页面产生不必要的操作
    if ( is_admin() && ! defined( 'DOING_AJAX' ) ) {
        return;
    }

    $free_product_ids    = array( 20070, 39039 ); // 赠品ID
    $trigger_product_ids = array( 38162, 38157 ); // 触发赠品的商品ID

    $cart = WC()->cart;
    $is_trigger_product_present = false;
    $free_gift_cart_item_keys   = array();

    // 遍历购物车，检查触发商品是否存在，并收集赠品的购物车项键
    foreach ( $cart->get_cart() as $cart_item_key => $item ) {
        $_product_id = $item['product_id'];

        // 检查是否存在触发商品
        if ( in_array( $_product_id, $trigger_product_ids ) ) {
            $is_trigger_product_present = true;
        }
        // 检查是否存在赠品，并通过自定义元数据识别
        if ( in_array( $_product_id, $free_product_ids ) && isset( $item['free_gift_meta'] ) && $item['free_gift_meta'] === 'yes' ) {
            $free_gift_cart_item_keys[] = $cart_item_key;
        }
    }

    // 如果购物车中不存在触发商品，但存在赠品，则移除这些赠品
    if ( ! $is_trigger_product_present && ! empty( $free_gift_cart_item_keys ) ) {
        foreach ( $free_gift_cart_item_keys as $item_key_to_remove ) {
            $cart->remove_cart_item( $item_key_to_remove );
        }
        // 移除后，需要重新计算购物车，以更新总价和显示
        $cart->calculate_totals();
    }
}
// 使用 'woocommerce_before_calculate_totals' 钩子，确保在计算总价前购物车状态正确
add_action( 'woocommerce_before_calculate_totals', 'tutorial_sync_free_gift_on_cart_update', 10 );

<?php
/**
 * WooCommerce 条件赠品管理：安全添加与同步移除购物车商品
 *
 * 当特定商品被添加到购物车时，自动添加赠品。
 * 当触发商品从购物车中移除时，同步移除赠品。
 */

// 1. 安全添加赠品到购物车
function tutorial_add_free_gift_product_to_cart( $cart_item_key, $product_id, $quantity, $variation_id, $variation, $cart_item_data ) {
    $free_product_ids    = array( 20070, 390