README

Valuable partners:

Installation

Make sure Composer is installed globally, as explained in the installation chapter of the Composer documentation.

Applications that use Symfony Flex

Open a command console, enter your project directory and execute:

$ composer require fabricio872/api-modeller-bundle

Applications that don't use Symfony Flex

Step 1: Download the Bundle

Open a command console, enter your project directory and execute the following command to download the latest stable version of this bundle:

$ composer require fabricio872/api-modeller-bundle

Step 2: Enable the Bundle

Then, enable the bundle by adding it to the list of registered bundles in the config/bundles.php file of your project:

// config/bundles.php

return [
    // ...
    Fabricio872\ApiModeller\ApiModellerBundle::class => ['all' => true],
];

Usage

This bundle uses models with Annotations similar to Doctrine Entities.

Usually they are in a directory src/ApiModels but they are not required to be there as long as they have correct namespace

Example model with single Resource

This is example of a model for receiving list of users from some API

// src/ApiModels/Users.php

use Fabricio872\ApiModeller\Annotations\Resource;

/**
 * @Resource(
 *     endpoint="{{api_url}}/api/users",
 *     method="GET",
 *     type="json",
 *     options={
 *          "headers"={
 *              "accept"= "application/json"
 *          }
 *     }
 * )
 */
class Users
{
    public $page;
    public $per_page;
    public $total;
    public $total_pages;
    public $data;
}

endpoint parameter is endpoint which will be called.

The variable {{api_url}} is Twig global variable configured in twig config (example in Global variables configuration section)

method parameter is method with which the request will be done

default: GET

type parameter defines format of the received data

currently supported: json, "xml'

default: json

options parameter is array that is directly passed (but can be altered as explained in setOptions section) to symfony/http-client request method as 3. parameter so use this documentation

Example model with multiple Resources

To define multiple resources you need to wrap multiple Resource annotation into single Resources annotation with identifier at beginning. This identifier is then used while calling this endpoint as described in section setIdentifier

// src/ApiModels/Users.php

use Fabricio872\ApiModeller\Annotations\Resource;
use Fabricio872\ApiModeller\Annotations\Resources;

/**
 * @Resources({
 *      "multiple"= @Resource(
 *          endpoint="{{api_url}}/api/users",
 *          method="GET",
 *          type="json",
 *          options={
 *              "headers"={
 *                  "accept"= "application/json"
 *              }
 *          }
 *      ),
 *      "single"= @Resource(
 *          endpoint="{{api_url}}/api/users/{{id}}",
 *          method="GET",
 *          type="json",
 *          options={
 *              "headers"={
 *                  "accept"= "application/json"
 *              }
 *          }
 *      ),
 * })
 */
class Users
{
    public $page;
    public $per_page;
    public $total;
    public $total_pages;
    public $data;
}

Global variables configuration

# config/packages/twig.yaml

twig:
    ...
    globals:
        api_url: 'https://reqres.in'

Calling the API

This bundle can be initialized from symphony's dependency container so in your controller you can call it like this:

Calling with single resource

This controller dumps model or collection of models form this example with namespace Users::class and sets query parameter page to 2

// src/Controller/SomeController.php


    /**
     * @Route("/", name="some_controller")
     */
    public function index(Modeller $modeller): Response
    {
        dump($modeller->getData(
            Repo::new(Users::class)
                ->setOptions([
                    "query" => [
                        "page" => 2
                    ]
                ])
        ));

        return $this->render('some_controller/index.html.twig', [
            'controller_name' => 'SomeController',
        ]);
    }

Calling with multiple resources

This controller dumps model or collection of models form this example with namespace Users::class and fills the {{id}} variable from model with number 2

noticed that now method setIdentifier is required

// src/Controller/SomeController.php


    /**
     * @Route("/", name="some_controller")
     */
    public function index(Modeller $modeller): Response
    {
        dump($modeller->getData(
            Repo::new(Users::class)
                ->setParameters([
                    "id" => 2
                ])
                ->setIdentifier("single")
        ));

        return $this->render('some_controller/index.html.twig', [
            'controller_name' => 'SomeController',
        ]);
    }

The modeller accepts Repo object which requires namespace of model you want to build and has optional setters:

setOptions()

setParameters()

setIdentifier()

setOptions

This method accepts array of options that will be merged with options configured in a model (and will override overlapped parameters) to symfony/http-client request method as 3. parameter so use this documentation

setParameters

This method accepts array and sets twig variables (same as if you render a template but here the template is endpoint parameter from model) to url configuration and can override global twig variables

setIdentifier

This method is required in case when you use multiple Resources for single model as shown in this example

fabricio872 / api-modeller-bundle

Maintainers

Details