README

Laravel Paystack Subscription提供了一个简单、流畅的接口，用于Paystack的订阅计费服务。无需再担心编写订阅计费代码！

安装

您可以通过composer安装此包

composer require digikraaft/laravel-paystack-subscription

配置文件

Laravel Paystack Subscription包附带一个配置文件，以下是文件内容

return [

    /*
    |--------------------------------------------------------------------------
    | Paystack Keys
    |--------------------------------------------------------------------------
    |
    | The Paystack publishable key and secret key. You can get these from your Paystack dashboard.
    |
    */

    'public_key' => env('PAYSTACK_PUBLIC_KEY'),

    'secret' => env('PAYSTACK_SECRET'),

    /*
    |--------------------------------------------------------------------------
    | Subscription Model
    |--------------------------------------------------------------------------
    |
    | This is the model in your application that implements the Billable trait
    | provided by PaystackSubscription. It will serve as the primary model you use while
    | interacting with PaystackSubscription related methods, subscriptions, etc.
    |
    */
    'model' => env('SUBSCRIPTION_MODEL', App\User::class),

    /*
   |--------------------------------------------------------------------------
   | User Table
   |--------------------------------------------------------------------------
   |
   | This is the table in your application where your users' information is stored.
   |
   */
    'user_table' => 'users',

    /*
   |--------------------------------------------------------------------------
   | Webhooks Path
   |--------------------------------------------------------------------------
   |
   | This is the base URI path where webhooks will be handled from.
   |
   | This should correspond to the webhooks URL set in your Paystack dashboard:
   | https://dashboard.paystack.com/#/settings/developer.
   |
   | If your webhook URL is https://domain.com/paystack/webhook/ then you should simply enter paystack here.
   |
   | Remember to also add this as an exception in your VerifyCsrfToken middleware.
   |
   | See the demo application linked on github to help you get started.
   |
   */
    'webhook_path' => env('PAYSTACK_WEBHOOK_PATH', 'paystack'),

];

您可以使用以下命令发布此配置文件

php artisan vendor:publish --provider="Digikraaft\PaystackSubscritpion\PaystackSubscritpionServiceProvider" --tag="config"

数据库迁移

您需要使用以下命令发布数据库迁移

php artisan vendor:publish --provider="Digikraaft\PaystackSubscritpion\PaystackSubscritpionServiceProvider" --tag="migrations"
php artisan migrate

迁移将为您的用户表添加多个列，并创建一个新的订阅表以保存所有客户的订阅。

配置

可计费模型

在开始使用包之前，请将Billable特质添加到您的模型定义中。这个特质提供了各种方法，使您能够执行常见的计费任务，例如创建订阅、续订订阅和取消订阅

use Digikraaft\PaystackSubscription\Billable;

class User extends Authenticatable
{
    use Billable;
}

包假设您的Billable模型将是Laravel附带的默认App\User类。如果您想更改这一点，您可以在.env文件中或包发布的配置文件中指定不同的模型

SUBSCRIPTION_MODEL = App\User

请注意，如果您使用的是Laravel提供的App\User模型以外的模型，您需要发布并修改提供的迁移以匹配您的替代模型表名。

您还可以为您的可计费模型指定不同的表名。请参阅配置文件部分。

API密钥

接下来，您应该在.env文件中配置您的Paystack密钥。您可以从Paystack仪表板获取您的Paystack API密钥。

PAYSTACK_PUBLIC_KEY=your-paystack-public-key
PAYSTACK_SECRET=your-paystack-secret

客户

检索客户

您可以使用PaystackSubscription::findBillable方法通过Paystack ID检索客户。这将返回Billable模型的一个实例

use Digikraaft\PaystackSubscription\PaystackSubscription;

$user = PaystackSubscription::findBillable($paystackId);

创建客户

如果您需要创建一个未立即启动订阅的Paystack客户，可以使用createAsPaystackCustomer方法完成

$paystackCustomer = $user->createAsPaystackCustomer();

该代码在Paystack中创建了一个客户。您可以在稍后的日期开始订阅。您还可以使用可选的$options数组传递任何由Paystack API支持的额外参数

$paystackCustomer = $user->createAsPaystackCustomer($options);

如果可计费实体已经是Paystack的客户，您可以使用asPaystackCustomer方法检索客户对象

$paystackCustomer = $user->asPaystackCustomer();

如果您不确定可计费实体是否已经是Paystack客户，可以使用createOrGetPaystackCustomer方法获取客户对象。如果不存在，此方法将在Paystack中创建一个新的客户

$paystackCustomer = $user->createOrGetPaystackCustomer();

更新客户

如果您需要使用附加信息更新Paystack客户，可以使用updatePaystackCustomer方法完成

$paystackCustomer = $user->updatePaystackCustomer($options);

检查订阅状态

一旦用户订阅了您的应用程序，您可以使用各种方便的方法轻松检查他们的订阅状态。首先，如果用户有活跃的订阅，即使订阅已取消且在账单周期结束时未续订，subscribed 方法也会返回 true

if ($user->subscribed('default')) {
    //
}

您还可以在路由中间件中使用 subscribed 方法，允许您根据用户的订阅状态过滤对路由和控制器访问。

public function handle($request, Closure $next)
{
    if ($request->user() && ! $request->user()->subscribed('default')) {
        // This user is not a paying customer...
        return redirect('billing');
    }

    return $next($request);
}

您可以在本软件包的演示实现中看到此示例此处

您可以使用 subscribedToPlan 方法根据给定的 Paystack 计划代码确定用户是否订阅了给定的计划。在此示例中，我们将确定用户的 default 订阅是否活跃地订阅了 PLN_paystackplan_code 计划。

if ($user->subscribedToPlan('PLN_paystackplan_code', 'default')) {
    //
}

通过将数组传递给 subscribedToPlan 方法，您可以确定用户的 default 订阅是否活跃地订阅了 PLN_paystackplan_code 或 PLN_paystackplan_code2 计划。

if ($user->subscribedToPlan(['PLN_paystackplan_code', 'PLN_paystackplan_code2'], 'default')) {
    //
}

您可以使用 active 方法确定用户是否目前有一个活跃的订阅。

if ($user->subscription('default')->active()) {
    //
}

您可以使用 renews 方法确定用户的订阅在当前账单周期结束后是否会续订。

if ($user->subscription('default')->renews()) {
    //
}

您可以使用 daysLeft 方法获取当前账单周期剩余的天数。

$daysLeft = $user->subscription('default')->daysLeft();

您可以使用 endsAt 方法获取当前账单周期结束的日期。

$endDate = $user->subscription('default')->endsAt();

已取消订阅状态

要确定用户是否已取消其订阅，您可以使用 isCancelled 方法。

if ($user->subscription('default')->isCancelled()) {
    //
}

要确定用户的订阅是否过期，您可以使用 pastDue 方法。

if ($user->subscription('default')->pastDue()) {
    //
}

订阅范围

活跃和已取消的订阅状态也作为查询范围可用，这样您就可以轻松查询数据库中的订阅。

// Get all active subscriptions...
$subscriptions = Subscription::query()->active()->get();

// Get all of the cancelled subscriptions for a user...
$subscriptions = $user->subscriptions()->cancelled()->get();

取消订阅

要取消订阅，请在用户的订阅上调用 cancel 方法。

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

当订阅被取消时，数据库中的 paystack_status 列设置为 complete。这是基于 Paytstack 的实现，这意味着订阅在账单周期结束时不会续订。订阅将继续在当前账单周期结束时保持活跃。

恢复订阅

如果用户已取消订阅，并且您希望恢复，请使用 enable 方法。

$user->subscription('default')->enable();

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

处理 Paystack Webhooks

Paystack可以通过webhooks通知您的应用程序各种事件。默认情况下，服务提供商已通过服务提供商配置了一个指向此包的webhook控制器的路由。此控制器将处理所有传入的webhook请求。

默认情况下，此控制器将自动处理取消订阅、启用订阅和失败的发票。此控制器可以扩展以处理您喜欢的任何webhook事件。

为确保您的应用程序可以处理Paystack webhooks，请务必在Paystack仪表板中配置webhook URL。默认情况下，此包的webhook控制器监听 /paystack/webhook

Webhooks & CSRF 保护

由于Paystack webhooks需要绕过Laravel的CSRF保护，请确保在 VerifyCsrfToken 中间件中将URI列为异常或在外部将路由列出 web 中间件组

protected $except = [
    'paystack/*',
];

定义 Webhook 事件处理器

如果您想处理额外的webhook事件，请扩展Webhook控制器。您的方法名称应与该包的预期约定相匹配，具体来说，方法应以前缀 handle 和您想处理的webhook的“驼峰命名”开头。例如，如果您想处理 invoice.create webhook，则应在控制器中添加 handleInvoiceCreate 方法

<?php

namespace App\Http\Controllers;

use Digikraaft\PaystackSubscription\Http\Controllers\WebhookController as PaystackWebhookController;

class WebhookController extends PaystackWebhookController
{
    /**
     * Handle invoice create.
     *
     * @param  array  $payload
     * @return \Symfony\Component\HttpFoundation\Response
     */
    public function handleInvoiceCreate($payload)
    {
        // Handle The Event
    }
}

接下来，在您的 routes/web.php 文件中定义一个路由到您的控制器。这将覆盖默认的打包路由

Route::post(
    'paystack/webhook',
    '\App\Http\Controllers\WebhookController@handleWebhook'
);

在底层，webhook处理使用此包实现

有关Paystack事件的详细信息，请在此查看

Paystack API

如果您想直接与Paystack对象交互，您可以方便地使用 asPaystack 方法检索它们

$paystackSubscription = $subscription->asPaystackSubscription();

$paystackSubscription->quantity = 2;

$paystackSubscription->save();

有关如何与对象交互的详细信息，请参阅我们的 paystack-php 包此处

测试

当测试使用此包的应用程序时，您可以自由地模拟对Paystack API的实际HTTP请求；但是，这需要您部分重新实现此包的自身行为。因此，我们建议允许您的测试击中实际的Paystack API。虽然这较慢，但它提供了更大的信心，即您的应用程序按预期工作，并且任何慢速测试可以放置在其自己的PHPUnit测试组中。

在测试时，请记住，此包本身已经有一个非常好的测试套件，因此您应该只关注测试您自己应用程序的订阅和支付流程，而不是此包的每个底层行为。

要开始，请将您的Paystack密钥的测试版本和其他必需实体添加到您的 phpunit.xml 文件中

<env name="PAYSTACK_SECRET" value="sk_test_your_secret_key"/>
<env name="PAYSTACK_CUSTOMER" value="CUS_<customercode1>" />
<env name="PAYSTACK_OTHER_CUSTOMER" value="CUS_<customercode2>" />
<env name="PAYSTACK_PLAN" value="PLN_<plan_code1>" />
<env name="PAYSTACK_OTHER_PLAN" value="PLN_<plan_code2>" />
<env name="PAYSTACK_TRANSACTION_ID" value="<valid_transaction_id_used_for_plan_code1>" />
<env name="PAYSTACK_TRANSACTION_ID_INVALID" value="<existing_paystack_transaction_id>" />
<env name="PAYSTACK_TRANSACTION_REF" value="valid_transaction_reference_used_for_plan_code1" />
<env name="PAYSTACK_TRANSACTION_REF_INVALID" value="<existing_paystack_transaction_id>" />
<env name="DB_CONNECTION" value="testing"/>

在测试时，请确保创建上述环境变量并在paystack中与值中的描述相匹配。

使用以下命令运行您的测试

composer test

替代方案

变更日志

请参阅变更日志了解最近有哪些更改。

贡献

请参阅贡献指南获取详细信息。

安全性

如果您发现任何安全问题，请通过电子邮件dev@digitalkraaft.com联系，而不是使用问题跟踪器。

致谢

许可证

MIT许可证（MIT）。请参阅许可证文件获取更多信息。

kikter / laravel-paystack-subscription

维护者

详细信息