Retrofit PHP

Retrofit is a type-safe REST client. It is blatantly stolen from square/retrofit and implemented in PHP.

❗UPGRADE NOTICE❗

Version 3 introduces many breaking changes. Please review the upgrade guide before upgrading.

Overview

The following is for version 3, please check out the corresponding tag for version 2 documentation

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.

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.

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

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

The Call object is then used to execute the request synchronously or asynchronously, returning a response.

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

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

$responseBody = $response->body();

Usage examples are referenced from Square's documentation

Installation & Usage

Retrofit 3 requires PHP 7.1

composer require tebru/retrofit-php

Please make sure you also install an http client.

composer require tebru/retrofit-php-http-guzzle6

Install a converter to handle more advanced request and response body conversions.

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.