tebru/retrofit-bundle

A Symfony2 bundle for the retrofit-php library.

v2.1.0 2016-08-17 17:27 UTC

Requires

• symfony/symfony: ~2.3|^3.0
• tebru/retrofit-php: ^2.0

Suggests

• guzzlehttp/guzzle: Required to make requests

MIT

• Nate Brunette

README

This Symfony2 bundle aims to provide an easy way to use the tebru/retrofit-php library. Please review the documentation for functionality.

Installation

composer require tebru/retrofit-bundle

As Retrofit does not include an http client, install Guzzle.

composer require guzzlehttp/guzzle

Add a line to your AppKernel.php

new Tebru\RetrofitBundle\TebruRetrofitBundle()

Usage

You will need to create providers for each API you want to consume. They should be created with the builder and return a RestAdapter. Here is an example:

<?php

namespace AppBundle;

use Tebru\Retrofit\Adapter\Rest\RestAdapter;

class FooBarRestAdapterProvider
{
    public static function get($baseUrl)
    {
        // setup additional dependencies like an http client here and use
        // the setters to add them to the builder
        
        // build the rest adapter
        return RestAdapter::builder()
            ->setBaseUrl($baseUrl)
            ->build();
    }
}

Create annotated interfaces. A simple example is shown below, more detailed examples are available here.

<?php

namespace AppBundle;

use Tebru\Retrofit\Annotation as Rest;

interface Foo
{
    /**
     * @Rest\GET("/get/{id}")
     */
    public function getFoo($id);
}

Everything else can be configured in your service definition. A yaml example is shown.

parameters:
    foo.class: AppBundle\Foo
    bar.class: AppBundle\Bar
    
services:
    # create a rest adapter
    foobar_rest_adapter:
        class: %tebru_retrofit.rest_adapter.class%
        factory: [AppBundle\FooBarRestAdapterProvider, get]
        arguments:
             - "https://foobar.com"
        
    # use the rest adapter to create clients
    # clients must be tagged with 'tebru_retrofit.register'
    foo_service:
        class: %foo.class%
        factory: [@foobar_rest_adapter, create]
        arguments: [%foo.class%]
        tags:
            - { name: tebru_retrofit.register }
            
    bar_service:
        class: %bar.class%
        factory: [@foobar_rest_adapter, create]
        arguments: [%bar.class%]
        tags:
            - { name: tebru_retrofit.register }

    # inject your client services anywhere
    baz:
        class: AppBundle\Baz
        arguments: [@foo_service, @bar_service]

Mocking

Because Retrofit uses interfaces, it's easy to create mock implementations if you do not want to hit a real API.

services:
    foo_service:
        class: %foo.class%
        factory: [@foobar_rest_adapter, create]
        arguments: ['AppBundle\MockFoo']
        tags:
            - { name: tebru_retrofit.register }

services:
    foo_service:
        class: %foo.class%
        factory: [@foobar_rest_adapter, create]
        arguments: [@mock_foo]
        tags:
            - { name: tebru_retrofit.register }

Take note of the arguments key in the above example. You may pass in a concrete class as a string or service to use that instead of the generated class. This is especially useful during development.