README

October CMS 插件，使用 Laravel Cashier 处理 Stripe 和 Braintree 付款。

此插件通过 Rainlab.User 集成 Laravel Cashier 到 October CMS。您可以对 Rainlab 用户执行“一次性”收费或订阅他们的 Stripe 计划。

插件预装了简单的 Stripe Elements 表单和发票列表组件。所有 Laravel Cashier 功能均可用。为 October CMS 版本的 Cashier 添加了易于定制的发票视图和一些有用的事件。

v2.0.0 版本的重大更改

此插件在 2.0.0 版本中，Laravel Cashier 已更新到 9.0 版本。这使得插件与基于 Laravel 5 和 Laravel 6 的 October 版本兼容。

通过此更新，解决了插件中的一些架构问题，这些问题可能会根据您的设置引入破坏性更改

• 已完全删除 \OFFLINE\Cashier\Models\User。请使用 \RainLab\User\Models\User 替代。
• 由于自定义用户模型已删除，您必须确保将可能指向旧模型类的任何关系移动到 RainLab.User 模型。
• 将 stripeelementsform/script.js 部分重命名为 script.htm。如果您覆盖此部分，请确保将覆盖的局部视图也重命名。

安装

在 config/services.php 中，将 stripe 配置替换为以下内容

'stripe' => [
   'model'   => \RainLab\User\Models\User::class,
   'key'     => env('STRIPE_KEY'),
   'secret'  => env('STRIPE_SECRET'),
   'webhook' => [
       'url'     => '/stripe/webhook',
       'handler' => '\OFFLINE\Cashier\Classes\WebhookController@handleWebhook'
   ]
],

现在将您的 STRIPE_KEY 和 STRIPE_SECRET 添加到您的 .env 文件中。

STRIPE_KEY=pk_test_XXXXXXXXXXXXXXXXXXXXXX
STRIPE_SECRET=sk_test_XXXXXXXXXXXXXXXXXXXXXX

如果您想使用 StripeElementsForm 组件，请确保包含 October CMS 框架扩展。

完成！

处理 Stripe Webhooks

要接收 Stripe Webhooks，请配置 Stripe 将它们发送到 https://<your-site>/stripe/webhook（您可以通过 services.stripe.webhook.url 配置条目更改此 URL）。

在失败的费用上取消订阅由 Laravel Cashier 默认处理。如果您希望响应其他 Webhooks，请监听通用的 offline.cashier::stripe.webhook.received 事件，该事件为所有传入 Webhooks 触发，或创建特定 Webhook 事件的监听器，例如 offline.cashier::stripe.webhook.invoice.payment_succeeded（使用格式 offline.cashier::stripe.webhook.<stripe_webhook_type>）。所有事件监听器都接收一个 $payload 和一个 $request 变量。

或者，您可以在 services.stripe.webhook.handler 配置条目中设置自己的 Webhook 处理器控制器，并自行实现所有内容。

Event::listen('offline.cashier::stripe.webhook.invoice.payment_succeeded', function ($payload, $request) {
    $subscription = $payload['data']['object']['subscription'];
    
    $user = \RainLab\User\Models\User::fromSubscriptionId($subscription);

    $user->payment_succeeded_at = \Carbon\Carbon::now();
    $user->save();

    logger()->debug('Received payment', compact('user', 'subscription'));
});

组件

InvoicesList

此组件列出特定用户账户的所有发票。

使用您自己的数字格式化程序

如果您希望完全控制发票中金额的格式，您有监听 offline.cashier::format.amount 事件并自行格式化金额的可能性。

Event::listen('offline.cashier::format.amount', function ($amount) {
    return number_format((float)$amount / 100, 2, '.', "'") . ' CHF';
});

自定义发票模板

发票模板存储在 views/receipt.htm 中。您可以将此模板复制并存储在自己的插件或主题中。要为发票设置自己的局部视图，请在 Cashier 的后端设置中设置新的视图路径。

您可以通过在后台设置表单中的重复器向发票传递附加数据。您指定的每个变量都将可在模板中使用。如果您想在发票上显示电话号码或电子邮件地址，这很有用。

属性

userId

指定要加载发票的用户的ID。如果您留空，则使用当前登录的用户。

includePending

是否将待处理发票包含在列表中。

loadingText

出于性能考虑，发票列表异步加载。在加载期间，此字符串将显示给用户（默认为 正在加载发票...）。

StripeElementsForm

此组件为您提供了一个简单的起点，以将 Stripe Elements 集成到您的网站中。

只需将组件 添加到您的页面，您就会看到一个简单的信用卡输入表单。

令牌处理程序回调

要扩展接收生成的Stripe令牌的默认 stripeTokenHandler 函数，将 plugins/offline/cashier/components/stripeelementsform/tokenHandler.htm 复制到 themes/<yourtheme>/partials/stripeElementsForms/tokenHandler.htm，并根据需要进行修改。

处理表单提交

当用户提交表单时，将触发 offline.cashier::stripeElementForm.submit 事件。您可以在自己的插件中 监听此事件 并存储支付信息以供以后使用，向用户收费或创建订阅。

有关如何使用生成的 stripeToken 向用户收费或订阅的更多信息，请参阅 Laravel Cashier 文档。

以下是一个示例代码

public function boot()
{
    parent::boot();

    Event::listen('offline.cashier::stripeElementForm.submit', function ($post) {
        $token = $post['token']['id'] ?? null;
        if ( ! $token) {
            throw new \RuntimeException('Stripe token is missing!');
        }

        $user = \Auth::getUser();
        $user->newSubscription('main', 'users-selected-plan-id')->create($token);

        return [
            'redirect' => \Url::to('thank-you')
        ];
    });
}

属性

includeStripeJs

此属性将 https://js.stripe.com/v3/ 代码包含到您的页面中。如果您在一个页面上有多个组件实例，请确保仅在其中一个上启用此属性。如果您全局包含代码，则可以安全地取消选中此属性。

includeCss

此属性将组件的 styles.htm 部分包含到组件中（您可以将它覆盖）。如果您定义了Stripe Elements样式

submitButtonLabel

此属性指定表单提交期间的提交按钮标签。

NeedsSubscription

将此组件放置在任何只有有效订阅用户才能访问的页面上。没有有效订阅的用户将被重定向到您定义的页面。

扩展订阅逻辑

如果您需要扩展订阅逻辑，您可以监听 offline.cashier::subscription.check 事件。该事件接收 user 和 NeedsSubscription 组件实例。

如果您从任何事件监听器返回 true，则用户将被允许查看页面。如果您从任何事件监听器返回 false，则用户将被重定向。请注意，任何 true 值都具有优先权。如果您不返回任何 boolean 值，则检查将回退到Laravel Cashier的 subscribed 方法。

扩展订阅逻辑

如果您需要扩展订阅逻辑，您可以监听 offline.cashier::subscription.check 事件。该事件接收 user 和 NeedsSubscription 组件实例。

如果您从任何事件监听器返回 true，则用户将被允许查看页面。如果您从任何事件监听器返回 false，则用户将被重定向。请注意，任何 true 值都具有优先权。如果您不返回任何 boolean 值，则检查将回退到Laravel Cashier的 subscribed 方法。

 Event::listen('offline.cashier::subscription.check', function ($user, $component) {
    if ( ! $user) {
        return false;
    }

    if (isBanned($user)) {
        return false;
    }

    return $user->subscribed($component->property('subscription'));
});

属性

redirect

未经授权的用户将被重定向到此路由。

subscription

用户需要访问页面的订阅名称。默认为 main。