https://github.com/tebru/retrofit-php
Retrofit implementation in PHP. A REST client for PHP.
https://github.com/tebru/retrofit-php
Last synced: 23 days ago
JSON representation
Retrofit implementation in PHP. A REST client for PHP.
- Host: GitHub
- URL: https://github.com/tebru/retrofit-php
- Owner: tebru
- License: other
- Created: 2015-01-19T08:07:08.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2024-07-12T12:07:09.000Z (10 months ago)
- Last Synced: 2025-03-06T13:21:28.561Z (2 months ago)
- Language: PHP
- Size: 1.09 MB
- Stars: 157
- Watchers: 12
- Forks: 23
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
- awesome-php - Retrofit - A library to ease creation of REST API clients. (Table of Contents / HTTP)
- awesome-projects - Retrofit - A library to ease creation of REST API clients. (PHP / HTTP)
- awesome-php - Retrofit - A library to ease creation of REST API clients. (Table of Contents / HTTP)
- awesome-php-cn - Retrofit - 图书馆,以缓解创建REST API的客户. (目录 / HTTP客户端 HTTP Client)
- fucking-awesome-php - Retrofit - A library to ease creation of REST API clients. (Table of Contents / HTTP)
README
Retrofit PHP
============
[](https://travis-ci.org/tebru/retrofit-php)
[](https://scrutinizer-ci.com/g/tebru/retrofit-php/?branch=master)
[](https://scrutinizer-ci.com/g/tebru/retrofit-php/?branch=master)
[](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.