README

Yii 2 的 Cashier 扩展

本扩展是 Laravel 的 Cashier 包的移植版本，可在此处查看 Laravel 的 Cashier 包文档

支持我们

您的业务依赖我们的贡献吗？请与我们联系，并在 Patreon 上支持我们。所有承诺都将用于维护工作和新功能。

安装

安装此扩展的最佳方式是通过 composer。

运行以下命令之一：

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

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

"yii2mod/yii2-cashier": "*"

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/yii2mod/yii2-cashier/migrations

模型设置

接下来，在您的用户模型定义中添加 Billable 特性

use yii2mod\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();

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

订阅试用

upfront使用信用卡

如果您想在收集客户支付方式信息的同时向客户提供试用期间，您应该在创建订阅时使用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

如果您想在收集用户支付方式信息之前提供试用期间，您只需将用户记录上的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' => 'yii2mod\cashier\controllers\WebhookController',
    ],

就这样！失败的支付将被控制器捕获和处理。当Stripe确定订阅失败（通常在三次失败的支付尝试后）时，控制器将取消客户的订阅。别忘了：您需要在Stripe控制面板设置中配置webhook URI，例如：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

yii2mod / yii2-cashier

维护者

详细信息