README

Yii 2 的 Cashier 扩展

本扩展是 Laravel Cashier 包的移植版本，链接为：Laravel's Cashier package

支持我们

您的业务依赖于我们的贡献吗？通过 Patreon 联系我们并支持我们。所有承诺将用于维护工作和开发新功能。

安装

安装此扩展的首选方式是通过 composer。

运行以下命令：

php composer.phar require --prefer-dist inquid/yii2-cashier "*"

或

"inquid/yii2-cashier": "*"

将以下内容添加到您的 composer.json 文件的 require 部分：

Stripe 配置

本项目受到 Laravel Cashier 包的启发，并试图将它的简洁性带到 Yii 框架中。

数据库迁移

在使用 Cashier 之前，我们还需要准备数据库。

$tableOptions = null;

if ($this->db->driverName === 'mysql') {
    $tableOptions = 'CHARACTER SET utf8 COLLATE utf8_unicode_ci ENGINE=InnoDB';
}

$this->createTable('subscriptions', [
    'id' => $this->primaryKey(),
    'user_id' => $this->integer()->notNull(),
    'name' => $this->string()->notNull(),
    'stripe_id' => $this->string()->notNull(),
    'stripe_plan' => $this->string()->notNull(),
    'quantity' => $this->integer()->notNull(),
    'trial_ends_at' => $this->timestamp()->null(),
    'ends_at' => $this->timestamp()->null(),
    'created_at' => $this->timestamp()->null(),
    'updated_at' => $this->timestamp()->null()
], $tableOptions);

$this->addColumn('users', 'stripe_id', $this->string());
$this->addColumn('users', 'card_brand', $this->string());
$this->addColumn('users', 'card_last_four', $this->string());
$this->addColumn('users', 'trial_ends_at', $this->timestamp()->null());

您也可以通过以下命令应用迁移：

php yii migrate --migrationPath=@vendor/inquid/yii2-cashier/migrations

模型设置

接下来，将 Billable 特性添加到您的 User 模型定义中

use inquid\cashier\Billable;

class User extends ActiveRecord implements IdentityInterface
{
    use Billable;
}

提供商密钥

接下来，您应该配置配置文件中的 params 部分

'params' => [
        .....
        'stripe' => [
            'apiKey' => 'Your Secret Api Key'
        ],
    ],

$user = User::findOne(1);

$user->subscription('main')->incrementQuantity();

// Add five to the subscription's current quantity...
$user->subscription('main')->incrementQuantity(5);

$user->subscription('main')->decrementQuantity();

// Subtract five to the subscription's current quantity...
$user->subscription('main')->decrementQuantity(5);

或者，您可以使用updateQuantity方法设置特定的数量

$user->subscription('main')->updateQuantity(10);

有关订阅数量的更多信息，请参阅Stripe文档。

订阅税费

使用Cashier，很容易提供发送到Stripe的tax_percent值。要指定用户在订阅上支付的税率，请在您的账单模型上实现taxPercentage方法，并返回一个介于0到100之间的数值，最多两位小数。

public function taxPercentage() {
    return 20;
}

这使您能够根据模型应用税率，这可能对跨越多个国家的用户基础有帮助。

取消订阅

要取消订阅，只需在用户的订阅上调用cancel方法

$user->subscription('main')->cancel();

当订阅被取消时，Cashier将自动设置您数据库中的endAt列。该列用于确定何时开始返回false的已订阅方法。例如，如果客户在3月1日取消订阅，但订阅原定于3月5日结束，则已订阅方法将继续返回true，直到3月5日。

您可以使用onGracePeriod方法确定用户是否已取消订阅但仍处于“宽限期”

if ($user->subscription('main')->onGracePeriod()) {
    //
}

恢复订阅

如果用户已取消订阅并且您希望恢复它，请使用resume方法。用户必须仍在他们的宽限期内才能恢复订阅

$user->subscription('main')->resume();

如果用户取消订阅然后在该订阅完全过期之前恢复该订阅，他们不会立即被收费。相反，他们的订阅将简单地被重新激活，并且他们将根据原始的账单周期收费

订阅试用期

信用卡预付费

如果您想在收集预付费支付方式信息的同时向客户提供试用期，您应该在创建订阅时使用trialDays方法

$user = User::findOne(1);

$user->newSubscription('main', 'monthly')
            ->trialDays(10)
            ->create($creditCardToken);

此方法将在数据库中的订阅记录上设置试用期结束日期，并指示Stripe在此日期之后开始向客户收费

如果客户在试用期结束日期之前未取消订阅，则在试用期结束后他们将立即被收费。因此，您应该通知您的用户他们的试用期结束日期。您可以使用用户实例的onTrial方法或订阅实例的onTrial方法来确定用户是否处于试用期。以下两个示例在目的上基本相同

if ($user->onTrial('main')) {
    //
}

if ($user->subscription('main')->onTrial()) {
    //
}

无需 upfront 信用卡

如果您希望提供无需 upfront 收集用户支付方式信息的试用期，您只需将用户记录中的 trialEndAt 列设置为期望的试用期结束日期即可。例如，这通常在用户注册时完成

$user = new User([
    // Populate other user properties...
    'trial_ends_at' => Carbon::now()->addDays(10),
]);

收银员将此类试用期称为“通用试用期”，因为它不与任何现有订阅相关联。如果当前日期尚未超过 trialEndAt 的值，则 User 实例上的 onTrial 方法将返回 true

if ($user->onTrial()) {
    // User is within their trial period...
}

如果您想确切知道用户是否处于“通用”试用期且尚未创建实际订阅，您也可以使用 onGenericTrial 方法

if ($user->onGenericTrial()) {
    // User is within their "generic" trial period...
}

一旦您准备好为用户创建实际订阅，您可以像往常一样使用 newSubscription 方法

$user = User::findOne(1);

$user->newSubscription('main', 'monthly')->create($creditCardToken);

处理 Stripe Webhooks

失败的订阅

只需将 WebhookController 添加到您的配置文件中的 controllerMap 即可

'controllerMap' => [
        //Stripe webhook
        'webhook' => 'inquid\cashier\controllers\WebhookController',
    ],

这样就完成了！失败的付款将被捕获并由控制器处理。当 Stripe 确定订阅失败（通常在三次失败的付款尝试之后）时，控制器将取消客户的订阅。别忘了：您需要在 Stripe 控制面板设置中配置 webhook URI，例如：在您的 Stripe 控制面板设置中配置 yoursite.com/webhook/handle-webhook

单一费用

简单费用

当使用 Stripe 时，charge 方法接受您希望以应用程序使用的货币的最小分母进行收费的金额。

如果您想对已订阅客户的信用卡进行一次性收费，您可以在账单模型实例上使用 charge 方法。

// Stripe Accepts Charges In Cents...
$user->charge(100);

charge 方法接受一个数组作为其第二个参数，允许您将任何选项传递给底层的 Stripe 收费创建。

$user->charge(100, [
    'custom_option' => $value,
]);

如果收费失败，charge 方法将抛出异常。如果收费成功，方法将返回完整的 Stripe 响应。

try {
    $response = $user->charge(100);
} catch (Exception $e) {
    //
}

带有发票的收费

有时您可能需要一次性收费，同时还需要为该收费生成发票，以便您可以向客户提供 PDF 发票。invoiceFor 方法可以让您做到这一点。例如，让我们向客户开具 5.00 美元的“一次性费用”发票。

// Stripe Accepts Charges In Cents...

$user->invoiceFor('One Time Fee', 500);

该发票将立即对用户的信用卡进行收费。invoiceFor 方法也接受一个数组作为第三个参数，允许您将任何选项传递给底层的 Stripe 收费创建。

$user->invoiceFor('One Time Fee', 500, [
    'custom-option' => $value,
]);

如果不想发票重试失败的收费，您需要在第一次失败的收费后使用 Stripe API 关闭它们。

发票

您可以使用 invoices 方法轻松检索账单模型的发票数组。

$invoices = $user->invoices();

当列出客户的发票时，您可以使用发票的辅助方法来显示相关的发票信息。例如，您可能希望在 GridView 中列出每个发票，以便用户可以轻松下载其中的任何一个。

$dataProvider = new \yii\data\ArrayDataProvider([
            'allModels' => $invoices,
            'pagination' => [
                'pageSize' => 10,
            ],
        ]);

 echo yii\grid\GridView::widget([
        'dataProvider' => $dataProvider,
        'columns' => [
            [
                'label' => 'Invoice Date',
                'value' => function ($model) {
                    return $model->date()->toFormattedDateString();
                }
            ],
            [
                'label' => 'Total',
                'value' => function ($model) {
                    return $model->total();
                }
            ],
            [
                'header' => 'Action',
                'class' => 'yii\grid\ActionColumn',
                'template' => '{download}',
                'buttons' => [
                    'download' => function ($url, $model, $key) {
                        $options = [
                            'title' => Yii::t('yii', 'Download Invoice'),
                            'data-pjax' => '0',
                        ];
                        $url = ['download-invoice', 'invoiceId' => $model->id];
                        return \yii\helpers\Html::a('<span class="glyphicon glyphicon-download"></span>', $url, $options);
                    }
                ],
            ],
        ],
 ]);

生成发票 PDF

在您的控制器中创建 download-invoice 动作，例如

public function actionDownloadInvoice($invoiceId)
{
    return $user->downloadInvoice($invoiceId, [
        'vendor' => 'Your Company',
        'product' => 'Your Product',
    ]);
}

退款

退款对象允许您退款先前已创建但尚未退款的收费。资金将退还到最初收费的信用卡或借记卡。您最初被收取的费用也将退还。

// Create Invoice
$invoice = $user->invoiceFor('Invoice Description', 1000);
 
// Create the refund
$refund = $user->refund($invoice->charge);

var_dump($refund->amount); // 1000

inquid / yii2-cashier

维护者

详细信息