README

包不再维护

尝试创建自己的包版本或使用Laravel Spark以获得完整的计划体验。

Laravel Chargeswarm

Laravel Chargeswarm是一个类似于Laravel Cashier的包，将帮助您与蜜蜂交朋友，并为您的应用程序打造一个出色的SaaS系统。此包提供了创建、更新、取消或恢复订阅的方法，还可以以优雅的方式处理webhooks！

此外，Chargeswarm还提供了支持处理可计数的资源。为此，建议使用Chargebee的元数据，带有或不带webhooks。

Chargebee的优势

Chargebee不是一个支付提供商。实际上，Chargebee是SaaS的管理者，而您可以使用任何类型的支付网关。与Stripe一样，您可以完全使用Chargebee的元数据来为您的计划执行信息。

此包还支持跟踪可计数功能的消耗。请继续阅读文档以了解更多信息。

从1.2.*升级到1.3.*

1.3版本使用配置文件的数组来检索环境变量，而不是“原始”传递。

在您的chargeswarm.php文件中，添加以下行

'site' => env('CHARGEBEE_SITE', ''),
'key' => env('CHARGEBEE_KEY', ''),
'gateway' => env('CHARGEBEE_GATEWAY', ''),

安装

安装包

$ composer require rennokki/chargeswarm

如果您的Laravel版本不支持包发现，请将此行添加到您的config/app.php文件中的providers数组中

Rennokki\Chargeswarm\ChargeswarmServiceProvider::class,

发布配置文件和迁移文件

$ php artisan vendor:publish

迁移数据库

$ php artisan migrate

将Billable特质添加到您的Eloquent模型中

use Rennokki\Chargeswarm\Traits\Billable;

class User extends Model {
    use Billable;
    ...
}

别忘了在您的.env文件中添加您的站点、API密钥以及网关选项

CHARGEBEE_SITE=site-test
CHARGEBEE_KEY=test_...
CHARGEBEE_GATEWAY=stripe

使用

如果您熟悉Cashier的源代码，那么在结构上这与Cashier很相似。要订阅您的用户，我们将使用订阅构建器。在其他任何情况下，我们将使用每个订阅中调用的方法。

任何字段都是可选的，除了plan_id参数和create方法。

$subscription = $user->subscription('plan_id')
                     ->withCoupon('coupon')
                     ->withAddons(['addon1', 'addon2'])
                     ->billingCycles(12)
                     ->withQuantity(3)
                     ->startsOn(...) // date or Carbon
                     ->onTrial() // overwrites the trial
                     ->trialEndsOn(...) // date or Carbon
                     ->withInvoiceNotes(...)
                     ->create('stripe_or_braintree_token');

$user->subscribed('plan_id'); // true
$user->activeSubscriptions()->count(); // 1

此外，如果您计划向客户添加更多数据，请使用withCustomerData()方法。所有字段都是可选的，可以设置为null

$user->subscription('plan_id')
     ->withCustomerData('email@google.com', 'John', 'Smith', 'Company Name')
     ->...
     ->create('token');

如果您也计划添加账单详情，这一项会稍微长一些。如果您不想使用某些字段，请将它们设置为null。

$user->subscription('plan_id')
     ->withCustomerData('email@google.com', 'John', 'Smith')
     ->withBilling(
        'email@google.com', 'John', 'Smith',
        'Street...', 'City', 'State',
        'Zip code', 'Country', 'Company name'
     )
     ->...
     ->create('token');

切换到其他计划

您可以使用订阅中调用的swap()方法简单地切换订阅的计划。如果订阅未激活，则返回false。

$subscription = $user->activeSubscriptions()->first();
$subscription = $subscription->swap('new_plan_id'); // updated subscription

计划切换正在进行中。如果您希望在当前期限结束后切换计划，可以将第二个参数设置为true。

$subscription = $subscription->swap('new_plan_id', true);

更改计划数量和账单周期

有两种方法可以更改计划数量和账单周期。

$subscription->changeQuantity(12);
$subscription->changeBillingCycles(12);

再次提醒，如果您计划在当前期限结束后进行更改，请将第二个参数传递为true。

更改试用结束日期和期限

如果您想更改试用日期或结束期限，您可以这样做，但前提是计划没有被取消。接受的参数可以是有效的日期字符串或Carbon实例。

$subscription->changeTrialEnd(Carbon::create(...));
$subscription->changeTermEnd(Carbon::create(...));

取消和恢复订阅

您可以将计划设置为试用状态。如果您计划取消订阅，可以使用cancel()方法。但是，如果订阅尚未过期（到期日期尚未过去），它将通过试用继续可用，但会被标记为已取消。

$subscripton->cancel();
$subscription->cancelled(); // true

稍后可以根据用户的决定继续订阅。

$subscription->resume();
$subscription->active(); // true
$subscription->onTrial(); // true

立即取消将取消订阅，无法再次恢复。

$subscription->cancelImmediately();
$subscription->active(); // false
$subscription->onTrial(); // false

然而，已取消的订阅可以被重新激活而不是恢复。

$subscription->reactivate();
$subscription->active(); // true

发票

发票是跟踪用户支出的一种合法方式。Chargeswarm允许您从订阅中获取发票。

$subscription->invoices(); // array with Chargebee_Invoice elements

由于发票是分页的，您可以指定一个$limit和一个$nextOffset。

$subscription->invoices($limit, $nextOffset);

您也可以通过调用账单模型中的方法来获取发票，但您还需要订阅ID。

$user->invoices($subscriptionId, $limit, $nextOffset);

发票解析可以通过一种方式完成，因此您也可以获取所需的$nextOffset。

$invoices = $user->invoices($subscriptionId, $limit, $nextOffset);

foreach ($invoices as $invoice) {
    $invoice = $invoice->invoice();

    ...
}

$nextPageOfInvoices = $user->invoices($subscriptionId, $limit, $invoices->nextOffset());

您还可以使用相同的方法直接从订阅中收集发票。

$invoices = $subscription->invoices($limit, $nextOffset);

foreach ($invoices as $invoice) {
    $invoice = $invoice->invoice();

    ...
}

$nextPageOfInvoices = $subscription->invoices($limit, $invoices->nextOffset());

请注意，有时偏移量不存在。在验证之前请确保它有效。

计划

要检索当前订阅的计划，您可以调用plan()。这允许您处理属于订阅的特定计划的数据。

$plan = $subscription->plan();
$metadata = $plan->metaData; // json object

Webhooks

每当发生任何事情时，Chargebee都会向配置的webhook发送一个POST请求。幸运的是，Chargeswarm可以为您做这件事，并且在webhook方面有很多支持。

要自动处理所有Chargebee的webhook，您只需要在您的routes/web.php或routes/api.php文件中声明一个这样的路由，并使用以下控制器：

Route::post('/webhooks/chargebee', '\Rennokki\Chargeswarm\Http\Controllers\ChargebeeWebhookController@handleWebhook');

另外，如果您启用了CSRF保护，请确保在您的VerifyCsrfToken.php文件中将其禁用。

protected $except = [
    'webhooks/chargebee',
];

预定义webhook

存在超过20个预定义的事件和webhook，但你可以使用Chargebee的任何事件来扩展它，因为语法友好，稍后将进行解释。每次webhook触发时，无论是什么事件，你都会收到一个执行变量$event->payload JSON对象的\Rennokki\Chargeswarm\Events\WebhookReceived事件。

此外，对于这些预定义的webhook，你还会接收到一个特定的事件。你可以在此处找到预定义的webhook及其配对事件列表。

不幸的是，对于你声明的任何其他类方法，除了之前定义的，你将不会收到事件。唯一触发的事件是\Rennokki\Chargeswarm\Events\WebhookReceived事件，该事件在接收到每个webhook时自动触发。

默认情况下，以下控制器方法会自动处理你的计划逻辑。我建议不要重写这些方法，除非你清楚你在做什么

• handleSubscriptionCancelled
• handlePaymentSucceeded
• handlePaymentRefunded
• handleSubscriptionDeleted
• handleSubscriptionRenewed

对于这四个，我建议监听它们的配对事件来处理你的逻辑。如果你想要实现任何其他处理器，你可以通过扩展控制器来自由地做，但请记住，与钩子相关的事件也会被触发。

扩展控制器

通过扩展你的控制器从Rennokki\Chargeswarm\Http\Controllers\ChargebeeWebhookController来定制webhook

use Rennokki\Chargeswarm\Http\Controllers\ChargebeeWebhookController;

class MyController extends ChargebeeWebhookController
{
    public function handleSubscriptionResumed($payload, $storedSubscription, $subscription, $plan)
    {
        // $payload is the JSON Object with the request
        // $storedSubscription is the stored subscription (if any)
        // $subscription is the subscription data (equivalent of $payload->content->subscription), if any
        // $plan is the plan object of the subscription
    }
}

扩展后，确保你使用的是具有相同@handleWebhook方法的控制器

Route::post('/webhooks/chargebee', 'MyController@handleWebhook');

定制webhook

你可以根据以下规则在你的控制器中定制任何类型的方法

MyController@handle{EventNameInStudlyCase}($payload, $storedSubscription, $subscription)

例如，由于card_added Chargebee事件既没有预定义也没有添加，你可以在你的控制器中简单地添加此方法

public function handleCardAdded($payload, $storedSubscription, $subscription, $plan)
{
    // your logic here
    // only $payload is not null.
    // The rest of the variables injected can be null or not, if the
    // subscription object exists
}

所有控制器方法和事件都接受4个参数：$payload、$storedSubscription、$subscription和$plan。

事件

如前所述，\Rennokki\Chargeswarm\Events\WebhookReceived事件会自动触发。除此之外，此处列出的每个方法都会自动触发配对事件。

如果你不熟悉事件，请查阅Laravel官方文档中的事件，该文档教你事件是什么，如何处理它们，更重要的是，如何监听它们。

所有事件都会将4个参数发送到它们的监听器：$payload、$storedSubscription、$subscription和$plan。你可以在你的监听器中使用事件实例来访问它们。

例如，每次调用@handleSubscriptionResumed时，我们可以监听\Rennokki\Chargeswarm\Events\SubscriptionResumed事件并实现我们的逻辑

class MyListener {
    public function handle(SubscriptionResumed $event)
    {
        // $event->payload
        // $event->storedSubscription
        // $event->subscription
        // $event->plan
    }
}

可计数功能

假设你运行自己的新闻简报应用程序，该应用程序使用SaaS向用户收费，并且你可以每月为用户提供5.000条新闻简报，他们可以发送。

在订阅或订阅续订后（可以通过监听\Rennokki\Chargeswarm\Events\SubscriptionRenewed事件来完成），你可以在你的逻辑中简单地调用createUsage()，例如

public function handle()
{
    $subscription = $event->storedSubscription;
    $subscription->createUsage('monthly.emails', 5000);
    ...
}

稍后，你可以在整个应用程序中通过调用订阅内的方法来消耗或撤销消耗

$subscription->consume('monthly.emails', 10); // sent 10 mails

在错误情况下，撤销效果可能很有用。例如，当邮件服务器失败，但你的应用程序没有时。要撤销，你可以撤销消耗

$subscription->unconsume('monthly.emails', 10); // undo-ed 10 from the quota

消费或未消费不存在的、未设置的用法将返回false。另外，如果消费的量超过剩余量，也会返回false。

$subscription->consume('daily.emails', 10); // false

取消消费不会低于零。如果您取消消费的量超过已使用的量，不会发生溢出，并且used属性将被设置为0。

如果您计划接收所有用法，可以通过在订阅中调用usages()关系来实现。

$usages = $subscription->usages()->get();