Retrofit implementation in PHP. A REST client for PHP.
natebrunette Adding ability to specify cache adapter
Additionally modified default cache to use php file cache

Signed-off-by: Nate Brunette <>
Latest commit a4e2113 Apr 2, 2018

Retrofit PHP

Build Status Code Coverage Scrutinizer Code Quality SensioLabsInsight

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


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


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 = RetrofitBuilder::builder()
    ->setHttpClient(new Guzzle6HttpClient(new Client())) // requires a separate library
    ->addConverterFactory(new GsonConverterFactory(Gson::builder()->build())) // requies a separate library
$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

    function(Response $response) { }, // response callback (optional)
    function(Throwable $throwable) { } // error callback (optional)

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



This project is licensed under the MIT license. Please see the LICENSE file for more information.