README

Maestro - Http Client for PHP

A light client built on top of 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"

If you are using laravel

Service Provider (Optional on Laravel 5.5)

Once Composer has installed or updated your packages you need add aliases or register you packages into Laravel. Open up config/app.php and find the aliases key and add:

'Maestro' => Maestro\Laravel\MaestroLaravelFacade::class,

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:

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

You can choose assoc return. The return will be an array.

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

Supported Methods

GET ->get()
POST ->post()
PUT ->put()
PATCH ->patch()
DELETE ->delete()
COPY ->copy()
HEAD ->head()
OPTIONS ->options()
LINK ->link()
UNLINK ->unlink()
PURGE ->purge()
LOCK ->lock()
UNLOCK ->unlock()
PROPFIND ->propfind()
VIEW ->view()

marcus-campos / maestro

Maintainers

Details