本文提供了一份关于在 woocommerce 中实现自动赠品系统的全面指南。它解决了在程序化添加产品时常见的 `woocommerce_add_to_cart` 递归问题，并提供了一个使用自定义购物车项元数据来管理关联赠品的健壮解决方案，确保赠品能与特定主产品同步添加和移除。
引言
在电子商务中，为特定产品提供赠品是一种常见的营销策略。理想情况下，当顾客将主产品添加到购物车时，赠品应自动添加；当主产品被移除时，赠品也应同步移除。本文将详细介绍如何在 WooCommerce 中实现这一功能，并解决在开发过程中可能遇到的关键技术挑战，特别是 woocommerce_add_to_cart 钩子引起的递归问题。
核心问题分析：woocommerce_add_to_cart 递归循环
在 WooCommerce 中，woocommerce_add_to_cart 是一个非常有用的动作钩子，它在产品被添加到购物车时触发。开发者通常会尝试在此钩子内部调用 WC()-youjiankuohaophpcncart->add_to_cart() 来添加额外的产品（例如赠品）。然而，这样做会导致一个严重的无限递归循环：
- 用户将产品 A 添加到购物车。
- woocommerce_add_to_cart 钩子触发。
- 在钩子回调函数中，代码调用 WC()->cart->add_to_cart() 来添加赠品 B。
- 添加赠品 B 的操作又会再次触发 woocommerce_add_to_cart 钩子。
- 这个循环将无限重复，最终导致服务器资源耗尽或 PHP 错误。
为了避免这种递归，我们需要在程序化添加赠品之前，暂时解除 woocommerce_add_to_cart 钩子，完成添加后再重新挂载。
实现赠品自动添加功能
以下是实现当特定主产品被添加到购物车时，自动添加一个或多个赠品的代码示例。我们通过自定义购物车项元数据 (is_free_gift) 来标记赠品，以便后续管理。
/**
* 当特定主产品添加到购物车时，自动添加赠品。
*
* @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 gift_add_product_to_cart_handler( $cart_item_key, $product_id, $quantity, $variation_id, $variation, $cart_item_data ) {
// 定义需要触发赠品的主产品ID列表
$allowed_main_product_ids = array(38162, 38157);
// 定义作为赠品的商品ID列表
$gift_product_ids = array(20070, 39039);
// 检查当前添加的产品是否是指定的主产品之一
if ( ! in_array( $product_id, $allowed_main_product_ids ) ) {
return; // 如果不是主产品，则不执行赠品逻辑
}
$cart = WC()->cart->get_cart();
$has_gift_in_cart = false;
$main_product_present_after_add = false;
// 遍历购物车，检查是否已存在任何指定赠品
foreach ( $cart as $item_values ) {
if ( in_array( $item_values['product_id'], $gift_product_ids ) && isset( $item_values['is_free_gift'] ) && $item_values['is_free_gift'] === true ) {
$has_gift_in_cart = true;
break;
}
}
// 遍历购物车，检查是否至少有一个指定的主产品（包括刚刚添加的）
foreach ( $cart as $item_values ) {
if ( in_array( $item_values['product_id'], $allowed_main_product_ids ) ) {
$main_product_present_after_add = true;
break;
}
}
// 如果购物车中存在主产品但没有赠品，则添加赠品
if ( $main_product_present_after_add && ! $has_gift_in_cart ) {
// 关键步骤：在添加赠品前暂时移除此动作，以避免无限递归
remove_action( 'woocommerce_add_to_cart', 'gift_add_product_to_cart_handler', 10, 6 );
foreach ( $gift_product_ids as $gift_id ) {
// 添加赠品到购物车，并使用自定义元数据 'is_free_gift' 标记为免费赠品
WC()->cart->add_to_cart( $gift_id, 1, 0, array(), array( 'is_free_gift' => true ) );
}
// 关键步骤：重新添加此动作
add_action( 'woocommerce_add_to_cart', 'gift_add_product_to_cart_handler', 10, 6 );
}
}
add_action( 'woocommerce_add_to_cart', 'gift_add_product_to_cart_handler', 10, 6 );代码解析：
- $allowed_main_product_ids 和 $gift_product_ids：定义了主产品和赠品的 ID 列表，方便管理。
- 避免递归：在调用 WC()->cart->add_to_cart() 之前，使用 remove_action() 暂时解除当前函数对 woocommerce_add_to_cart 钩子的绑定。添加完成后，立即使用 add_action() 重新绑定。这是解决无限循环的关键。
- 自定义元数据：通过 array( 'is_free_gift' => true ) 将一个自定义字段添加到赠品购物车项中。这使得我们能够轻松识别和管理赠品，而不是仅仅依靠产品 ID。
- 条件判断：在添加赠品之前，代码会检查购物车中是否已经存在主产品和赠品，以避免重复添加。
实现赠品自动移除功能
当所有指定的主产品都从购物车中移除时，相应的赠品也应该被移除。我们使用 woocommerce_cart_item_removed 钩子来监听购物车项的移除事件。
/**
* 当所有关联的主产品从购物车中移除时，自动移除赠品。
*
* @param string $cart_item_key 被移除购物车项的唯一键。
* @param WC_Cart $cart WooCommerce 购物车对象。
*/
function gift_remove_product_from_cart_handler( $cart_item_key, $cart ) {
// 定义需要触发赠品的主产品ID列表
$allowed_main_product_ids = array(38162, 38157);
// 定义作为赠品的商品ID列表
$gift_product_ids 
