Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/tebru/retrofit-php

Retrofit implementation in PHP. A REST client for PHP.
https://github.com/tebru/retrofit-php

Last synced: about 2 months ago
JSON representation

Retrofit implementation in PHP. A REST client for PHP.

Lists

README 

        
Retrofit PHP

============



[![Build Status](https://travis-ci.org/tebru/retrofit-php.svg?branch=master)](https://travis-ci.org/tebru/retrofit-php)

[![Code Coverage](https://scrutinizer-ci.com/g/tebru/retrofit-php/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/tebru/retrofit-php/?branch=master)

[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/tebru/retrofit-php/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/tebru/retrofit-php/?branch=master)

[![SensioLabsInsight](https://insight.sensiolabs.com/projects/d2188bf8-8248-4df6-8bc5-8150fc0b8898/mini.png)](https://insight.sensiolabs.com/projects/d2188bf8-8248-4df6-8bc5-8150fc0b8898)



Retrofit is a type-safe REST client. It is blatantly stolen from

[square/retrofit](https://github.com/square/retrofit) and implemented in

PHP.



❗UPGRADE NOTICE❗

----------------



**Version 3 introduces many breaking changes. Please review the

[upgrade guide](docs/upgrade_2_3.md) 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.



```php

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.



```php

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



```php

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

```



The `Call` object is then used to execute the request synchronously

or asynchronously, returning a response.



```php

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



```php

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*



```bash

composer require tebru/retrofit-php

```



Please make sure you also install an http client.



```bash

composer require tebru/retrofit-php-http-guzzle6

```



Install a converter to handle more advanced request and response body

conversions.



```bash

composer require tebru/retrofit-php-converter-gson

```



### Documentation 



- [Installation](docs/installation.md)

- [Getting Started](docs/usage.md)

- [Advanced Usage](docs/advanced_usage.md)

- [Annotation Reference](docs/annotations.md)



License

-------



This project is licensed under the MIT license. Please see the `LICENSE` file

for more information.