WooCommerce 特定配送方式禁用支付网关空会话错误排查

从提供的PHP错误堆栈可以直接锁定三个核心问题：

• 原过滤器的执行范围未做场景限制：woocommerce_available_payment_gateways 钩子的触发场景不止前台结账页，WooCommerce后台首页的新手引导模块，在拉取可用支付网关列表用于展示设置任务时，也会触发这个钩子。
• 空值防护缺失：代码直接调用WC()->session->get()方法，但后台场景下WooCommerce不会初始化前台购物对应的session对象，此时WC()->session为null，直接调用方法就会触发“调用null对象方法”的致命错误。
• 潜在逻辑风险：即便session正常初始化，若chosen_shipping_methods为空值，直接访问数组第一个元素会触发未定义偏移的PHP警告。

1. 路径复现验证：按照错误堆栈的调用链，直接访问WooCommerce后台默认首页，确认报错完全复现，排除其他插件、主题功能的交叉冲突。
2. 逐分支校验执行环境：
   • 判断函数触发时是否处于后台请求场景
   • 判断WC()全局实例是否可用
   • 判断WC()->session是否为有效对象，而非null
   • 判断会话中存储的选中配送方式是否为非空数组
3. 收敛执行范围：因为自定义逻辑的需求仅作用于结账页的支付网关展示控制，需要把逻辑触发的场景严格限定在前台结账页、结账AJAX请求中，后台场景直接跳过自定义处理逻辑，返回原有的支付网关列表。

add_filter( 'woocommerce_available_payment_gateways', 'filter_woocommerce_available_payment_gateways', 10, 1 );
function filter_woocommerce_available_payment_gateways( $available_gateways ) { 
    // 直接跳过后台场景的执行，避免触发session空值错误
    if ( is_admin() ) {
        return $available_gateways;
    }

    $gateways_to_disable = array( 'cardgatecreditcard', 'cardgategiropay', 'cardgateideal', 'cardgatesofortbanking' );
    $shipping_methods = array( 'flat_rate', 'request_shipping_quote' );
    $disable_gateways = false;

    // 校验session对象是否存在，避免空值调用
    if ( ! WC()->session ) {
        return $available_gateways;
    }

    $chosen_shipping = WC()->session->get( 'chosen_shipping_methods' );
    // 校验选中的配送方式是否为有效数组，避免无效数组访问
    if ( ! is_array( $chosen_shipping ) || empty( $chosen_shipping[0] ) ) {
        return $available_gateways;
    }

    $chosen_shipping_slug = $chosen_shipping[0];
    // 匹配需要触发禁用逻辑的配送方式
    foreach ( $shipping_methods as $shipping_method ) {
        if ( strpos( $chosen_shipping_slug, $shipping_method ) !== false ) {
            $disable_gateways = true;
            break;
        }
    }
    
    // 匹配到目标配送方式时，移除指定的支付网关
    if ( $disable_gateways ) {
        foreach ( $available_gateways as $id => $gateway ) {
            if ( in_array( $id, $gateways_to_disable ) ) {
                unset( $available_gateways[$id] );
            }
        }
    }
    return $available_gateways;
}

• 打开WooCommerce后台所有页面，确认不再触发PHP致命错误
• 进入前台结账页，切换不同配送方式，确认对应支付网关的显示/隐藏逻辑符合预期
• 测试结账页无刷新切换配送方式时，支付网关列表的自动更新功能正常

内容的提问来源于stack exchange，提问作者Wanderlust Consulting