README

The RestClient package is a PHP library that simplifies working with RESTful APIs. It provides an easy way to create and configure HTTP requests, handle responses, and convert JSON data into PHP objects. This documentation will guide you through the main features and usage of the RestClient package.

Whether you're building web services or powerful API clients in your applications, the RestClient package streamlines the process of interacting with RESTful APIs in PHP. It allows you to focus on your application's functionality rather than the intricacies of making HTTP requests and processing responses.

Installation

You can install the RestClient package via Composer:

composer require brzuchal/rest-client

Documentation

• Basic usage
• Builder
• Entity Classes
• Custom Handling
• Integrating with Symfony
• Integrating with Laravel
• Service Factory (Experimental)

Getting Started

To get started with the RestClient package, create a RestClient instance. You can use the RestClient::create method to do this:

use Brzuchal\RestClient\RestClient;

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

Now you have a RestClient instance ready to make HTTP requests.

Making Requests

The RestClient package allows you to create various types of HTTP requests, such as GET, POST, PUT, DELETE, etc. You can use the RestClient instance to create request objects for these methods.

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

Error Handling

$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 Framework

Configuration

To use the RestClient package in a Symfony application, follow these steps:

1. Register the bundle in your Symfony application by adding the RestClientBundle to the config/bundles.php file:

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

2. By default, the RestClientBundle uses Symfony configuration to define REST client services. Create a configuration file (e.g., rest_client.yaml) in the config/packages directory of your Symfony project. Here's an example configuration:

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

   In this configuration, we define a my_rest_client service with a base URI of https://api.example.com/. You can add more client configurations as needed.

Example Symfony Controller

Here's an example Symfony controller that uses the RestClient package to make API requests:

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 Framework

Configuration

To use the RestClient package in a Laravel application, follow these steps:

1. Create a configuration file for the RestClient package using the following Artisan command:

   php artisan vendor:publish --tag=config

   This command will generate a rest_client.php configuration file in the config directory of your Laravel project.

   NOTE!: Laravel 8 and later versions should automatically discover the package. For older Laravel versions, you may need to register the service provider manually.

2. The configuration for the RestClient package in Laravel is similar to Symfony. Here's an example configuration file (config/rest_client.php):

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

   In this configuration, we define a my_rest_client service with a base URI of https://api.example.com/. You can add more client configurations as needed.

Example Laravel Controller

Here's an example Laravel controller that uses the RestClient package to make API requests:

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(),
        );
    }
}

License

The RestClient package is open-source software licensed under the MIT License. See the LICENSE file for more information.