WooCommerce：重写WC_Payment_Gateway_CC的needs_setup方法未触发

前置条件 #

• 我已执行故障排查步骤，认为发现了一个bug。
• 我已搜索开放和已关闭的类似问题，未找到重复项。

问题描述 #

当我为自定义的WC_Payment_Gateway_CC支付网关重写needs_setup方法时，该方法从未被调用。想确认这个方法是否已被弃用。

代码示例：

public function needs_setup(): bool {
    WC_MyGateway_Logger::logg('DEBUG: ' . $this->id . ' ' . $this->plugin_id); // 从未执行到这里
    return empty($this->get_option('account_id'));
}

预期行为 #

重写needs_setup方法后该方法应被触发，并且像PayPal插件一样显示“完成设置”按钮。

实际行为 #

无任何反应。

复现步骤 #

使用WooCommerce版本10.2.0-dev。

WordPress环境 #

系统状态报告可在WordPress后台的WooCommerce > 状态中找到。请选择“获取系统报告”，然后“复制到GitHub”，再粘贴到此处。

问题隔离验证 #

• 我已停用其他插件，确认仅WooCommerce插件激活时仍会出现此bug。
• 此bug在默认WordPress主题或Storefront主题激活时会出现。
• 我可以按照上述步骤稳定复现此bug。

我在自己的WooCommerce支付网关中重写了这个公共方法，但它被完全忽略了。

问题解答 #

needs_setup方法并未被弃用，但在WooCommerce 10.x版本中，它的调用逻辑有以下变化需要注意：

1. 启用状态限制：该方法仅在支付网关处于启用状态时，才会在支付网关列表页面（WooCommerce > 设置 > 支付）的渲染流程中被调用。如果你的网关未启用，方法不会执行。
2. 渲染逻辑依赖：新版本中“完成设置”按钮的渲染，不再仅依赖needs_setup的返回值，而是关联woocommerce_payment_gateway_setup_actions钩子。需确保网关正确注册了设置链接，或通过钩子手动添加提示。
3. 代码自检：确认自定义网关类正确继承WC_Payment_Gateway_CC，且needs_setup方法为public（你的代码已满足）。同时检查日志函数WC_MyGateway_Logger::logg是否正常工作，避免因日志失效误以为方法未执行。
4. 替代方案：如果needs_setup调用仍异常，可通过钩子手动添加设置提示，示例代码：

add_action('woocommerce_admin_payment_gateways_after_title_' . $this->id, function() {
    if (empty($this->get_option('account_id'))) {
        echo '<div class="notice notice-warning inline"><p>' . __('请完成支付网关设置', 'your-text-domain') . ' <a href="' . esc_url($this->get_settings_url()) . '">' . __('前往设置', 'your-text-domain') . '</a></p></div>';
    }
});

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