README

这是用于 Laravel 应用的 Billing SDK，它使用了 IX Billing Engine。

要使用此 SDK，您需要从 IX Billing 获取 Client ID 和 Client Secret。

安装

使用 Composer 安装此包

composer require boneybone/billing-sdk

配置

使用 vendor:publish artisan 命令发布配置文件。

php artisan vendor:publish --tag=billing-service

使用以下变量设置 .env 文件

BILLING_SERVICE_CLIENT_ID=
BILLING_SERVICE_CLIENT_SECRET=
BILLING_SERVICE_ENDPOINT=

如果您打算使用 guzzlehttp/guzzle 作为您的 HTTP 客户端，请将 config/billing-service.php 客户端设置为 guzzle。

// config/billing-service.php

'client' => 'guzzle'

...

然后安装 Guzzle。

composer require guzzlehttp/guzzle

如何使用

实体

每个账单服务的端点都是此 SDK 上的一个 Entity，因此如果您想使用 /invoices 端点，则需要使用 BoneyBone\BillingService\Entities\InvoiceEntity 实体。但每个实体都有自己的别名，见下文。

目前只有一个实体可用，将相应更新。

Entity 包含 5 个方法，即 list()、get()、create()、update() 和 delete()，具体请参考 BoneyBoney\BillingService\Contracts\Entity 中的 Entity Interface。

Entity 的每个方法都接受一个 array 负载数据在最后一个参数中，因此您可以传递任何负载到账单服务器。

BillingService::use('invoice')->list([
    'id' => 'this is invoice id'
]);

BillingService::use('invoice')->list([
    'args' => [
        'customer_id' => 'this is customer id'
    ]
]);

BillingService::use('invoice')->get($id);

BillingService::use('invoice')->delete($id);

BillingService::use('invoice')->update($id, [
    // array payload
]);

账单外观

BillingService 外观就像是您的代码和 SDK 之间的门，使用这个外观，您可以注册 Entity、RequestClient、获取访问令牌、端点等。

此 SDK 与 PSR-7 兼容，因此您可以使用任何您想要的 HTTP 客户端。

默认客户端是 guzzle，但您可以自由更改和扩展客户端，以下是方法。

扩展 RequestClient

RequestClient 是 SDK 和互联网之间的桥梁，客户端的职责是将 HTTP 请求发送到账单服务器，并且它只需要 1 个方法。

并且它需要实现 BoneyBone\BillingService\Contracts\RequestClient。

<?php

use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\ResponseInterface;
use BoneyBone\BillingService\Contracts\RequestClient

class YourClient implements RequestClient {

    /**
     * Send HTTP Request.
     *
     * @param  RequestInterface   $request
     * @param  array              $options
     * @return ResponseInterface
     */
    public function sendRequest(RequestInterface $request, array $options = []) : ResponseInterface {
        // here's how you implement tht HTTP request to the server.
        // the $options format is follow the Guzzle Request Options, so each of guzzle options valid here
        // and you need to parse that options
        // @see http://docs.guzzlephp.org/en/stable/request-options.html
    }

}

如您所见，sendRequest() 方法接受 PSR 的 RequestInterface 作为参数，并期望返回 PSR 的 ResponseInterface。

然后您可以使用外观注册您的 RequestClient。

// app/Providers/AppServiceProvider.php

BillingService::requestClient('your-request-client-name', YourClient::class);

最后，您可以在 config/billing-service.php 中将您的客户端设置为默认客户端

...
'client' => 'your-request-client-name'
...

完成！SDK 现在将使用您的客户端作为 HTTP 客户端。

创建新实体

由于 SDK 没有涵盖所有的账单端点，您可能需要自己实现并注册它。以下是方法。

如前所述，Entity 包含 5 个方法，即 list()、get()、create()、update() 和 delete()，因为实体实现了 BoneyBone\BillingService\Contracts\Entity。

以下是它的样子

<?php

namespace YourNamespace\Entities;

use BoneyBone\BillingService\WithRequests;
use BoneyBone\BillingService\Contracts\Entity;

final class CreditNoteEntity implements Entity {

    use WithRequests {
        WithRequests::get as getRequest;
    }

    /**
     * Get the entity listings.
     *
     * @param  array $options
     * @return array
     */
    public function list(array $options = []) {
        $res = $this->get('/credit_not_endpoints');

        return $res->getBody()->getContents();
    }

    /**
     * Get the individual entity.
     *
     * @param  string|integer $id
     * @param  array          $options
     * @return array
     */
    public function get($id, array $options = []) {
        //
    }

    /**
     * Create new entity.
     *
     * @param  array $data
     * @param  array $options
     * @return array
     */
    public function create(array $data, array $options = []) {
        //
    }

    /**
     * Update entity.
     *
     * @param  string|int  $id
     * @param  array       $options
     * @return array
     */
    public function update($id, array $options = []) {
        //
    }

    /**
     * Delete entity.
     *
     * @param  string|int  $id
     * @param  array       $options
     * @return array
     */
    public function delete($id, array $options = []) {
        //
    }
}

Entity 的职责是从 API 服务器提供数据给客户端，并应返回一个包含服务器数据的数组对象。

为了符合 PSR-7 规范，此 SDK 随带 BoneyBone\BillingService\WithRequests 特性，为您提供基本的 HTTP 请求方法。该 WithRequests 特性包含您进行 HTTP 请求到服务器所需的所有 HTTP 方法。

例如 get()、post()、patch() 等。但由于 Entity 已经预留了 get() 方法，因此特性被覆盖。您需要在导入特性时使用以下代码来别名 get() 方法。

use WithRequests {
    WithRequests::get as getRequest;
}

最后，您需要将实体注册到 SDK 中。

BillingService::entity('credit-note', CreditNoteEntity::class);

完成！