JMS Converter

Installation

composer require ecotone/jms-converter

Ecotone comes with integration with JMS Serializer and extending it with extra features.

Conversion Table

JMS Converter can handle conversions:

// conversion from JSON to PHP
application/json => application/x-php | {"productId": 1} => new OrderProduct(1)
// conversion from PHP to JSON
application-x-php => application/json | new OrderProduct(1) => {"productId": 1}
// conversion from XML to PHP
application/xml => application/x-php | <productId>1</productId> => new OrderProduct(1)
// conversion from PHP to XML
application-x-php => application/xml | new OrderProduct(1) => <productId>1</productId>
// conversion from JSON to PHP Array
application/json => application/x-php;type=array | {"productId": 1} => ["productId": 1]
// conversion from PHP Array to JSON
application/x-php;type=array => application/json | {"productId": 1} => ["productId": 1]
// conversion from XML to PHP Array
application/xml => application/x-php;type=array | <productId>1</productId> => ["productId": 1]
// conversion from PHP Array to XML
application/x-php;type=array => application/xml | ["productId": 1] => <productId>1</productId>

How to register Converter

JMS Convertermake use of Converters registered as PHP to PHP Converters in order to provide all the conversion types described in Conversion Table. You can read how to register new PHP to PHP Converter in Conversion section.

Example usage

Suppose we have endpoint with following Command:

/**
* @CommandHandler(inputChannelName="order.place")
*/
public function placeOrder(PlaceOrder $orderId)
{
// do something
}
class PlaceOrder
{
/**
* @var Uuid[]
*/
private array $productIds;
private ?string $promotionCode;
private bool $quickDelivery;
}

We do not need to add any metadata describing how to convert JSON to PlaceOrder PHP class. We already have it using type hints.

If use you PHP 7.3, you may describe types using docblocks.

The only thing, that we need is to add how to convert string to UUID. We do it using PHP to PHP Converter:

use Ecotone\Messaging\Annotation\Converter;
use Ecotone\Messaging\Annotation\ConverterClass;
/**
* @ConverterClass()
*/
class ExampleConverterService
{
/**
* @Converter()
*/
public function convert(string $data) : Uuid
{
return Uuid::fromString($data);
}
}

And that's enough. Whenever we will use string to UUID conversion or array of string to array of UUID. This converter will be automatically used. Now we can call Command Bus with JSON.

$this->commandBus->convertAndSend(
"order.place",
"application/json",
'{"productIds": ["104c69ac-af3d-44d1-b2fa-3ecf6b7a3558"], "promotionCode": "33dab", "quickDelivery": false}'
)

Customization

If you want to customize serialization or deserialization process, you may use of annotations on properties, just like it is describes in Annotation section in JMS Serializer.

class GetOrder
{
/**
* @SerializedName("order_id")
*/
private string $orderId;
}