README

PHP Simple Client API 是一个轻量级的PHP库，可以轻松构建REST API客户端。它简化了HTTP请求、处理响应和管理API交互。

要求

• PHP版本 >= 8.1
• GuzzleHttp >= 7.8

安装

您可以使用流行的包管理器 composer 无缝地安装 PHP Simple Client Api。

composer require thojou/php-simple-api-client:dev-master

用法

要开始使用Simple API Client库实现REST API客户端，请按照以下步骤操作

快速入门

1. 创建您的API类

扩展 Thojou\SimpleApiClient\AbstractApi 类以创建您的API客户端类。实现onSuccessResponse、onRedirectResponse和onErrorResponse方法以处理不同类型的响应。

<?php

use Thojou\SimpleApiClient\AbstractApi;
use Thojou\SimpleApiClient\Contracts\ClientFactoryInterface;
use Thojou\SimpleApiClient\Exception\ApiException;

class MyApi extends AbstractApi
{
    protected function onSuccessResponse(int $statusCode, array $headers, string $response): mixed
    {
        return (array) json_decode($response, true);
    }

    protected function onRedirectResponse(int $statusCode, array $headers, string $response): mixed
    {
        throw new ApiException('Redirects are not supported');
    }

    protected function onErrorResponse(int $statusCode, array $headers, string $response): mixed
    {
        throw new ApiException('Status code ' . $statusCode . ': ' . $response);
    }
}

2. 创建您的请求类

实现 Thojou\SimpleApiClient\Contracts\RequestInterface 接口以创建您的请求类。根据您的API端点需要定义HTTP方法、URI、头部、正文格式和正文。

<?php

use Thojou\SimpleApiClient\Contracts\RequestInterface;use Thojou\SimpleApiClient\Enums\RequestMethod;

class MyRequest implements RequestInterface
{
    public function getMethod(): RequestMethod
    {
        return RequestMethod::GET;
    }

    public function getUri(): string
    {
        return 'v1/weather';
    }

    public function getHeaders(): array
    {
         return [
            'Accept' => 'application/json',
        ];
    }
    
    public function getBodyFormat(): BodyFormat
    {
        return BodyFormat::Empty;
    }

    public function getBody(): null|array
    {
        return null;
    }
}

3. 使用您的API客户端

现在，您可以使用API客户端对API端点进行请求。以下是如何创建API实例并发送请求的示例

<?php

use Thojou\SimpleApiClient\Adapter\GuzzleClientFactory;

$httpClientFactory = new GuzzleClientFactory('https://api.example.com', 'MyApi/1.0.0', [
    'Authorization' => 'Bearer: mySecretApiToken'
]); 
$api = new MyApi($httpClientFactory);

$response = $api->send(new MyRequest());
var_dump($response);

// Or send an asynchronous request
$promise = $api->sendAsync(new MyRequest());
$response = $promise->wait(); // Wait for the asynchronous request to complete
var_dump($response);

示例：使用JSON数据发送POST请求

假设您需要向API端点发送JSON数据的POST请求。您可以通过定义一个带有 RequestMethod::POST 方法的请求类并指定 BodyFormat::JSON 正文格式以及您的JSON数据来实现。

<?php

use Thojou\SimpleApiClient\Contracts\RequestInterface;
use Thojou\SimpleApiClient\Enums\RequestMethod;
use Thojou\SimpleApiClient\Enums\BodyFormat;

class MyJsonPostRequest implements RequestInterface
{
    public function getMethod(): RequestMethod
    {
        return RequestMethod::POST;
    }

    public function getUri(): string
    {
        return 'v1/create-resource';
    }

    public function getHeaders(): array
    {
        return [
            'Accept' => 'application/json',
            'Content-Type' => 'application/json',
        ];
    }
    
    public function getBodyFormat(): BodyFormat
    {
        return BodyFormat::JSON;
    }

    public function getBody(): null|array
    {
        // Define your JSON data as an associative array
        return [
            'key' => 'value',
            'nested' => [
                'property' => 'nested-value',
            ],
        ];
    }
}

示例：使用表单数据发送POST请求

假设您需要向API端点发送表单数据的POST请求。您可以通过定义一个带有 RequestMethod::POST 方法的请求类并指定 BodyFormat::MULTIPART 正文格式以及您的表单数据来实现。

<?php

use Thojou\SimpleApiClient\Contracts\RequestInterface;
use Thojou\SimpleApiClient\Enums\RequestMethod;
use Thojou\SimpleApiClient\Enums\BodyFormat;

class MyMultipartPostRequest implements RequestInterface
{
    public function getMethod(): RequestMethod
    {
        return RequestMethod::POST;
    }

    public function getUri(): string
    {
        return 'v1/upload-file';
    }

    public function getHeaders(): array
    {
        return [
            'Accept' => 'application/json',
        ];
    }
    
    public function getBodyFormat(): BodyFormat
    {
        return BodyFormat::MULTIPART;
    }

    public function getBody(): null|array
    {
        // Define your multipart form data as an associative array
        return [
            'file' => fopen('/path/to/file.jpg', 'r'), // Replace with your file path
            'field1' => 'value1',
            'field2' => 'value2',
        ];
    }
}

现在，您可以使用API客户端发送与上一个示例类似的表单数据的POST请求。

许可证

本项目采用宽松的 MIT许可证。