tebru / retrofit-php
Retrofit for PHP - A type-safe PHP REST client.
Installs: 130 666
Dependents: 7
Suggesters: 0
Security: 0
Stars: 156
Watchers: 12
Forks: 23
Open Issues: 5
Requires
- php: >= 7.1
- guzzlehttp/psr7: ^1.0
- nikic/php-parser: ~3.0.6|^4.0
- symfony/cache: ^3.3|^4.0|^5.0
- symfony/console: ^3.0|^4.0|^5.0
- tebru/doctrine-annotation-reader: ^0.3.0
- tebru/php-type: ^0.1.1
Requires (Dev)
- mikey179/vfsstream: ^1.6
- phpunit/phpunit: ^7.3
Suggests
- guzzlehttp/guzzle: Required to make requests
- dev-master
- v3.3.1
- v3.3.0
- v3.2.1
- v3.2.0
- v3.1.0
- v3.0.3
- v3.0.2
- v3.0.1
- v3.0.0
- v3.0.0-rc2
- v3.0.0-rc1
- v2.x-dev
- v2.9.0
- v2.8.3
- v2.8.2
- v2.8.1
- v2.8.0
- v2.8.0-rc4
- v2.8.0-rc3
- v2.8.0-rc2
- v2.8.0-rc1
- v2.7.0
- v2.6.1
- v2.6.0
- v2.5.5
- v2.5.4
- v2.5.3
- v2.5.2
- v2.5.1
- v2.5.0
- v2.4.0
- v2.3.0
- v2.2.0
- v2.1.0
- v2.0.6
- v2.0.5
- v2.0.4
- v2.0.3
- v2.0.2
- v2.0.1
- v2.0.0
- v1.2.1
- v1.2.0
- v1.1.0
- v1.0.0
- v0.3.5
- v0.3.4
- v0.3.3
- v0.3.2
- v0.3.1
- v0.3.0
- v0.2.1
- v0.2.0
- v0.1.3
- v0.1.2
- v0.1.1
- v0.1.0
- dev-simpler-requests
This package is auto-updated.
Last update: 2024-10-29 03:33:24 UTC
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
License
This project is licensed under the MIT license. Please see the LICENSE
file
for more information.