Maestro

A light client built on Guzzle that simplifies the way you work with micro-services. It is based on method definitions and parameters for your URLs.

Requirements

PHP 7.0 or greater
Composer

Installation

Composer way

composer require marcus-campos/maestro

Or add manually to your composer.json:

"marcus-campos/maestro": "dev-master"

Running the test suite

Using Docker

docker build -t maestro .
docker run maestro

Basic Usage


<?php

namespace App\Platform\V1\Domains\App;


use Maestro\Rest;

class Products extends Rest
{
    protected $url = 'https://mydomain.com/api/v1/'; // http://mydomain.com:9000/api/v1

    /**
     * @return array
     */
    public function getProducts()
    {
        return $this
            ->get()
            ->setEndPoint('products')
            ->headers([
                'Content-Type' => 'application/json'
            ])
            ->body( [
                'ids' => [1,2,3,4,5]
            ])
            ->send()
            ->parse();
    }

    /**
     * @return array
     */
    public function getProduct()
    {
        return $this
            ->get()
            ->setEndPoint('product')
            ->send()
            ->parse();
    }

    /**
     * @return array
     */
    public function postNotification()
    {
        return $this
            ->get()
            ->setEndPoint('package/')
            ->headers([
                'Content-Type' => 'application/json'
            ])
            ->body([
                'message' => 'Tanks for all.',
                'id' => [1]
            ])
            ->sendAsync()
            ->wait()
            ->parse()
            ->name;
    }
}

Response data

By default the returns is a StdClass, which gives you the freedom to treat the data the way you want. See the examples:

The way of Laravel

 public function getProducts()
 {
     return collect(
         $this
         ->get()
         ->setEndPoint('products')
         ->headers([
             'Content-Type' => 'application/json'
         ])
         ->body([
             'ids' => [1,2,3,4,5]
         ])
         ->send()
         ->parse());
 }

You can choose assoc return.

Assoc way

 public function postNotification()
 {
     return $this
         ->get()
         ->setEndPoint('package/')
         ->headers([
             'Content-Type' => 'application/json'
         ])
         ->body([
             'message' => 'Tanks for all.',
             'id' => [1]
         ])
         ->send()
         ->assoc()
         ->parse()['name'];
 }

Get response status

 public function postNotification()
 {
     $response = $this
          ->get()
          ->setEndPoint('package/')
          ->headers([
              'Content-Type' => 'application/json'
          ])
          ->body([
              'message' => 'Tanks for all.',
              'id' => [1]
          ])
          ->send();

          if($response->status() === 200) {
                $db->save($response->parse()); // any code to work with response body
          }
 }

Other way

 public function postNotification()
 {
     return $this
         ->get()
         ->setEndPoint('package/')
         ->headers([
             'Content-Type' => 'application/json'
         ])
         ->body([
             'message' => 'Tanks for all.',
             'id' => [1]
         ])
         ->sendAsync()
         ->wait()
         ->parse()
         ->name;
 }

Response Caching

If the response of the microservice is likely to remain the same for periods of time, you may want to be polite and reduce requests to the service by caching the responses. This is also useful if the service imposes a request limit and you do not want to breach it with unnecessary calls.

You can enable caching using the ->cachable() method which accepts a period of time in seconds as it's only parameter. The following example will hold the response for 60 seconds before making the request again:

$request = new \Maestro\Rest();

$result = $request
    ->get()
    ->setUrl('http://api.example.com')
    ->setEndPoint('/horses')
    ->cachable(60)
    ->send()
    ->parse();

Caching functionality is dependent on the PHP package, APCu being installed and enabled in the environment.

Note: If you are developing and accidentally cache a bad response for a long period of time, simply make a request with ->cachable(0) to overwrite previous caches.

Senders

You can send in 2 ways: synchronous or asynchronous. See the examples:

Synchronous: ->send()

 public function getProducts()
 {
     return collect($this
         ->get()
         ->setEndPoint('products')
         ->headers([
             'Content-Type' => 'application/json'
         ])
         ->body([
             'ids' => [1,2,3,4,5]
         ])
         ->send()
         ->parse());
 }

Asynchronous: ->sendAsync()

 public function postNotification()
 {
     return $this
         ->get()
         ->setEndPoint('package/')
         ->headers([
             'Content-Type' => 'application/json'
         ])
         ->body([
             'message' => 'Tanks for all.',
             'id' => [1]
         ])
         ->sendAsync()
         ->wait()
         ->parse()
         ->name;
 }