tebru/retrofit-php

Retrofit for PHP - A type-safe PHP REST client.

Retrofit PHP

, _(*1)

Retrofit is a type-safe REST client. It is blatantly stolen from square/retrofit and implemented in PHP., _(*2)

❗UPGRADE NOTICE❗

Version 3 introduces many breaking changes. Please review the upgrade guide before upgrading., _(*3)

Overview

The following is for version 3, please check out the corresponding tag for version 2 documentation, _(*4)

Retrofit allows you to define your REST API with a simple interface. The follow example will attempt to display a typical use-case, but requires two additional libraries. The first uses Guzzle to make http requests as Retrofit does not ship with any default way to make network requests. The second uses a serializer (Gson) to hook into Retrofit's Converter functionality. This allows for automatic serialization of request bodies and deserialization of response bodies., _(*5)

interface GitHubService
{
    /**
     * @GET("/users/{user}/list")
     * @Path("user")
     * @ResponseBody("App\GithubService\ListRepo")
     * @ErrorBody("App\GitHubService\ApiError")
     */
    public function listRepos(string $user): Call;
}

Annotations are used to configure the endpoint. Then, the Retrofit class generates a working implementation of the service interface., _(*6)

$retrofit = Retrofit::builder()
    ->setBaseUrl('https://api.github.com')
    ->setHttpClient(new Guzzle6HttpClient(new Client())) // requires a separate library
    ->addConverterFactory(new GsonConverterFactory(Gson::builder()->build())) // requies a separate library
    ->build();

$gitHubService = $retrofit->create(GitHubService::class);

Our newly created service is capable of making GET requests to /users/{user}/list, which returns a Call object., _(*7)

$call = $gitHubService->listRepos('octocat');

The Call object is then used to execute the request synchronously or asynchronously, returning a response., _(*8)

$response = $call->execute();

// or

$call->enqueue(
    function(Response $response) { }, // response callback (optional)
    function(Throwable $throwable) { } // error callback (optional)
);
$call->wait();

You can then check to see if the request was successful and get the deserialized response body., _(*9)

if (!$response->isSuccessful()) {
    throw new ApiException($response->errorBody());
}

$responseBody = $response->body();

Usage examples are referenced from Square's documentation, _(*10)

Installation & Usage

Retrofit 3 requires PHP 7.1, _(*11)

composer require tebru/retrofit-php

Please make sure you also install an http client., _(*12)

composer require tebru/retrofit-php-http-guzzle6

Install a converter to handle more advanced request and response body conversions., _(*13)

composer require tebru/retrofit-php-converter-gson

Documentation

• Installation
• Getting Started
• Advanced Usage
• Annotation Reference

License

This project is licensed under the MIT license. Please see the LICENSE file for more information., _(*14)