README

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.