本文深入探讨了在woocommerce中实现条件赠品功能的技术细节，包括当特定商品被添加到购物车时自动添加赠品，以及当触发商品被移除时同步移除赠品。核心内容聚焦于解决`woocommerce_add_to_cart`钩子可能导致的无限递归问题，并提供了一套安全、高效的解决方案，确保购物车状态的准确性和一致性。
引言
在电子商务运营中，通过提供免费赠品来激励购买是一种常见的营销策略。WooCommerce 平台提供了丰富的钩子（Hooks）和函数，允许开发者实现各种复杂的购物车逻辑。其中一个常见需求是：当用户将特定商品（称为“触发商品”）添加到购物车时，自动添加一个免费赠品；同时，当触发商品从购物车中移除时，该赠品也应随之移除，以保持购物车状态的逻辑一致性。
然而，在实现这一功能时，开发者可能会遇到一些技术挑战，特别是当尝试在 woocommerce_add_to_cart 钩子内部再次调用 WC()-youjiankuohaophpcncart->add_to_cart() 函数时，容易陷入无限递归的陷阱。本文将详细阐述如何安全地解决这一问题，并提供一套完整的代码实现方案。
核心问题：woocommerce_add_to_cart 钩子的递归陷阱
woocommerce_add_to_cart 是一个在商品成功添加到购物车后触发的动作钩子。当我们在该钩子的回调函数中再次调用 WC()->cart->add_to_cart() 来添加赠品时，这个新的添加操作会再次触发 woocommerce_add_to_cart 钩子，从而导致回调函数被重复调用，形成无限递归，最终可能导致服务器资源耗尽或页面错误。
问题根源： WC()->cart->add_to_cart() 函数内部会触发 woocommerce_add_to_cart 动作。
解决方案： 为了避免这种递归，我们需要在内部调用 WC()->cart->add_to_cart() 之前，暂时移除当前正在执行的 woocommerce_add_to_cart 钩子，待赠品添加完成后再将其重新添加回来。
安全添加赠品到购物车
以下代码演示了如何在触发商品被添加到购物车时，安全地添加一个或多个免费赠品。
/**
* 功能：当特定商品被添加到购物车时，自动添加免费赠品。
*
* @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 );代码解析：
- 定义商品ID： $free_product_ids 存储赠品的ID，$trigger_product_ids 存储触发赠品的商品ID。
- 遍历购物车： 代码会检查当前购物车中是否已存在赠品（通过自定义元数据 free_gift_meta 识别）以及是否存在触发商品。
- 条件判断： 只有当购物车中存在触发商品但不存在赠品时，才会执行添加赠品的操作。
- 防止递归： remove_action() 和 add_action() 是防止无限递归的关键。在调用 WC()->cart->add_to_cart() 之前移除当前钩子，操作完成后再重新添加。
- 自定义元数据： 在添加赠品时，我们通过 array( 'free_gift_meta' => 'yes' ) 为赠品添加了一个自定义元数据。这对于后续识别和移除赠品至关重要，因为它能区分用户手动添加的同款商品和系统自动添加的赠品。
移除赠品：同步购物车状态
当触发商品被移除时，相应的赠品也应被移除。为了确保购物车状态的实时同步和准确性，我们不应依赖 woocommerce_cart_item_removed 钩子（因为它在商品已被移除后才触发），而是在每次购物车内容更新或总价计算之前进行检查。woocommerce_before_calculate_totals 钩子是一个理想的选择，它在购物车总价计算前触发，允许我们调整购物车内容。
/**
* 功能：在购物车总价计算前，检查并同步移除不再符合条件的免费赠品。
*/
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 );代码解析：
- 钩子选择： woocommerce_before_calculate_totals 确保在每次购物车内容可能发生变化（例如，商品数量更新、商品移除、页面加载等）且需要计算总价前，都能检查并调整购物车状态。
- 防止后台执行： if ( is_admin() && ! defined( 'DOING_AJAX' ) ) { return; } 这一行是最佳实践，用于避免在WordPress后台不必要地执行此逻辑，仅在前端或AJAX请求时生效。
- 遍历检查： 代码同样遍历购物车，检查触发商品是否存在，并收集所有被标记为赠品的商品项键。
- 条件移除： 如果购物车中不存在任何触发商品，但存在赠品，则遍历收集到的赠品项键，并使用 WC()->cart->remove_cart_item() 逐一移除。
- 重新计算总价： 在移除商品后，调用 $cart->calculate_totals(); 是必要的，以确保购物车总价和显示信息能够立即更新。
完整示例代码
将上述两个函数放置到您的主题 functions.php 文件或自定义插件中即可实现所需功能。
<?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 
