README

Valuable partners:

Before installation

If you are using older php then version 7.2 download with command

$ composer require fabricio872/api-modeller:^1.0

Installation

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

Step 1: Download the Library

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

Step 2: Initialize library

Create new instance of Fabricio872\ApiModeller\Modeller. For legacy project is easiest to implement it with Singleton pattern which gives you instance anywhere where you call it as described here.

create new class for client adapter of your choice in this example we use GuzzleHttp/Client

use Fabricio872\ApiModeller\ClientAdapter\ClientInterface;
use GuzzleHttp\Client;

class GuzzleClient implements ClientInterface
{
    private Client $client;

    public function __construct()
    {
        $this->client = new Client();
    }

    public function request(string $method, string $endpoint, array $options): string
    {
        return $this->client->request($method, $endpoint, $options)->getBody()->getContents();
    }
}

create new class somewhere in your composer autoload directory with name Modeller and add your namespace

use Doctrine\Common\Annotations\AnnotationReader;
use Fabricio872\ApiModeller\ClientAdapter\Symfony;
use Symfony\Component\HttpClient\HttpClient;
use Twig\Environment;
use Twig\Loader\FilesystemLoader;

class Modeller
{
    /** @var \Fabricio872\ApiModeller\Modeller */
    private static $modeller;

    public static function get()
    {
        if (!isset(self::$modeller)) {
            $reader = new AnnotationReader();

            $client = new GuzzleClient(); // class we have created above

            $loader = new FilesystemLoader();
            $twig = new Environment($loader, [
                'cache' => '/path/to/compilation_cache',
            ]);

            self::$modeller = new \Fabricio872\ApiModeller\Modeller(
                $reader,
                $client,
                $twig
            );
        }
        return self::$modeller;
    }
}

Usage

This lib 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.

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;
}

Calling the API

Instance of class Fabricio872\ApiModeller\Modeller can be received like this if configuration was as described here

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

    public function index()
    {
        var_dump(Modeller::get()->getData(
            Repo::new(Users::class)
                ->setOptions([
                    "query" => [
                        "page" => 2
                    ]
                ])
        ));
    }

Notice setOptions have alternative function addOptions which merges existing and provided options

Notice that Modeller::get() must have correct namespace pointing to class from configuration section

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

    public function index(Modeller $modeller)
    {
        var_dump(Modeller::get()->getData(
            Repo::new(Users::class)
                ->setParameters([
                    "id" => 2
                ])
                ->setIdentifier("single")
        ));
    }

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

Model Title

Model title is useful if your data arrives covered in another object like this

{
  "data": [
    {
      "myData": "data"
    }
  ]
}

in this case your model would have title data to map your model variable directly to myData and not to data object:

// src/ApiModels/Data.php

use Fabricio872\ApiModeller\Annotations\Resource;
use Fabricio872\ApiModeller\Annotations\ModelTitle;

/**
 * @Resource(
 *     endpoint="{{api_url}}/api/data",
 *     method="GET",
 *     type="json",
 *     options={
 *          "headers"={
 *              "accept"= "application/json"
 *          }
 *     }
 * )
 * @ModelTitle("data")
 */
class Data
{
    public $myData;
}

you can also nest ModelTitles to array with multiple options for each title for example:

/**
 * @ModelTitle("data", {"subTitle1", "subTitle2"})
 */

this will search in incoming response for data and in it for either subTitle1 or subTitle2

fabricio872 / api-modeller

Maintainers

Details