README

======

Cashew允许您以最简单的方式集成Stripe订阅计费。我们处理订阅计费中边缘情况的维护工作，同时提供一个易于使用的API进行消费。

Cashew与Laravel 4.2和Laravel 5兼容。

安装

要安装此包，请在您的composer.json中包含以下内容。

"owlgrin/cashew": "dev-master"

然后在您的app.php中包含以下服务提供者。

...
'Owlgrin\Cashew\CashewServiceProvider'
...

然后在同一app.php文件中的外观列表中添加以下内容，以便轻松使用此包。

...
'Cashew' => 'Owlgrin\Cashew\CashewFacade',
...

最后，发布配置。

php artisan config:publish owlgrin/cashew

用法

Cashew通过将用户的所有信息映射到您应用程序中该用户的主键来实现。要设置一切，您需要迁移几个表，可以使用以下命令完成。

php artisan migration:publish --package owlgrin/cashew

创建新的订阅

要创建新的订阅，您可以简单地将用户标识符（通常是主键）与一个包含键 'card'、'email' 等（所有都是可选的）的关联数组一起传递。

Cashew::create(Auth::user()->id, array('trial_end' => 'now', 'coupon' => 'earlybird'));

现在，一旦为用户存在一个订阅，您可以使用user方法在每个请求中注册它。（可能是在用户登录时。）

if(Auth::attempt($username, $password))
{
	Cashew::user(Auth::user()->id);
}

一旦设置，您可以使用以下方法访问订阅的不同方法。

更新卡详情

您可以使用card方法更新卡详情。

Cashew::card('tok_o48H37h8eh');

如果您在更新卡的同时想更新其他详情，如'trial_end'，您可以通过第二个参数完成。

Cashew::card('tok_o48H37h8eh', array('trial_end' => 'now'));

应用优惠券

您可以使用'coupon'方法为一个订阅应用优惠券。

Cashew::coupon('20OFF');

更改计划

交换订阅计费中的计划不是一件容易的事情。有许多事情需要考虑。我们为您做了这件事，您只需像这样更改订阅的计划。

Cashew::toPlan('premium');

默认情况下，Cashew会按比例计算计划变更，但您可以通过第二个参数完成。

Cashew::toPlan('premium', false); // no prorate

如果更改计划时订阅中还有剩余的试用期，默认情况下，我们将保持试用期。您可以通过第三个参数强制Cashew立即停止试用期。

Cashew::toPlan('premium', true, false); // stop trial period immediately

处理数量

您可能需要按每个单元计费您的用户所使用的服务。例如，您可能按'每个用户'计费。Cashew使得处理数量变得容易。

您可以使用'increment'方法增加数量。

Cashew::increment();

类似地，'decrement'方法允许您减少一个数量。

Cashew::decrement();

您也可以将这些方法作为第一个参数传递数量，以覆盖默认值一。以下代码增加了三个数量。

Cashew::increment(3);

同样适用于'decrement'方法。

更新订阅

尽管我们已经有像toPlan、coupon、card这样的辅助方法，允许您轻松地进行特定更新。但如果你想要使用原始的更新方法自己更新你的订阅，你可以使用update方法。

Cashew::update(array('plan' => 'new-plan', 'coupon' => 'yipee'));

该方法只接受一个参数 - 一个关联数组 - 包含所有Strip API接受的选项。

取消订阅

您可以使用cancel方法取消用户的订阅。

Cashew::cancel();

用户在您重新激活其订阅之前不会收费。然而，此方法将在当前订阅期结束时取消订阅。因此，用户现在将处于宽限期。

如果您想立即取消订阅，请使用cancelNow方法。

Cashew::cancelNow();

重新激活订阅

在每项订阅申请中，订阅都会过期。通常，这些是由于临时原因，如试用期结束，稍后需要重新激活。Cashew提供了resume方法，以便轻松完成此操作。重新激活订阅有许多注意事项，而Cashew会为您处理所有这些。

Cashew::resume();

这只是一个最简单的用法。您在重新激活时可能需要传递一些选项，这些选项可以像这样作为关联数组传递。

Cashew::resume(array('plan' => 'premium', 'quantity' => 3));

许多时候，您需要在试用期结束后，在用户请求后重新激活订阅。通常，您将要求用户提供卡信息以重新激活订阅。您可以将卡详细信息作为resume方法的第二个参数传递。

Cashew::resume(array('plan' => 'premium'), 'tok_dff38rm347gBYF7');

即将过期的订阅

您有时可能根据您的业务领域手动使订阅过期。例如，您可能有一个cron作业正在运行，该作业将使超出试用期的订阅过期。对于此类情况，您可以使用expire方法。

Cashew::expire();

有时，您可能希望根据用户的Stripe客户ID使您的用户账户过期。那么，expireCustomer方法正是为此目的。

Cashew::expireCustomer($customerId);

检查用户是否提供了卡

您可能经营的业务需要或不需要提前索要卡。如果您想检查用户是否与其订阅相关联了卡，您可以使用hasCard方法。

if($user->birthday == Carbon\Carbon::today() && Cashew::hasCard())
{
	// send birthday cake
}

获取用户的发票

始终建议您在用户的账单部分显示用户的支付历史记录。为此，'invoices'方法将为您获取用户以前所有已支付的发票。

Cashew::invoices();

默认情况下，它将获取保存在您数据库中的本地发票详情。但，您可能需要每个发票的更多信息，因此希望通过API获取详细信息。为此，将此方法的第一参数作为false传递。

// fetch from API
Cashew::invoices(false);

此外，默认情况下，它将获取最新的10张发票。如果您想获取所有发票，请将数字作为第二个参数传递。

// fetch 25 invoices
Cashew::invoices(true, 25);

获取用户的下一张发票

始终建议您向用户显示即将到来的发票，这样他们就不会对账单有任何意外。

Cashew提供了一个方便的nextInvoice方法来获取订阅的下一张发票。

Cashew::nextInvoice();

获取订阅状态

您可能需要根据用户的订阅状态执行不同的操作。为了让您轻松找到订阅状态，您可以使用status方法。

if(Cashew::status() === 'active')
{
	$user->sendGift();
}

辅助状态确定器

Cashew为您提供了一些辅助方法来确定用户的订阅。

活动

检查用户是否有活动订阅。活动订阅意味着用户被认为是有偿客户。确切地说，如果以下任一为真，则该方法返回true

- is he/she on trial?
- is he/she on grace period?
- does he/she have an active subscription?

if( ! Cashew::active())
{
	Redirect::to(...);
}

已订阅

有时，仅检查用户是否活跃是不够的。您可能需要检查用户是否具有活动订阅。在这种情况下，subscribed方法非常有用。

if( ! Cashew::subscribed())
{
	Redirect::to('billing.plans');
}

不活跃

还有另一个辅助方法可以确定用户是否有不活跃的订阅。

if(Cashew::inactive())
{
	Offer::send(...);
}

有卡吗？

有时，您可能不仅想知道用户是否活跃，还想具体知道用户是否提供了他的卡详细信息。

if(Cashew::hasCard())
{
	Redirect::to(...);
}

试用中

onTrial方法允许您快速判断用户是否处于试用状态。

if(Cashew::onTrial())
{
	// send them coupon code
}

宽限期

onGrace 方法可以帮助你轻松判断用户是否处于宽限期。宽限期是指从取消订阅到当前订阅期结束的这段时间。例如，如果用户的订阅原定于11月30日结束，而他于11月15日取消了订阅，那么从11月16日到11月30日，他处于宽限期。

if(Cashew::onGrace())
{
	// show alert
}

已过期

要确定用户是否已过期，你可以使用 expired 方法。

if(Cashew::expired())
{
	Redirect::to('billing');
}

已取消

要快速检查用户是否已取消订阅，可以使用 canceled 方法。

if(Cashew::canceled())
{
	Redirect::to('billing.upgrade');
}

套餐

如果你为用户提供多个套餐，你可能需要检查某人是否处于特定的套餐中。你可以使用 onPlan 方法来实现。

if(Cashew::onPlan('gold'))
{
	$allowReferral = true;
}

Webhook控制器

Cashew自带一个可工作的Webhook控制器。默认情况下，它处理以下三个事件：

订阅更新
支付成功
支付失败

要使用控制器，你需要注册一个类似的路由

Route::post('hooks/stripe', 'Owlgrin\Cashew\CashewHookController@handle');

完成必要操作后，它会触发一个事件，你可以监听并扩展这些事件的功能。

订阅更新会触发一个名为 cashew.subscription.update 的事件，其中包含 user_id 和 subscription 对象。
支付成功会触发一个名为 cashew.payment.success 的事件，其中包含 user_id 和 invoice 对象。
支付成功会触发一个名为 cashew.payment.fail 的事件，其中包含 user_id 和 invoice 对象。

默认情况下，我们会负责更新数据库中的数据，但你可以通过监听这些事件来扩展功能，例如发送电子邮件收据，如下所示

Event::listen('cashew.payment.success', function($id, $invoice)
{
	User::find($id)->sendReceipt($invoice);
});

宽限期结束时过期用户

Cashew当然可以在支付失败的情况下使用户过期，但在宽限期结束时，你需要手动使用户过期。为此，Cashew为你提供了一个Artisan命令，你可以将其放入每日cron作业中，这将为你完成工作。你可以在终端中这样调用命令

php artisan cashew:expire

异常

Cashew将这些Stripe异常包装在这些异常中

Owlgrin\Cashew\Exceptions\CardException - 处理卡失败时。
Owlgrin\Cashew\Exceptions\InputException - 数据未正确传递时。
Owlgrin\Cashew\Exceptions\NetworkException - 无法连接到Stripe时。

扩展Cashew

整个包都是接口驱动的，这意味着你可以通过创建接口的自定义实现来轻松替换实现。

以下是可以使用你自己的版本扩展的接口。

Owlgrin\Cashew\Card\Card
Owlgrin\Cashew\Customer\Customer
Owlgrin\Cashew\Event\Event
Owlgrin\Cashew\Gateway\Gateway
Owlgrin\Cashew\Hook\Hook
Owlgrin\Cashew\Invoice\Invoice
Owlgrin\Cashew\Storage\Storage
Owlgrin\Cashew\Subscription\Subscription

为Cashew做出贡献

贡献指南即将推出。

许可证

Cashew是一个开源软件，许可协议为MIT许可

owlgrin / cashew

维护者

详细信息