README

一套可以帮助你制作更好SDK的工具。

安装

composer require juststeveking/sdk-tools

使用

这个库中有许多不同的组件，我会尽力记录这些。

HTTP组件

请求类

使用请求类，你可以传入方法和URI来构建一个请求对象，并将其转换为PSR-7请求。

use JustSteveKing\Tools\Http\Enums\Method;
use JustSteveKing\Tools\Http\Request;

$request = (new Request(
    method: Method::GET,
    uri: 'https://api.domain.com/resources',
))->toPsrRequest(); // Returns whichever PSR-7 implementation you have installed.

响应类

使用响应类，你可以将PSR响应转换为具有更友好API的响应类。

use JustSteveKing\Tools\Http\Response;

$response = Response::fromPsrResponse(
    response: $response, // Add a PSR response here.
);

$response->status(); // Get the status code.
$response->headers(); // Get the headers from the response.
$response->json(); // Get the payload from the response as an array.
$response->protocol(); // Get the HTTP protocol from the response.
$response->reason(); // Get the Http reason phrase from the response.

有效载荷类

使用有效载荷类，你可以从JSON字符串构建HTTP流。

use  JustSteveKing\Tools\Http\Payload;

$json = json_encode(
    value: ['foo' => 'bar'],
);

$payload = (new Payload(
    content: $json,
))->toStream(); // Returns whichever PSR-7 implementation you have installed.

查询参数类

使用查询参数类，你可以程序化构建你的请求参数。你可以通过值属性传入字符串、整数或布尔值。

use JustSteveKing\Tools\Http\Uri\QueryParameter;

$queryParameter = (new QueryParameter(
    key: 'test',
    value: true,
))->toString(); // Returns `test=1`

认证类

使用认证类，你可以构建你想要或需要的认证头。第二个参数类型默认为Bearer令牌，但是你可以覆盖它。

use JustSteveKing\Tools\Http\Headers\Authorization;

$header = (new Authorization(
    value: 'YOUR-API-TOKEN',
))->toHeader(); // ['Authorization' => 'Bearer YOUR_API_TOKEN'],

令牌头类

使用令牌头类，你可以构建一个自定义的令牌头，你可以将其附加到你的请求上。第二个参数key默认为X-API-TOKEN，你可以覆盖它。

use JustSteveKing\Tools\Http\Headers\TokenHeader;

$header = (new TokenHeader(
    value: 'YOUR-API-KEY',
))->toHeader(); // ['X-API-TOKEN' => 'YOUR-API-TOKEN'],

HTTP传输类

使用HTTP传输类，你可以发现已安装的PSR-18客户端并返回PSR-18实现。

use JustSteveKing\Tools\SDK\Transport\HttpTransport;

$client = HttpTransport::client(); // HttpClient PSR-18 implementation.

SDK类

SDK类是为了让你扩展自己的SDK而设计的，它在构造函数中接受一个属性，这将是一个PSR-18兼容的HTTP客户端。

use JustSteveKing\Tools\SDK\SDK;
use JustSteveKing\Tools\SDK\Transport\HttpTransport;

$sdk = new SDK(
    client: HttpTransport::client(),
);

// Fetch the attached client:
$sdk->client();

// Replace the attached client
$sdk->setClient(
    client: new \Http\Mock\Client(),
);

构建自己的SDK

要使用这些工具构建自己的SDK，你可以很容易地使用提供的组件进行脚手架搭建。如果你不能完全进行脚手架搭建，那么请随时提出问题或PR，这样我可以为更多的用例提供更好的支持。

use JustSteveKing\Tools\Http\Headers\Authorization;
use JustSteveKing\Tools\SDK\SDK;
use JustSteveKing\Tools\SDK\Transport\HttpTransport;

class Acme extends SDK
{
    public function __construct(
        protected HttpClient $client,
        private readonly Authorization $auth,    
    ) {}
    
    public static function build(string $apiToken): Acme
    {
        return new Acme(
            client: HttpTransport::client(),
            auth: (new Authorization(
                value: $apiToken,
            )),
        );
    }
}

从这里开始，你可以在Acme类中开始添加你的SDK逻辑。

$acme = Acme::build(
    apiToken: 'YOUR-API-TOKEN',
);

// Then you can start to do things like:
$acme->projects()->list();

资源类

你可以使用资源类来定义你的API或SDK上的资源。

use JustSteveKing\Tools\Http\Enums\Method;
use JustSteveKing\Tools\Http\Request;
use JustSteveKing\Tools\SDK\Resource;
use JustSteveKing\Tools\SDK\SDK;
use JustSteveKing\Tools\SDK\Transport\HttpTransport;

$resource = new Resource(
    sdk: new SDK(
        client: HttpTransport::client(),
    ),
);

// Access the underlying SDK
$resource->sdk();

// Access the client from the resource
$resource->sdk()->client();

// Example of sending a request
$resource->sdk()->client()->sendRequest(
    request: new Request(
        method: Method::GET,
        uri: 'https://api.domain.com/resource',
    ),
);

当然，上面的代码只是你所能做的示例，你可以根据需要抽象化它。

扩展你的SDK

你可以使用资源类来创建你自己的资源，并开始为你的API构建实现。

use JustSteveKing\Tools\SDK\Resource;
use Psr\Http\Message\ResponseInterface;

class Project extends Resource
{
    public function list(): ResponseInterface
    {
        try {
            $response = $this->sdk()->client()->sendRequest(
                request: new Request(
                    method: Method::GET,
                    uri: 'https://api.domain.com/resource',
                ),
            )
        } catch (Throwable $exception) {
            throw new AcmeRequestException(
                message: 'Failed to fetch projects from API',
                previous: $exception,
            );
        }
        
        return $response;
    }
}

测试

运行测试

composer run test

鸣谢

授权协议

MIT授权协议（MIT）。请参阅授权文件获取更多信息。

juststeveking / sdk-tools

维护者

详细信息