Sylius项目支付网关插件集成开发指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_01126/article/details/148441142

Sylius项目支付网关插件集成开发指南

Sylius Sylius/Sylius: Sylius是一个基于Symfony PHP框架构建的开源电子商务平台，具备高度模块化和可配置性，提供商品管理、订单处理、库存控制等一系列电商核心功能，帮助企业快速搭建自己的在线商店。项目地址: https://gitcode.com/gh_mirrors/sy/Sylius

引言

在电子商务系统中，支付网关集成是核心功能之一。Sylius作为一个现代化的电商平台，提供了灵活的支付网关集成机制。本文将深入讲解如何在Sylius中开发自定义支付网关插件，涵盖从基础配置到高级集成的完整流程。

基础配置

1. 创建插件框架

首先需要创建一个标准的Sylius插件项目结构。建议使用Composer初始化项目：

composer init --name=acme/sylius-payment-plugin

2. 配置网关表单

支付网关通常需要特定的配置参数，如API密钥、商户ID等。我们需要创建一个配置表单类型：

namespace Acme\SyliusPaymentPlugin\Form\Type;

use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\FormBuilderInterface;

final class GatewayConfigurationType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            ->add('api_key', TextType::class, [
                'label' => 'API密钥',
                'required' => true
            ])
            ->add('merchant_id', TextType::class, [
                'label' => '商户ID',
                'required' => true
            ]);
    }
}

3. 服务注册与模板集成

在服务配置中注册表单类型，并关联到支付网关系统：

services:
  Acme\SyliusPaymentPlugin\Form\Type\GatewayConfigurationType:
    tags:
      - name: sylius.gateway_configuration_type
        type: custom_payment
        label: 'custom_payment.gateway.name'
      - name: form.type

前端模板集成使用Twig hooks机制，确保配置表单在管理后台正确显示：

sylius_twig_hooks:
  hooks:
    'sylius_admin.payment_method.create.content.form.sections.gateway_configuration.custom_payment':
      api_key:
        template: '@AcmeSyliusPaymentPlugin/admin/payment_method/fields/api_key.html.twig'
        priority: 10
      merchant_id:
        template: '@AcmeSyliusPaymentPlugin/admin/payment_method/fields/merchant_id.html.twig'
        priority: 20

支付处理核心逻辑

1. 命令提供者模式

Sylius 2.0+采用基于Symfony Messenger的命令总线处理支付操作，这种架构提供了更好的扩展性和灵活性。

基础命令提供者配置：

acme.payment.command_provider.custom_payment:
  class: Sylius\Bundle\PaymentBundle\CommandProvider\ActionsCommandProvider
  arguments:
    - !tagged_locator
        tag: acme.payment.command_provider.custom_payment
        index_by: 'action'
  tags:
    - name: sylius.payment_request.command_provider
      gateway_factory: 'custom_payment'

2. 支付捕获实现

对于捕获支付操作，需要创建专门的命令和处理器：

捕获命令：

namespace Acme\SyliusPaymentPlugin\Command;

use Sylius\Bundle\PaymentBundle\Command\PaymentRequestHashAwareInterface;
use Sylius\Bundle\PaymentBundle\Command\PaymentRequestHashAwareTrait;

class CapturePaymentRequest implements PaymentRequestHashAwareInterface
{
    use PaymentRequestHashAwareTrait;
    
    private float $amount;
    
    public function __construct(?string $hash, float $amount)
    {
        $this->hash = $hash;
        $this->amount = $amount;
    }
    
    public function getAmount(): float
    {
        return $this->amount;
    }
}

命令处理器：

namespace Acme\SyliusPaymentPlugin\CommandHandler;

use Acme\SyliusPaymentPlugin\Command\CapturePaymentRequest;
use Sylius\Abstraction\StateMachine\StateMachineInterface;
use Sylius\Bundle\PaymentBundle\Provider\PaymentRequestProviderInterface;
use Sylius\Component\Payment\PaymentRequestTransitions;
use Symfony\Component\Messenger\Attribute\AsMessageHandler;

#[AsMessageHandler]
final class CapturePaymentRequestHandler
{
    public function __construct(
        private PaymentRequestProviderInterface $paymentRequestProvider,
        private StateMachineInterface $stateMachine,
        private PaymentGatewayClientInterface $gatewayClient
    ) {}

    public function __invoke(CapturePaymentRequest $command): void
    {
        $paymentRequest = $this->paymentRequestProvider->provide($command);
        
        // 调用支付网关API
        $result = $this->gatewayClient->capture(
            $command->getAmount(),
            $paymentRequest->getDetails()
        );
        
        if ($result->isSuccessful()) {
            $this->stateMachine->apply(
                $paymentRequest,
                PaymentRequestTransitions::GRAPH,
                PaymentRequestTransitions::TRANSITION_COMPLETE
            );
        } else {
            $this->stateMachine->apply(
                $paymentRequest,
                PaymentRequestTransitions::GRAPH,
                PaymentRequestTransitions::TRANSITION_FAIL
            );
        }
    }
}

用户界面集成

1. HTTP响应提供者

对于需要用户交互的支付流程（如3D Secure验证），需要实现响应提供者：

namespace Acme\SyliusPaymentPlugin\OrderPay\Provider;

use Sylius\Bundle\PaymentBundle\Provider\HttpResponseProviderInterface;
use Sylius\Component\Payment\Model\PaymentRequestInterface;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpFoundation\Response;

final class RedirectHttpResponseProvider implements HttpResponseProviderInterface
{
    public function supports(PaymentRequestInterface $paymentRequest): bool
    {
        return $paymentRequest->getAction() === 'redirect';
    }

    public function getResponse(PaymentRequestInterface $paymentRequest): Response
    {
        $details = $paymentRequest->getDetails();
        
        return new RedirectResponse($details['redirect_url']);
    }
}

2. 支付状态页面

可以创建自定义的支付状态页面模板：

{# templates/bundles/SyliusShopBundle/Checkout/complete.html.twig #}
{% extends '@SyliusShop/Checkout/complete.html.twig' %}

{% block content %}
    {% if order.paymentState == 'awaiting_payment' %}
        <div class="ui segment">
            <h2 class="ui header">支付处理中</h2>
            <p>您的订单已创建，正在等待支付确认...</p>
            <div class="ui active centered inline loader"></div>
        </div>
    {% else %}
        {{ parent() }}
    {% endif %}
{% endblock %}

安全与最佳实践

敏感数据加密：
- 使用Sylius内置的加密机制保护API密钥等敏感信息
- 运行命令生成加密密钥：bin/console sylius:payment:generate-key

错误处理：

try {
    $result = $this->gatewayClient->processPayment($payment);
} catch (PaymentGatewayException $e) {
    $this->logger->error('Payment processing failed', [
        'error' => $e->getMessage(),
        'payment_id' => $payment->getId()
    ]);

    throw new PaymentProcessingException('支付处理失败，请重试');
}

日志记录：
- 记录所有支付网关交互
- 保存原始请求和响应数据

测试与验证

单元测试：

public function testCaptureHandler(): void
{
    $gatewayClient = $this->createMock(PaymentGatewayClientInterface::class);
    $gatewayClient->expects($this->once())
        ->method('capture')
        ->willReturn(new PaymentResult(true));

    $handler = new CapturePaymentRequestHandler(/* ... */);
    $handler(new CapturePaymentRequest('test_hash', 100.00));
}

功能测试：
- 测试完整的支付流程
- 验证不同支付状态下的行为

扩展与定制

支持更多支付操作：
- 退款(Refund)
- 预授权(Authorize)
- 取消(Void)

Webhook集成：

#[Route('/payment/webhook', name: 'payment_webhook')]
public function webhookAction(Request $request): Response
{
    $payload = json_decode($request->getContent(), true);
    $signature = $request->headers->get('X-Signature');

    if (!$this->gatewayClient->verifyWebhook($payload, $signature)) {
        return new Response('Invalid signature', 403);
    }

    // 处理webhook事件
    $this->commandBus->dispatch(new ProcessWebhook($payload));

    return new Response('OK');
}