自定义WooCommerce支付网关在结账页面不显示问题求助

问题背景 #

我正在开发一款集成自定义WooCommerce支付网关的插件，已在WordPress后台成功激活，但结账页面仍未显示该支付选项。相关版本信息：WooCommerce 8.4.0，WordPress 6.4.2。插件完整代码如下：

if (!defined("ABSPATH")) {
    exit(); // Exit if accessed directly.
}

// Hook to plugins_loaded to ensure WooCommerce is loaded
add_action("plugins_loaded", "init_woocommerce_to_stripe", 0);

function init_woocommerce_to_stripe()
{
    if (!class_exists("WC_Payment_Gateway")) {
        return;
    }

    // Define the custom payment gateway class
    class WC_Gateway_WooCommerce_To_Stripe extends WC_Payment_Gateway
    {
        // Declare properties
        public $redirect_url;

        public function __construct()
        {
            // Basic setup for the gateway
            $this->id = "woocommerce_to_stripe";
            $this->has_fields = false;
            $this->icon = "";
            $this->method_title = "WooCommerce to Stripe";
            $this->method_description =
                "Redirects users to a custom URL with order ID and total amount for Stripe payments.";
            $this->supports = [];

            // Initialize settings
            $this->init_form_fields();
            $this->init_settings();

            // Get settings values
            $this->title = $this->get_option("title");
            $this->description = $this->get_option("description");
            $this->enabled = $this->get_option("enabled");

            // Use the constructor to set dynamic properties
            $this->redirect_url = $this->get_option(
                "redirect_url",
                "https://www.example.com/"
            ); // Default redirect URL

            // Save settings on WooCommerce admin options update
            add_action(
                "woocommerce_update_options_payment_gateways_" . $this->id,
                [$this, "process_admin_options"]
            );
        }

        // Define form fields for WooCommerce settings
        public function init_form_fields()
        {
            $this->form_fields = [
                "enabled" => [
                    "title" => "Enable/Disable",
                    "type" => "checkbox",
                    "label" => "Enable WooCommerce to Stripe",
                    "default" => "yes",
                ],
                "title" => [
                    "title" => "Title",
                    "type" => "text",
                    "description" =>
                        "This controls the title which the user sees during checkout.",
                    "default" => "WooCommerce to Stripe",
                    "desc_tip" => true,
                ],
                "description" => [
                    "title" => "Description",
                    "type" => "textarea",
                    "description" =>
                        "This controls the description which the user sees during checkout.",
                    "default" =>
                        "Redirects users to a custom URL with order ID and total amount for Stripe payments.",
                ],
                "redirect_url" => [
                    "title" => "Redirect URL",
                    "type" => "text",
                    "description" =>
                        "Enter the custom URL where users will be redirected with order ID and total amount.",
                    "default" => "https://www.example.com/",
                ],
            ];
        }

        // Process payment and redirect to the custom URL
        public function process_payment($order_id)
        {
            $order = wc_get_order($order_id);

            // Redirect URL with order ID and total amount as query parameters
            $redirect_url =
                $this->redirect_url .
                "?order_id=" .
                $order_id .
                "&total_amount=" .
                $order->get_total();

            return [
                "result" => "success",
                "redirect" => $redirect_url,
            ];
        }
    }

    // Register the custom payment gateway class
    function add_woocommerce_to_stripe_gateway($gateways)
    {
        $gateways[] = "WC_Gateway_WooCommerce_To_Stripe";

        return $gateways;
    }

    // Filter to add the custom payment gateway class
    add_filter(
        "woocommerce_payment_gateways",
        "add_woocommerce_to_stripe_gateway",
        999
    );
}

问题排查与修复 #

代码存在两个核心问题导致支付网关无法显示：

• 内部函数作用域限制：add_woocommerce_to_stripe_gateway函数定义在init_woocommerce_to_stripe内部，woocommerce_payment_gateways过滤器无法正确调用到该函数，因为内部函数的作用域仅局限于父函数内部。
• 支持特性缺失：$this->supports设为空数组，部分场景下WooCommerce会过滤掉未声明基础支持项的网关。

修改后的完整代码 #

if (!defined("ABSPATH")) {
    exit(); // 直接访问时退出
}

// 钩子到plugins_loaded确保WooCommerce已加载
add_action("plugins_loaded", "init_woocommerce_to_stripe", 0);

function init_woocommerce_to_stripe()
{
    if (!class_exists("WC_Payment_Gateway")) {
        return;
    }

    // 定义自定义支付网关类
    class WC_Gateway_WooCommerce_To_Stripe extends WC_Payment_Gateway
    {
        // 声明属性
        public $redirect_url;

        public function __construct()
        {
            // 网关基础设置
            $this->id = "woocommerce_to_stripe";
            $this->has_fields = false;
            $this->icon = "";
            $this->method_title = "WooCommerce 转 Stripe";
            $this->method_description = "将用户重定向到自定义URL，携带订单ID和总金额用于Stripe支付。";
            // 添加基础支持特性
            $this->supports = [
                "products",
                "refunds"
            ];

            // 初始化设置
            $this->init_form_fields();
            $this->init_settings();

            // 获取设置值
            $this->title = $this->get_option("title");
            $this->description = $this->get_option("description");
            $this->enabled = $this->get_option("enabled");

            // 通过构造函数设置动态属性
            $this->redirect_url = $this->get_option(
                "redirect_url",
                "https://www.example.com/"
            ); // 默认重定向URL

            // 保存WooCommerce后台选项更新时的设置
            add_action(
                "woocommerce_update_options_payment_gateways_" . $this->id,
                [$this, "process_admin_options"]
            );
        }

        // 定义WooCommerce设置的表单字段
        public function init_form_fields()
        {
            $this->form_fields = [
                "enabled" => [
                    "title" => "启用/禁用",
                    "type" => "checkbox",
                    "label" => "启用 WooCommerce 转 Stripe",
                    "default" => "yes",
                ],
                "title" => [
                    "title" => "标题",
                    "type" => "text",
                    "description" => "控制用户在结账时看到的标题。",
                    "default" => "WooCommerce 转 Stripe",
                    "desc_tip" => true,
                ],
                "description" => [
                    "title" => "描述",
                    "type" => "textarea",
                    "description" => "控制用户在结账时看到的描述。",
                    "default" => "将用户重定向到自定义URL，携带订单ID和总金额用于Stripe支付。",
                ],
                "redirect_url" => [
                    "title" => "重定向URL",
                    "type" => "text",
                    "description" => "输入用户将被重定向的自定义URL，会携带订单ID和总金额参数。",
                    "default" => "https://www.example.com/",
                ],
            ];
        }

        // 处理支付并重定向到自定义URL
        public function process_payment($order_id)
        {
            $order = wc_get_order($order_id);

            // 携带订单ID和总金额作为查询参数的重定向URL
            $redirect_url =
                $this->redirect_url .
                "?order_id=" .
                $order_id .
                "&total_amount=" .
                $order->get_total();

            return [
                "result" => "success",
                "redirect" => $redirect_url,
            ];
        }
    }
}

// 注册自定义支付网关类
function add_woocommerce_to_stripe_gateway($gateways)
{
    $gateways[] = "WC_Gateway_WooCommerce_To_Stripe";

    return $gateways;
}

// 添加过滤器注册自定义支付网关类
add_filter(
    "woocommerce_payment_gateways",
    "add_woocommerce_to_stripe_gateway",
    999
);

额外检查步骤 #

1. 进入WooCommerce后台设置 → 支付，找到"WooCommerce 转 Stripe"，确认开关已打开。
2. 清除WordPress缓存和浏览器缓存，避免缓存导致的显示异常。
3. 暂时禁用其他插件或切换默认主题，排查是否存在代码冲突。

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