logo

配置

简介

在以下文档中,我们将讨论如何在使用 Paddle 支付提供商时配置 Laravel Spark 安装。所有 Spark 的配置选项都位于应用程序的 config/spark.php 配置文件中。

Paddle 计费

Spark Paddle 5.x 支持 Paddle 计费。如果您仍在使用 Paddle Classic,则应继续使用 Spark Paddle 4.x

Paddle 配置

当然,要使用 Paddle 作为 Laravel Spark 应用程序的支付提供商,您必须拥有一个有效的 Paddle 帐户在开发应用程序时,您可以使用 Paddle 沙盒

环境变量

接下来,您应该配置 Spark 访问您的 Paddle 帐户所需的应用程序环境变量。这些变量应该放在应用程序的 .env 环境文件中。

当然,您应该调整变量的值以对应您自己的 Paddle 帐户凭据。此外,如果您使用的是 Paddle 的沙盒环境,则应将 PADDLE_SANDBOX 变量设置为 true。您的 Paddle API 凭据和 Webhook 密钥可在您的 Paddle 帐户仪表板中通过“开发者工具”部分的“身份验证”和“通知”获得。

bash
CASHIER_CURRENCY=USD
CASHIER_CURRENCY_LOCALE=en
PADDLE_SANDBOX=true
PADDLE_CLIENT_SIDE_TOKEN=your-paddle-client-side-token
PADDLE_API_KEY=your-paddle-api-key
PADDLE_WEBHOOK_SECRET=pdl_ntfset_xxx

配置语言环境

为了使用除 en 以外的语言环境,请确保 ext-intl PHP 扩展已安装并在您的服务器上配置。

Paddle Webhooks

此外,您的 Spark 驱动的应用程序需要接收来自 Paddle 的 Webhook,以便将应用程序的计费和订阅数据与 Paddle 的数据同步。在您的 Paddle 仪表板的“通知”管理面板中,您应该将 Paddle 配置为将 Webhook 警报发送到应用程序的 /paddle/webhook URI。您应该为以下事件启用 Webhook 警报

  • 客户更新
  • 交易完成
  • 交易更新
  • 订阅创建
  • 订阅更新
  • 订阅暂停
  • 订阅取消

Webhook 和本地开发

为了使 Paddle 能够在本地开发期间向您的应用程序发送 Webhook,您需要通过网站共享服务(例如 NgrokExpose)公开您的应用程序。如果您使用 Laravel Sail 在本地开发应用程序,您可以使用 Sail 的 网站共享命令

配置计费项

Spark 允许您定义应用程序将管理的计费模型类型。最常见的是,应用程序会向单个用户收取每月和每年的订阅计划费用。但是,您的应用程序可以选择收取其他类型的模型费用,例如团队、组织、乐队等。Spark 的 Paddle 版本目前仅支持每个应用程序一个计费模型(团队、用户等)。

您可以在应用程序的 spark 配置文件中的 billables 数组中定义您的计费模型。默认情况下,此数组包含 App\Models\User 模型的条目。

在继续之前,您应该确保与您的计费模型相对应的模型类正在使用 Spark\Billable 特性。此外,您的计费模型的主键应为名为 idinteger 列。

php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Spark\Billable;

class User extends Authenticatable
{
    use Billable, HasFactory, Notifiable;
}

计费项别名

您可能已经注意到,billables 配置数组中的每个条目都由一个“别名”键控,该别名是计费模型类的简写形式。此别名可以在访问 Spark 客户账单门户时使用,例如 https://example.com/billing/userhttps://example.com/billing/team

计费项解析

当您安装 Laravel Spark 时,会为您创建一个 App\Providers\SparkServiceProvider 类。在此服务提供者中,您将找到一个回调,Spark 使用该回调在访问 Spark 账单门户时解析计费模型实例。默认情况下,此回调只返回当前经过身份验证的用户,这是大多数使用 Laravel Spark 的应用程序所需的行為。

php
use App\Models\User;
use Illuminate\Http\Request;
use Spark\Spark;

Spark::billable(User::class)->resolve(function (Request $request) {
    return $request->user();
});

但是,如果您的应用程序没有对单个用户进行计费,您可能需要调整此回调。例如,如果您的应用程序提供团队计费而不是用户计费,您可能会像这样自定义回调

php
use App\Models\Team;
use Illuminate\Http\Request;
use Spark\Spark;

Spark::billable(Team::class)->resolve(function (Request $request) {
    return $request->user()->currentTeam;
});

计费项授权

接下来,让我们检查 Spark 将用来确定您的应用程序的当前经过身份验证的用户是否有权查看特定计费模型的账单门户的授权回调。

当您安装 Laravel Spark 时,会为您创建一个 App\Providers\SparkServiceProvider 类。在这个服务提供者中,您会找到用于确定给定用户是否有权查看 App\Models\User 可计费类的计费门户的授权回调定义。当然,如果您的应用程序没有对用户进行计费,您应该更新可计费类和授权回调逻辑以适应您的应用程序需求。默认情况下,Spark 只会验证当前已认证的用户只能管理其自身的计费设置。

php
use App\Models\User;
use Illuminate\Http\Request;
use Spark\Spark;

Spark::billable(User::class)->authorize(function (User $billable, Request $request) {
    return $request->user() &&
           $request->user()->id == $billable->id;
});

如果授权回调返回 true,则当前已认证的用户将被授权查看计费门户并管理给定 $billable 模型的计费设置。如果回调返回 false,则访问计费门户的请求将被拒绝。

您可以根据自己的应用程序需求自由定制 authorize 回调。例如,如果您的应用程序对团队而不是单个用户进行计费,您可能会像这样更新回调

php
use App\Models\Team;
use Illuminate\Http\Request;
use Spark\Spark;

Spark::billable(Team::class)->authorize(function (Team $billable, Request $request) {
    return $request->user() &&
           $request->user()->ownsTeam($billable);
});

可计费名称和电子邮件地址

默认情况下,Spark 将使用您的可计费模型的 nameemail 属性作为与它为模型创建的 Paddle 客户记录关联的名称和电子邮件地址。如果您想指定另一个属性来代替,您可以在可计费模型上定义 paddleNamepaddleEmail 方法

php
/**
 * Get the name that should be associated with the Paddle customer.
 */
public function paddleName(): string|null
{
    return $this->name;
}

/**
 * Get the email address that should be associated with the Paddle customer.
 */
public function paddleEmail(): string|null
{
    return $this->email;
}

定义订阅计划

正如我们之前讨论的,Spark 允许您定义您的应用程序将管理的可计费模型类型。此可计费模型在应用程序的 config/spark.php 配置文件中的 billables 数组中定义

billables 数组中的可计费配置包含一个 plans 数组。在这个数组中,您可以配置您的应用程序向该特定可计费类型提供的每个计费计划。monthly_idyearly_id 标识符应与您 Paddle 帐户仪表板中订阅计划关联的计划标识符相对应:

php
use App\Models\User;

'billables' => [
    'user' => [
        'model' => User::class,
        'trial_days' => 5,
        'plans' => [
            [
                'name' => 'Standard',
                'short_description' => 'This is a short, human friendly description of the plan.',
                'monthly_id' => env('SPARK_STANDARD_MONTHLY_PLAN', 'pri_1000'),
                'yearly_id' => env('SPARK_STANDARD_YEARLY_PLAN', 'pri_1001'),
                'features' => [
                    'Feature 1',
                    'Feature 2',
                    'Feature 3',
                ],
            ],
        ],
    ],
]

如果您的订阅计划只提供每月账单周期,您可以在计划配置中省略yearly_id标识符。同样,如果您的计划只提供每年账单周期,您可以在计划配置中省略monthly_id标识符。

此外,您可以自由提供计划的简短描述和与计划相关的功能列表。此信息将在 Spark 账单门户中显示。

如果您想指示某些功能**不可用**于特定计划,您可以在其前面加上--。这些功能将使用删除线文本显示。

php
'features' => [
    'Feature 1',
    'Feature 2',
    'Feature 3',
    '--No Batch Approve',
    '--No Additional Sources',
],

Disabled features example

访问账单门户

配置完 Spark 安装后,您可以在/billing URI 访问应用程序的账单门户。因此,如果您的应用程序在localhost上运行,您可以在http://localhost/billing访问应用程序的账单门户。

当然,您可以从应用程序的仪表板链接到账单门户,无论您认为合适。

html
<a href="/billing">
    Manage Subscription
</a>

许多应用程序在结账时会显示账单条款和条件。Spark 允许您在应用程序的账单门户中轻松地执行相同的操作。首先,在应用程序的config/spark.php配置文件中添加一个terms_url配置值。

php
'terms_url' => '/terms'

添加后,Spark 将在账单门户中显示指向/terms的链接。