nacosvel/feign

Implementing a Feign HTTP Client in PHP.

dev-main / 1.x-dev 2024-10-20 09:18 UTC

Requires

• php: >=8.0
• nacosvel/container-interop: ^1.0
• nacosvel/helper: ^1.0
• nacosvel/open-http: ^1.0

MIT

• jundayw

README

This is a PHP implementation inspired by the Feign client used in microservices architecture. It provides a lightweight HTTP client that integrates declarative web service calling with easy annotation-based APIs.

Features

• Declarative HTTP client interface
• Annotation-driven request handling
• Custom middleware for requests and responses
• Extensible with various mapping and middleware interfaces
• Support for microservices with FeignClient annotations

Development Plan

• Supports #[EnableFeignClients] annotation
• Supports #[Autowired] annotation
• Supports #[FeignClient] annotation
• Supports #[RequestMapping] annotation
• Supports #[RequestAttribute] annotation
• Supports #[Middleware] annotation
• Support custom response type
• Implement service discovery
• Support Without Interface Dependency

Installation

You can install the package via Composer:

composer require nacosvel/feign

Quick Start

It is super easy to get started with your first project.

Your project must support PSR-11.

Step 1 : Build a FeignRegistrar instance in the service provider of your project's container.

use Nacosvel\Feign\FeignRegistrar;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        FeignRegistrar::builder();
    }

}

Step 2 : Use #[Autowired] to inject properties.

use Nacosvel\Feign\Annotation\Autowired;
use Nacosvel\Feign\Contracts\AutowiredInterface;

class PostController implements AutowiredInterface
{
    #[Autowired]
    protected PostInterface|AutowiredInterface $post;

    public function index(): string
    {
        return $this->post->detail(name: 'nacosvel/feign', version: 'v1.0.0')->getRawContents();
    }

}

Step 3 : Define interfaces using #[FeignClient] and #[RequestMapping].

use Nacosvel\Feign\Annotation\FeignClient;
use Nacosvel\Feign\Annotation\RequestGetMapping;
use Nacosvel\Feign\Contracts\ServiceInterface;
use Nacosvel\Feign\Contracts\TransformationInterface;

#[FeignClient(name: 'debug', path: '/')]
interface PostInterface
{
    #[RequestGetMapping(path: '/get')]
    public function detail(string $name = '', string $version = ''): Post|ServiceInterface|TransformationInterface;

}

Advanced Usage

Step 1 : Construct a FeignRegistrar instance and set a custom Configuration class.

use Nacosvel\Feign\Annotation\EnableFeignClients;
use Nacosvel\Feign\FeignConfiguration;
use Nacosvel\Feign\FeignRegistrar;

#[EnableFeignClients(FeignConfiguration::class)]
class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        FeignRegistrar::builder($this->app);
    }

}

Step 2 : Inject properties and add Middleware.

use Nacosvel\Feign\Annotation\Autowired;
use Nacosvel\Feign\Annotation\Middleware;
use Nacosvel\Feign\Annotation\RequestMiddleware;
use Nacosvel\Feign\Annotation\ResponseMiddleware;
use Nacosvel\Feign\Contracts\AutowiredInterface;

class PostController implements AutowiredInterface
{
    #[Autowired]
    #[Middleware(Request::class, Response::class)]
    #[RequestMiddleware(Request::class)]
    #[ResponseMiddleware(Response::class)]
    protected PostInterface|AutowiredInterface $post;

    public function index(): string
    {
        return $this->post->detail(name: 'nacosvel/feign', version: 'v1.0.0')->getRawContents();
    }

}

Step 3 : More configurations for defining interfaces.

use Nacosvel\Feign\Annotation\FeignClient;
use Nacosvel\Feign\Annotation\RequestAttribute;
use Nacosvel\Feign\Annotation\RequestGetMapping;
use Nacosvel\Feign\Annotation\Middleware;
use Nacosvel\Feign\Annotation\RequestMiddleware;
use Nacosvel\Feign\Annotation\ResponseMiddleware;
use Nacosvel\Feign\Configuration\Client;
use Nacosvel\Feign\Configuration\Configuration;
use Nacosvel\Feign\Configuration\Fallback;
use Nacosvel\Feign\Support\Service;

#[FeignClient(
    name: 'debug',
    url: 'https://httpbin.org/',
    path: '/',
    configuration: Configuration::class,
    fallback: Fallback::class,
    client: Client::class
)]
#[Middleware(Request::class, Response::class)]
#[RequestMiddleware(Request::class)]
#[ResponseMiddleware(Response::class)]
interface PostInterface
{
    #[RequestGetMapping(path: '/get?id={id}', params: 'id=123456')]
    #[RequestAttribute(value: RequestAttribute::QUERY)]
    #[Middleware(Request::class, Response::class)]
    #[RequestMiddleware(Request::class)]
    #[ResponseMiddleware(Response::class)]
    public function detail(string $name = '', string $version = ''): Post|Service;

}

• To add custom Configuration, Fallback, and Client settings for FeignClient;
• using Middleware
• and specify request data attributes

Advanced Example

This implementation enhances Feign to support remote microservice calls without relying on defined interfaces. This feature allows for more flexible remote service invocation where you don't need to pre-define interfaces for each service.

use Nacosvel\Feign\Annotation\Autowired;
use Nacosvel\Feign\Annotation\RequestGetMapping;
use Nacosvel\Feign\Contracts\AutowiredInterface;
use Nacosvel\Feign\Contracts\ReflectiveInterface;

class PostController implements AutowiredInterface
{
    #[Autowired]
    #[FeignClient(name: 'debug', url: 'https://httpbin.org/', path: '/')]
    #[RequestGetMapping(path: '/uuid')]
    protected ReflectiveInterface $post;

    public function index(): string
    {
        return $this->post->uuid()->getRawContents();
    }

}

Documentation

Configuration Reference

public function getDefaultMethod(): string;

Get the default request method, which takes effect when not specified.

public function converters(): array;

Overriding this method can achieve custom response types.

public function getService(?string $name = null): string|array|null;

Randomly select a service from multiple service addresses.

Fallback Reference

public function __invoke(
        RequestInterface  $request,
        ResponseInterface $response,
        array             $options = [],
        Throwable         $previous = null
    ): ResponseInterface;

Exception responses can be uniformly handled here.

Client Reference

public function __invoke(): ClientInterface;

For a custom request instance, you need to return an instance of GuzzleHttp\ClientInterface.

License

Nacosvel Feign is made available under the MIT License (MIT). Please see License File for more information.