mapado/rest-client-sdk

Rest Client SDK for hydra API

Rest Client Sdk

PHP Rest Client SDK for JSON API., _(*1)

This client tries to avoid the complexity of implementing a custom SDK for every API you have. You just have to implements your model and a little configuration and it will hide the complexity for you., _(*2)

installation

composer require mapado/rest-client-sdk

Usage

Imagine you have those API endpoints:, _(*3)

• /v2/carts
• /v2/carts/{id}
• /v2/cart_items
• /v2/cart_items/{id}

You will need to have two entities, let's say:, _(*4)

• Foo\Bar\Model\Cart
• Foo\Bar\Model\CartItem

You will need to declare one Mapping containing your two ClassMetadata, _(*5)

Entity declarations

Configure an entity

Imagine the following entities:, _(*6)

namespace Acme\Foo\Bar;

use Mapado\RestClientSdk\Mapping\Attributes as Rest;

#[Rest\Entity(key: "carts")]
class Cart
{
   #[Rest\Id, Rest\Attribute(name: "@id", type: "string")]
  private $iri;

   #[Rest\Attribute(name: "status", type: "string")]
  private $status;

  #[Rest\Attribute(name: "created_at", type: "datetime")]
  private $createdAt;

  #[Rest\OneToMany(name: "cart_items", targetEntity: "CartItem")]
  private $cartItemList;

  // getters & setters ...
}

/**
 * @Rest\Entity(key="cart_items")
 */
#[Rest\Entity(key: "cart_items")]
class CartItem
{
  #[Rest\Id, Rest\Attribute(name: "@id", type: "string")]
  private $iri;

  #[Rest\Attribute(name: "number", type: "integer")]
  private $number;

  #[Rest\ManyToOne(name: "cart", targetEntity: "Cart")]
  private $cart;
}

Explanations

Entity definitions:, _(*7)

• key must be the key of your API endpoint

Attributes definition:, _(*8)

• name the name of the key in the API return format
• type type of the attribute

Relations definition:, _(*9)

• name the name of the key in the API return format
• targetEntity class name of the target entity

UnitOfWork

EntityRepository has a UnitofWork used for PUT and POST requests. It sends only changed data not the full model by comparing with the entity stored on GET request., _(*10)

Configuration

Using Symfony ?

There is a bundle to easily integrate this component: mapado/rest-client-sdk-bundle., _(*11)

Once configured, you can get a client like this:, _(*12)

$sdkClient = $this->get('mapado.rest_client_sdk.foo');
// or $sdkClient = $this->get('mapado.rest_client_sdk')->getSdkClient('foo');

Not using Symfony

You need to configure client this way:, _(*13)

use Mapado\RestClientSdk\Mapping;
use Mapado\RestClientSdk\RestClient;
use Mapado\RestClientSdk\SdkClient;
use Mapado\RestClientSdk\Mapping\Driver\AttributeDriver;

$restClient = new RestClient(
  new GuzzleHttp\Client(),
  'http://path-to-your-api.root'
);

// if you need to pass some headers to the client, you can do something like this:
// $restClient = new RestClient(
//   new GuzzleHttp\Client(['headers' => [ 'Authorization' => 'Bearer foobar' ]]),
//   'http://path-to-your-api.root'
// );
// See guzzle documentation for more informations

$annotationDriver = new AttributeDriver($cachePath, ($debug = true));

$mapping = new Mapping('/v2'); // /v2 is the prefix of your routes
$mapping->setMapping($annotationDriver->loadDirectory($pathToEntityDirectory));

$sdkClient = new SdkClient($restClient, $mapping);

Optionnal: create a SdkClientRegistry

use Mapado\RestClientSdk\SdkClientRegistry;

$registry = new Registry(['my-api' => $sdkClient]);

It can be easier to manager multiple clients. You can then call:, _(*14)

$sdkClient = $registry->getSdkClient('my-api');

// or

$sdkClient = $registry->getSdkClientForClass('\App\Entity\SomeEntity');

Accessing data

Fetching an entity / a list of entities

$repository = $sdkClient->getRepository('Acme\Foo\Bar\Cart');

// you can also access the repository by model key:
// $repository = $sdkClient->getRepository('cart');

// Find entity based on ID as defined in the entity by @Rest\Id
$cart = $repository->find(1);

// If you need to pass extra query parameters:
$cart = $repository->find(1, ['foo' => 'bar']); // will call /v2/carts/1?foo=bar

// Find all entities in the database
$cart = $repository->findAll();

// Find one entity based on the fielddefined in the function name (in this case <Name>)
$cart = $repository->findOneByName('username'); // will call /v2/carts?name=username

// Find one entity based on the criteria defined in the array
$cart = $repository->findOneBy(array(
  'name' => 'username',
  'date' => '1-1-2016',
)); // will call /v2/carts?name=username&date=1-1-2016

// To find all matches for the two examples above replace findOneByName() with findByName() and findOneBy() with findBy()

Creating a new instance

$cart = new \Acme\Foo\Bar\Cart();
$cart->setStatus('awaiting_payment');
$cart->setCreatedAt(new \DateTime());
$repository->persist($cart);

The persist operation will send a POST request with the serialized object to the API endpoint and return the newly created object, _(*15)

Updating an instance

$cart = $repository->find(13);
$cart->setStatus('payed');
$repository->update($cart);

The update operation will send a PUT request with the serialized object to the API endpoint (using the object Id) and return the updated object., _(*16)

Deleting an instance

$cart = $repository->find(13);
$repository->remove($cart);

The remove operation will send a DELETE request to the API endpoint using the object Id., _(*17)

Custom serialization

By default, when serializing, the SDK return only the Id to existing relations (like one-to-many)., _(*18)

You may want to serialize OneToMany relations though (imagine you have a Cart and you want to update linked cartItems), _(*19)

to do so, you can specify a $serializationContext in the persist and update method:, _(*20)

$repostory->update($cart, ['serializeRelations' => ['cartItems']]);

Extending the repository

If you need to extend the EntityRepository, you can just do something like that:, _(*21)

namespace Acme\Foo\Bar\Repository;

use Mapado\RestClientSdk\EntityRepository;

class CartRepository extends EntityRepository
{
  public function findOneByFoo($bar)
  {
    // generate the path to call
    $path = $data = $this->restClient->get($path); // ...
    return $this->sdk->getModelHydrator()->hydrate($data, $this->entityName); // hydrate for an entity, hydrateList for a list
  }
}

Update your entity Rest attribute to let the entity be aware of it's repository:, _(*22)

namespace Acme\Foo\Bar;

use Mapado\RestClientSdk\Mapping\Attributes as Rest;

#[Rest\Entity(key: "carts", repository: Acme\Foo\Bar\Repository\CartRepository::class)]
class Cart {

Handling exceptions

The SDK will throw an Exception if your API return something different than a 2xx or a 404 status code., _(*23)

You can see all the exceptions in this folder., _(*24)

If you need to access the body of the response from your API you can do something like this:, _(*25)

use Mapado\RestClientSdk\Exception\RestClientException;

try {
  // do something that will fail
} catch (\RestClientException $e) {
  $response = $e->getResponse(); // $response should be a Psr\Http\Message\ResponseInterface
  $body = $response->getBody();
  var_dump($body); // will dump your response body
}

PHPStan

rest-client-sdk does work well with PHPStan. See the related documentation., _(*26)

Hacking

This library is tested on multiple Symfony and PHP version thanks to composer-test-scenarios., _(*27)

But there is a conflict between ocramius/proxy-manager, composer 1&2, and php version., _(*28)

In order to sort this issue, it may be usefull to update scenarios with this command for scenario with php 7.4:, _(*29)

docker run --rm --interactive --tty --volume $PWD:/app -w "/app" roadiz/php74-runner composer scenario:update

This should be resolved with ocramius/proxy-manager#2.9.0 but it requires composer 2 absolutely, and we (Mapado) are not ready for this., _(*30)

The path to fix this is to bump a major version with "ocramius/proxy-manager": "^2.9.0" that requires composer^2, _(*31)