Stripe PHP SDK v17.4.0-beta.1 版本解析：API 变更与功能演进

Stripe PHP SDK 是 Stripe 官方提供的 PHP 语言集成工具包，它让开发者能够便捷地与 Stripe 支付平台进行交互。本次发布的 v17.4.0-beta.1 版本是一个预发布版本，主要针对 API 版本 2025-05-28.preview 进行了多项重要更新，包含了一些破坏性变更和新功能引入。

核心变更概览

本次更新最显著的变化是对 Stripe API 预览功能的调整，移除了多个已弃用的预览资源和方法，同时对部分数据类型和枚举值进行了优化。这些变更反映了 Stripe 平台功能的演进方向，开发者需要特别注意其中的破坏性变更。

主要破坏性变更分析

1. 预览功能移除

• 完全移除了对 Billing.MeterErrorReport、GiftCards.Card、GiftCards.Transaction 和 Privacy.RedactionJobRootObjects 资源的支持
• 移除了 GiftCards.Card 和 GiftCards.Transaction 资源上的所有操作方法
• 产品对象中移除了 provisioning 属性支持
• 移除了特定的错误代码支持，如礼品卡相关的错误码

2. 数据类型变更

• PaymentAttemptRecord.metadata 和 PaymentRecord.metadata 从可空映射类型变为非空映射类型
• Privacy.RedactionJob.objects 类型从 $Privacy.RedactionJobRootObjects 变更为 RedactionResourceRootObjects
• 隐私相关作业的状态和验证行为字段从字符串类型变为枚举类型

3. 功能简化

• 移除了订单对象中的 amount_remaining 和 credits 属性
• 移除了支付意图中的 async_workflows 支持
• 移除了订阅计费模式中的特定枚举值

新增功能亮点

1. 订阅迁移支持 新增了 migrate 方法到 Subscription 资源，这为处理订阅计划变更提供了更优雅的解决方案。

2. 金融机构连接增强

• 账户对象新增 institution 属性
• 机构对象新增 countries 属性，支持多国家金融机构连接

3. 支付意图钩子 支付意图对象新增 hooks 支持，为支付流程提供了更灵活的扩展能力。

4. 订阅计费模式改进

• 新增 classic 和 flexible 枚举值到订阅计费模式
• 新增 billing_mode_details 到订阅对象，提供更详细的计费信息

开发者迁移建议

对于正在使用受影响功能的开发者，建议采取以下步骤进行迁移：

1. 全面测试：由于存在破坏性变更，应在测试环境中充分验证所有功能
2. 替代方案评估：对于移除的功能，寻找官方推荐的替代实现方式
3. 类型检查：特别注意数据类型变更可能导致的运行时错误
4. 枚举处理：更新代码中对字符串比较的处理，改为使用新的枚举类型

总结

Stripe PHP SDK v17.4.0-beta.1 版本通过清理废弃功能和引入新特性，使 API 更加规范和强大。这些变更虽然带来了一定的迁移成本，但长期来看将提高系统的稳定性和可维护性。开发者应仔细评估这些变更对现有系统的影响，并制定相应的升级计划。