Stripe-PHP 库中支付链接的 line_items 属性获取问题解析

在使用 Stripe-PHP 库处理支付链接时，开发者可能会遇到一个常见问题：通过 API 检索到的支付链接对象中，line_items 属性显示为 null。这个问题涉及到 Stripe API 的一个重要设计特性——可包含属性（includable properties）。

问题现象

当开发者创建支付链接时，通常会指定 line_items 参数来定义支付项目。例如：

$link = $stripe->paymentLinks->create([
    'line_items' => [
        [
            'price' => $price->id,
            'quantity' => 1
        ],
    ]
]);

然而，在后续通过支付链接ID检索该对象时：

$plink = $stripe->paymentLinks->retrieve($paymentLinkId);

发现 $plink->line_items 为 null，导致调用 toJSON() 方法时出现错误。

技术原理

这个问题源于 Stripe API 的优化设计。为了减少不必要的数据传输和提高性能，Stripe API 默认不会返回所有可能的属性。line_items 就是这样一个"可包含属性"（includable property），它需要开发者明确请求才会在响应中包含。

解决方案

正确的做法是使用 Stripe 的"扩展"（expand）功能，明确请求包含 line_items 属性：

$plink = $stripe->paymentLinks->retrieve(
    $paymentLinkId,
    ['expand' => ['line_items']]
);

同样地，对于结账会话（checkout session）对象，也需要使用相同的技术：

$session = $stripe->checkout->sessions->retrieve(
    $sessionId,
    ['expand' => ['line_items']]
);

最佳实践

1. 预先规划数据需求：在编写代码前，明确需要哪些属性，特别是那些标记为可包含的属性。

2. 批量扩展：可以一次性请求多个可包含属性，例如：

   ['expand' => ['line_items', 'customer', 'payment_intent']]
   

3. 性能考量：虽然扩展功能很强大，但不应过度使用。只请求实际需要的属性，以避免不必要的数据传输和处理开销。

4. 错误处理：始终对可能的null值进行防御性编程，即使使用了扩展功能。

深入理解

Stripe API 的这种设计模式在REST API中很常见，它遵循了"按需获取"的原则。这种设计有以下几个优点：

1. 减少了网络传输的数据量
2. 提高了API响应速度
3. 降低了服务器处理负担
4. 让客户端可以精确控制所需数据

对于PHP开发者来说，理解这一设计模式非常重要，因为它不仅存在于Stripe API中，也是现代API设计的常见实践。

通过正确使用扩展功能，开发者可以灵活地获取所需数据，同时保持应用程序的高效运行。这一技术同样适用于Stripe API中的其他资源类型，如订单、发票等，它们都可能包含需要显式请求的可包含属性。