numenor / api-wrapper

一个用于快速开发围绕远程API的PHP包装客户端的系统

维护者

详细信息

github.com/numenordev/com.numenor.php.api-wrapper

源代码

问题

安装: 3

依赖: 0

建议者: 0

安全: 0

星标: 0

关注者: 1

分支: 0

开放问题: 0

1.0.0 2021-06-15 15:16 UTC

Requires

Requires (Dev)

MIT 3487c5b22f49a4404b2abe47bfaafb33e2d3d19b

  • Nick Rupert <nickrupert7.woop@gmail.com>

phprestapiclientwrapperremote

This package is not auto-updated.

Last update: 2024-10-03 05:22:50 UTC

README

简介

API包装器是一个用于快速开发围绕远程API的PHP包装客户端的系统。在底层由Guzzle提供支持，这个库提供了所有必要的抽象，以快速配置API请求，无需处理不必要的样板代码。

要深入了解这个库的优点，请查看我们的Medium文章。

本README中的所有示例都使用了JSONPlaceholder API，这是一个用于测试基本请求的免费REST API。

安装

要将此库添加到您的项目中，请运行

composer require numenor/api-wrapper

用法

路由

基本路由

可以使用Route类创建路由。所有路由方法都接受一个唯一的名称和一个URL。

Route::get('post.all', 'https://jsonplaceholder.typicode.com/posts')

唯一的名称用于在请求时引用此路由（见请求）。

可用的路由方法

您可以手动声明路由，或使用任何HTTP动词

Route::endpoint('GET', $name, $route);
Route::head($name, $route);
Route::get($name, $route);
Route::post($name, $route);
Route::put($name, $route);
Route::patch($name, $route);
Route::delete($name, $route);
Route::options($name, $route);

每个路由方法都返回一个Endpoint实例，它表示您的路由的所有配置选项。您可以使用端点的公共成员方法将额外的配置选项（如处理器）应用到端点。

路由组

要将对一组路由应用某些配置选项，请声明一个路由组。路由组可以接受一个基本URL、单个处理器或处理器组（见处理器），以及一个包含路由声明的回调。路由组可以嵌套，并且所有在内部声明的路由都将接收所有父组的配置选项。

Route::group('https://jsonplaceholder.typicode.com', [], function() {
    Route::get('post.all', 'posts');
});

处理器

创建处理器

受Laravel中间件的启发，Processor类在请求执行前后拦截请求。处理器可以在请求发送之前修改 outgoing 请求，并在返回之前检查和修改响应对象。

处理器是应用共享配置选项（如授权头）到 outgoing 请求的首选方式（见请求）。

class AuthorizationProcessor extends Processor
{
    public static function handle(Request $request, callable $next): Response
    {
        $request->headers(['Authorization' => 'token']);

        return $next($request);
    }
}

要处理请求发送后的响应，获取由$next回调返回的响应对象（见响应）。

class PostProcessor extends Processor
{
    public static function handle(Request $request, callable $next): Response
    {
        $response = $next($request);
        
        //Do Something
        
        return $response;
    }
}

应用处理器

您可以将处理器应用到路由和路由组。Route::group和$endpoint->processor函数都接受一个数组或单个处理器类名。

Route::group('https://jsonplaceholder.typicode.com', [GroupProcessor::class], function() {
    Route::get('post.all', 'posts')->processor(EndpointProcessor::class);
});

请求

创建请求

Request类代表在Guzzle执行之前HTTP请求的完整配置。创建请求的最佳方式是使用静态route方法，该方法接受您在声明路由时提供的唯一名称。

$request = Request::route('post.all');

请求路径参数

要设置请求路径参数，您必须在路由上声明该参数，使用花括号{}。

Route::get('post.get', 'posts/{id}');

在创建请求时，使用pathParams方法设置参数值。

$request->pathParams(['id' => 1]);

此请求将解析为URL https://jsonplaceholder.typicode.com/posts/1。

请求查询参数

要设置请求查询（URL）参数，请使用queryParams方法。

$request->queryParams(['userId' => 1]);

此请求将解析为URL https://jsonplaceholder.typicode.com/posts?userId=1。

请求体

请求体可以通过多种方法设置，具体取决于您的需求。

$request->body('body');
$request->json(['key' => 'value']);
$request->formParams(['key' => 'value']);
$request->multipart(['key' => 'value']);

请求头

要配置请求头，请使用headers方法，该方法接受一个包含头名称和值的关联数组。

$request->headers(['Authorization' => 'token']);

身份验证

要配置Guzzle定义的身份验证选项（请参阅Guzzle 文档），而无需手动设置Authorization头，请使用auth方法。

$request->auth(['username', 'password']);

选项

要将任何额外的配置选项传递给Guzzle，请使用options方法。

$request->options(['timeout' => 3.14]);

Guzzle 客户端

要使用自定义Guzzle客户端，请将您的自定义实例传递给Request::route方法。这通常用于调试和为测试模拟Guzzle。

Request::route('post.all', $client);

发送

在您完成配置请求所需的所有选项后，使用send方法执行它以接收响应。

$response = $request->send();

方法链式调用

为了便于使用，所有之前提到的请求方法都可以在一个调用中链式调用。

$response = Request::route('post.get')
    ->pathParams(['id' => 1])
    ->headers(['Authorization' => 'token'])
    ...
    ->send();

响应

在执行请求后，您将接收到一个Response对象。此类实现了Psr\Http\Message\ResponseInterface接口，与Guzzle直接返回的响应对象相同（请参阅Guzzle 文档），实际上内部将所有接口方法调用转发到Guzzle响应对象的一个实例。然而，此响应对象包含一些用于提高易用性的额外方法。

获取内容

默认情况下，Guzzle仅以流的形式返回响应体。尽管这可以被转换为一个普通的string，但请使用响应的getContents方法。

$body = $response->getContents();

JSON

要自动处理JSON字符串响应的解码，请使用json方法。

$data = $response->json();

默认情况下，此方法将JSON字符串解码为关联数组，但为了使用stdClass实例而不是关联数组，请将false传递给此方法。

$data = $response->json(false);

资源

受Laravel的Eloquent和Stripe PHP库的启发，Resource类以模型实例的形式表示API数据，并具有类似ORM的基本功能。

对于不符合或不遵循REST标准的API，资源可能是不必要的抽象。然而，对于处理关系对象数据的API，资源提供了许多有用的功能。

创建资源

您可以使用自定义的ApiResource类来表示API的每个模型。

class Post extends Resource
{
    ...
}

可用的属性方法

类似于Eloquent模型，资源维护一个表示模型数据的内部键值对数组，并且有多种方式可以与这些属性交互。

$post = new Post(['id' => 1]);

$post->id = 1;

$id = $post->id;

$post->setAttribute('id', 1);

$id = $post->getAttribute('id');

$post->mergeAttributes(['id' => 1]); //Merge the new attributes into the existing attributes.
                                     //For existing keys, overwrite old values with new, but do not clear other keys.
                                     
$post->setAttributes(['id' => 1]); //Same effect as mergeAttributes.

$post->setAttributes(['id' => 1], true); //Clear all existing attributes.

属性转换

您可以将ApiResource类配置为在设置属性值时将该属性转换到其他类型。

可用的转换类型包括

在您的ApiResource类中声明属性转换类型。

class Post extends Resource
{
    protected $casts = [
        'id' => 'int',
        ...
    ];
}

请注意，如果远程API返回的数据类型正确，则声明转换是不必要的。尽管这不会造成任何伤害，但除非需要转换，否则您不需要声明转换类型。

当设置转换属性时，它的值将经过一个内部转换函数的处理，并将其作为正确的类型存储在内部。当您将来检索此对象时，它将以存储的类型返回。

铸造资源

为了自动将嵌套对象转换为正确的ApiResource类，请使用目标类名作为转换类型。当使用数据关联数组设置属性时，它将自动创建目标资源类的实例。

class Post extends Resource
{
    protected $casts = [
        'user' => 'User::class',
        ...
    ];
}

默认操作

默认情况下，该库为您的ApiResource类提供了基本的CRUD操作实现。通过实现适当的接口契约和使用提供的特质，将此行为包含在您的类中。

use Numenor\ApiWrapper\Resource\Contracts\All as AllContract;
use Numenor\ApiWrapper\Resource\Contracts\Create as CreateContract;
use Numenor\ApiWrapper\Resource\Contracts\Delete as DeleteContract;
use Numenor\ApiWrapper\Resource\Contracts\Get as GetContract;
use Numenor\ApiWrapper\Resource\Contracts\Update as UpdateContract;
use Numenor\ApiWrapper\Resource\Operations\All;
use Numenor\ApiWrapper\Resource\Operations\Create;
use Numenor\ApiWrapper\Resource\Operations\Delete;
use Numenor\ApiWrapper\Resource\Operations\Get;
use Numenor\ApiWrapper\Resource\Operations\Update;
use Numenor\ApiWrapper\Resource\Resource;

class Post extends ApiResource implements AllContract, CreateContract, DeleteContract, GetContract, UpdateContract
{
    use All, Create, Delete, Get, Update;
}

在底层，这些操作映射到上述的请求层。要执行查询，请调用可用的操作方法。

$posts = Post::all();           //Queries post.all Route (usually GET)
                                //returns Collection of Post Resources

$post = Post::create([...]);    //Queries post.create Route (usually POST) using provided attributes
                                //returns instance of Post Resource

$post = new Post([...]);
$post->store();                 //Queries post.create Route (usually POST) using current attributes
                                //Fills $post with returned data
                                
Post::delete(1);                //Queries post.delete (usually DELETE) Route with id = 1

$post = new Post(['id' => 1]);
$post->destroy();               //Queries post.delete Route (usually DELETE) with id = 1

$post = Post::get(1);           //Queries post.get Route (usually GET) with id = 1

$post = new Post(['id' => 1]);
$post = $post->fresh();         //Queries post.get Route (usually GET) with id = 1
                                //Returns new instance of Post Resource
                                
$post = new Post(['id' => 1]);
$post->refresh();               //Queries post.get Route (usually GET) with id = 1
                                //Fills $post with returned data
                                
Post::update(1, [...]);         //Queries post.update Route (usually PUT/PATCH) with id = 1 and current attributes

$post = new Post(['id' => 1]);
$post->updateAttributes([...]); //Sets $post attribues using provided attributes
                                //Queries post.update Route (usually PUT/PATCH) with id = 1 and current attributes
                                //Fills $post with returned data
                                
$post = new Post(['id' => 1]);
$post->saveChanges();           //Queries post.update Route (usually PUT/PATCH) with id = 1 and current attributes
                                //Fills $post with returned data

默认操作路由

默认情况下，每个操作假设一个特定的路由名称，该名称包含模型名称和操作名称。例如，Post::all假设一个名为post.all的路由。如果您需要为任何默认操作设置自定义路由名称，请设置您的ApiResource类上的相关属性。

class Post extends ApiResource implements AllContract, CreateContract, DeleteContract, GetContract, UpdateContract
{
    use All, Create, Delete, Get, Update;
    
    protected $allRoute = 'customAllRoute';
    protected $createRoute = 'customCreateRoute';
    protected $deleteRoute = 'customDeleteRoute';
    protected $getRoute = 'customGetRoute';
    protected $updateRoute = 'customUpdateRoute';
}

自定义操作

当然，您可以根据API的需求创建自己的自定义操作。只需定义所需的方法，并在其中调用Request::route方法。或者，如果您需要覆盖默认操作实现的默认行为，您应该自己实现契约方法，而不是引入提供默认行为的特质。