README

一个由Saloon支持的扩展型 SDK。

安装

要开始使用 NextGen SDK，您需要通过 Composer 安装它。

$ composer require clinect/nextgen-sdk

注意：NextGen SDK 支持 PHP 8.1+

依赖关系

NextGen SDK 有两个依赖关系。

• Saloon（API 集成框架的核心 PHP 库）
• Saloon Cache Plugin（Saloon v2 的官方缓存插件）

使用 Laravel 吗？

安装完成后，使用以下 Artisan 命令发布配置文件：

php artisan vendor:publish --tag=nextgen-config

NextGen SDK 类

使用 NextGen SDK 类有两种方式。

通过实例化类

<?php

use Clinect\NextGen\NextGen;

$connector = new NextGen(...);

$request = $connector->persons()->get();

通过 Laravel 依赖注入使用

<?php

use Clinect\NextGen\NextGen;

class ExampleController extends Controller
{
    public function show(NextGen $connector)
    {
        $request = $connector->persons()->get();
    }
}

授权/会话

在实例化 NextGen SDK 类时，会自动执行授权和会话。

配置

NextGen 配置键列表

• client_id
• secret
• site_id
• enterprise_id
• practice_id
• base_url
• route_uri
• auth_uri
• cache_adapter (有关响应缓存的更多信息)

注意：所有配置键和值都是必需的。

使用

<?php

use Clinect\NextGen\NextGen;
use Clinect\NextGen\NextGenConfig;

$config = NextGenConfig::create([
    'client_id' => 'nextgen-client-id',
    'secret' => 'nextgen-secret',
    'site_id' => 'nextgen-site-id',
    'enterprise_id' => 'nextgen-enterprise-id',
    'practice_id' => 'nextgen-practice-id',
    'base_url' => 'https://nativeapi.nextgen.com/nge/prod',
    'route_uri' => '/nge-api/api',
    'auth_uri' => '/nge-oauth/token',
    'cache_adapter' => [
        'type' => 'laravel-cache',

        'driver' => Illuminate\Support\Facades\Cache::class,

        'cache_type' => 'file',

        'expiry_time' => 3600,
    ],
]);

$connector = new NextGen($config);

使用 Laravel 吗？

使用 artisan 命令发布配置（请参阅上面的示例）。并将以下内容添加到您的 .env 配置文件中。

# config for .env file

NEXTGEN_CLIENTID=nextgen-client-id
NEXTGEN_SECRET=nextgen-secret
NEXTGEN_SITEID=nextgen-site-id
NEXTGEN_ENTERPRISEID=nextgen-enterprise-id
NEXTGEN_PRACTICEID=nextgen-practice-id
NEXTGEN_URL=https://nativeapi.nextgen.com/nge/prod
NEXTGEN_ROUTEURI=/nge-api/api
NEXTGEN_AUTHURI=/nge-oauth/token

请求

NextGen SDK 请求存储单个 API 请求的信息。在请求中，您可以通过在每个端点请求的末尾附加来设置 HTTP 方法。

方法

• get()
• post()
• put()
• patch()
• delete()

注意：所有 id 都是可选的。

查看所有可用端点

使用

GET

<?php

use Clinect\NextGen\NextGen;

$connector = new NextGen(...);

// Endpoint: "/persons"
$request = $connector->persons()->get();

// Endpoint: "/persons/{id}"
$request = $connector->persons({id})->get();

POST|PUT|PATCH|DELETE

<?php

use Clinect\NextGen\NextGen;

$connector = new NextGen(...);

// Post
$request = $connector->persons()
    ->fill([
        'name' => 'Name',
        'provider' => 'Provider name',
    ])
    ->post();

// Put
$request = $connector->persons()
    ->fill([
        'name' => 'Name',
        'provider' => 'Provider name',
    ])
    ->put();

// Patch
$request = $connector->persons()
    ->fill([
        'name' => 'Name',
        'provider' => 'Provider name',
    ])
    ->patch();

// Delete
$request = $connector->persons({id})->delete();

头部

<?php

use Clinect\NextGen\NextGen;

$connector = new NextGen(...);

$request = $connector->persons()
    ->withHeaders([
        ...
    ])
    ->get();

查询参数

<?php

use Clinect\NextGen\NextGen;

$connector = new NextGen(...);

$request = $connector->persons()
    ->withQuery([
        ...
    ])
    ->get();

客户端配置

<?php

use Clinect\NextGen\NextGen;

$connector = new NextGen(...);

$request = $connector->persons()
    ->withConfig([
        ...
    ])
    ->get();

分页

<?php

use Clinect\NextGen\NextGen;

$connector = new NextGen(...);

$request = $connector->persons()->paginate(perPage: $perPage, page: $page);

请求体/数据

使用表单体

<?php

use Clinect\NextGen\NextGen;

$request = $connector->persons()
    ->fill([
        'name' => 'Name',
        'provider' => 'Provider name',
    ])
    ->usingFormBody()
    ->post();

使用 JSON 体

<?php

use Clinect\NextGen\NextGen;

$request = $connector->persons()
    ->fill([
        'name' => 'Name',
        'provider' => 'Provider name',
    ])
    ->usingJsonBody()
    ->post();

使用多部分体

<?php

use Clinect\NextGen\NextGen;

$request = $connector->persons()
    ->fill([
        'name' => 'logo',
        'contents' => 'your-file-contents-or-stream',
        'filename' => 'logo.png',
    ])
    ->usingMultipartBody()
    ->post();

响应

根据您如何发送请求（同步/异步），您将收到 Response 实例或 PromiseInterface。

同步响应

<?php

use Clinect\NextGen\NextGen;

$connector = new NextGen(...);

$request = $connector->persons()->get();

$response = $connector->send($request);

// Returns the HTTP body as a string
$response->body();

// Retrieves a JSON response body and json_decodes it into an array.
$response->json();

异步响应

<?php

use Clinect\NextGen\NextGen;
use Saloon\Contracts\Response;

$connector = new NextGen(...);

$request = $connector->persons()->get();

$response = $connector->sendAsync($request);

$promise->then(function (Response $response) {
        // Handle successful response
    })
    ->otherwise(function (Exception $exception) {
        // Handle failed request
    });

响应缓存

在某些情况下，您可能希望缓存来自 API 的响应，例如检索静态列表或检索您知道在指定时间内不会更改的数据。缓存可以非常强大，并且可以通过减少对第三方集成的依赖来加快应用程序的速度。这里有三种类型的缓存集成。

注意：可以在 NextGenConfig::create([...]) 中添加/更改缓存，或者在 Laravel 中在 ./config/clinect/nextgen.php 文件中添加。

PsrCacheDriver（支持 PSR-16 缓存实现）

不可用。

FlysystemDriver（需要 league/flysystem 版本 3）

不可用。

LaravelCacheDriver（支持 Laravel 的任何缓存磁盘，需要 Laravel）

<?php

use Clinect\NextGen\NextGenConfig;

NextGenConfig::create([
    ...
    'cache_adapter' => [
        // Cache type.
        'type' => 'laravel-cache',

        // Driver to be used.
        'driver' => Illuminate\Support\Facades\Cache::class,

        // Where to store the cache: "file", "redis", etc...
        // For reference: Check your laravel './config/cache.php'file
        'cache_type' => 'file',

        // Set cache expiry time in seconds.
        'expiry_time' => 3600,
    ],
]);

使用

<?php

$connector = new NextGen(...);

// Using cache
$request = $connector->enableCaching()->persons()->get();

// Not using cache
$request = $connector->persons()->get();

测试

运行以下命令以启动测试：

vendor/bin/phpunit --testsuite Feature

它如何工作？

测试 Saloon 请求涉及固定值。Saloon 将检查固定值是否存在，如果不存在，则将执行真实的 API 请求并将响应存储以备下次使用。

• 如果一个端点已经有一个Fixture，它将直接使用该Fixture作为记录的响应，而不会运行实际的请求。
• 如果一个端点没有Fixture，运行测试将模拟一个真实的请求，响应将被记录为Fixture，这个JSON响应保存在Tests/Fixtures/Saloon中。

删除Fixtures的命令

这将删除授权Fixture和ng-session Fixture

composer run delete-config-fixtures

这将删除所有Fixture

composer run delete-all-fixtures

要重置使用此分支的所有测试，请按顺序运行以下命令

composer run delete-config-fixtures
composer run delete-all-fixtures
vendor/bin/phpunit --testsuite Feature

许可证

MIT许可证（MIT）。