Skip to content
master
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
bin
 
 
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

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.

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

License

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

You can’t perform that action at this time.