README

RestClient包是一个PHP库，简化了与RESTful API的交互。它提供了一种简单的方法来创建和配置HTTP请求，处理响应，并将JSON数据转换为PHP对象。本文档将指导您了解RestClient包的主要功能和用法。

无论是构建网络服务还是应用中的强大API客户端，RestClient包都简化了PHP中与RESTful API交互的过程。它使您能够专注于应用程序的功能，而不是HTTP请求的复杂性以及响应的处理。

安装

您可以通过Composer安装RestClient包

composer require brzuchal/rest-client

文档

• 基本用法
• 构建器
• 实体类
• 自定义处理
• 与Symfony集成
• 与Laravel集成
• 服务工厂（实验性）

入门

要开始使用RestClient包，创建一个RestClient实例。您可以使用RestClient::create方法来这样做

use Brzuchal\RestClient\RestClient;

$client = RestClient::create('https://api.example.com/');

现在您有一个准备好的RestClient实例，可以发起HTTP请求。

发起请求

RestClient包允许您创建各种类型的HTTP请求，如GET、POST、PUT、DELETE等。您可以使用RestClient实例来创建这些方法请求对象。

$response = $client->get('/todos/1')
    ->retrieve();
$data = $response->toArray();
$todo = $response->toEntity(Todo::class);

错误处理

$response = $client->get('/todos/1')
    ->retrieve();

$response->onStatus(404, function ($response) {
    throw new NotFoundException('Resource not found');
});

$response->onStatus(500, function ($response) {
    throw new ServerErrorException('Server error');
});

Symfony框架

配置

要在Symfony应用程序中使用RestClient包，请按照以下步骤操作

1. 将bundle注册到您的Symfony应用程序中，通过在config/bundles.php文件中添加RestClientBundle

   // config/bundles.php
   
   return [
       // ...
       Brzuchal\RestClient\RestClientBundle::class => ['all' => true],
   ];

2. 默认情况下，RestClientBundle使用Symfony配置来定义REST客户端服务。在您的Symfony项目config/packages目录中创建一个配置文件（例如，rest_client.yaml）。以下是一个示例配置

   # config/packages/rest_client.yaml
   
   rest_client:
       clients:
           my_rest_client:
               base_uri: 'https://api.example.com/'

   在这个配置中，我们定义了一个具有基础URI https://api.example.com/ 的my_rest_client服务。根据需要，您可以添加更多客户端配置。

示例Symfony控制器

以下是一个使用RestClient包发起API请求的示例Symfony控制器

use Brzuchal\RestClient\RestClient;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\DependencyInjection\Attribute\Autowire;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Contracts\HttpClient\HttpClientInterface;

class TodoController extends AbstractController
{
    public function index(
        #[Autowire(service: 'rest_client.default')]
        RestClientInterface $client,
    ): JsonResponse {
        return $this->json($client->get('/todos')->toArray());
    }
}

Laravel框架

配置

要在Laravel应用程序中使用RestClient包，请按照以下步骤操作

1. 使用以下Artisan命令为RestClient包创建配置文件

   php artisan vendor:publish --tag=config

   此命令将在您的Laravel项目config目录中生成一个rest_client.php配置文件。

   注意！：Laravel 8及更高版本应自动发现该包。对于旧版本Laravel，您可能需要手动注册服务提供者。

2. Laravel中RestClient包的配置类似于Symfony。以下是一个示例配置文件（config/rest_client.php）

   return [
       'clients' => [
           'my_rest_client' => [
               'base_uri' => 'https://api.example.com/',
           ],
       ],
   ];

   在这个配置中，我们定义了一个具有基础URI https://api.example.com/ 的my_rest_client服务。根据需要，您可以添加更多客户端配置。

示例Laravel控制器

以下是一个使用RestClient包发起API请求的示例Laravel控制器

namespace App\Http\Controllers;

use Brzuchal\RestClient\RestClient;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Http;

class TodoController extends Controller
{
    public function index(Request $request): JsonResponse
    {
        return response()->json(
            app('rest_client.default')->get('/todos')->toArray(),
        );
    }
}

许可证

RestClient包是开源软件，MIT许可证下发布。有关更多信息，请参阅LICENSE文件。