[bc break] BusinessModel removal, Serializer addition

Author: Maks3w

CHANGELOG.md

@@ -7,14 +7,16 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 ## [Unreleased]
 ### Added
 - [Api] Add `getHttpStatusCode` to `ApiClientException` and `ApiServerException`. This method returns the response HTTP status code.
+- [Serializer] New component focused only in assist the conversion of PHP types to JSON compatible types.
 
 ### Changed
-- [BusinessModel] Remove constructors
+- [BusinessModel] This component has been replaced by [Serializer]
 - [Api] Change in `ApiClientException` and `ApiServerException` constructor signature.
 
 ### Deprecated
 
 ### Removed
+- [BusinessModel] This component has been replaced by [Serializer]
 
 ### Fixed
 

README.md

@@ -26,7 +26,7 @@ This SDK provides a tree of objects for guide you about to craft the checkout mo
 /*
  * Merchant model
  */
-$merchant = new Aplazame\BusinessModel\Merchant();
+$merchant = new stdClass();
 $merchant->confirmation_url = "/confirm"; // url that the JS client sent to confirming the order.
 $merchant->cancel_url = "/cancel";        // url that the customer is sent to if there is an error in the checkout.
 $merchant->success_url = "/success";      // url that the customer is sent to after confirming their order.
@@ -36,17 +36,17 @@ $merchant->checkout_url = "/checkout";    // url that the customer is sent to if
 /*
  * Article model
  */
-$article = new Aplazame\BusinessModel\Article();
-$article->id = "89793238462643383279";                                     // The article ID.
-$article->name = "Reloj en oro blanco de 18 quilates y diamantes";         // Article name.
-$article->url = "http://shop.example.com/product.html";                    // Article url.
-$article->image_url = "http://shop.example.com/product_image.png";         // Article image url.
-$article->quantity = 2;                                                    // Article quantity.
-$article->price = Aplazame\BusinessModel\Decimal::fromFloat(4020.00);      // Article price (tax is not included). (4,020.00 €)
-$article->description = "Movimiento de cuarzo de alta precisión";          // Article description.
-$article->tax_rate = Aplazame\BusinessModel\Decimal::fromFloat(21.00);     // Article tax rate. (21.00%)
-$article->discount = Aplazame\BusinessModel\Decimal::fromFloat(5.00);      // The discount amount of the article. (5.00 €)
-$article->discount_rate = Aplazame\BusinessModel\Decimal::fromFloat(2.00); // The rate discount of the article. (2.00 %)
+$article = new stdClass();
+$article->id = "89793238462643383279";                                  // The article ID.
+$article->name = "Reloj en oro blanco de 18 quilates y diamantes";      // Article name.
+$article->url = "http://shop.example.com/product.html";                 // Article url.
+$article->image_url = "http://shop.example.com/product_image.png";      // Article image url.
+$article->quantity = 2;                                                 // Article quantity.
+$article->price = Aplazame\Serializer\Decimal::fromFloat(4020.00);      // Article price (tax is not included). (4,020.00 €)
+$article->description = "Movimiento de cuarzo de alta precisión";       // Article description.
+$article->tax_rate = Aplazame\Serializer\Decimal::fromFloat(21.00);     // Article tax rate. (21.00%)
+$article->discount = Aplazame\Serializer\Decimal::fromFloat(5.00);      // The discount amount of the article. (5.00 €)
+$article->discount_rate = Aplazame\Serializer\Decimal::fromFloat(2.00); // The rate discount of the article. (2.00 %)
 
 // ... rest of articles in the shopping cart.
 
@@ -59,21 +59,21 @@ $articles = array( $article, ... );
 /*
  * Order model
  */
-$order = new Aplazame\BusinessModel\Order();
-$order->id = "28475648233786783165";                                          // Your order ID.
-$order->currency = "EUR";                                                     // Currency code of the order.
-$order->tax_rate = Aplazame\BusinessModel\Decimal::fromFloat(21.00);          // Order tax rate. (21.00%)
-$order->total_amount = Aplazame\BusinessModel\Decimal::fromFloat(4620.00);    // Order total amount. (4,620.00 €)
-$order->articles = $articles;                                                 // Articles in cart.
-$order->discount = Aplazame\BusinessModel\Decimal::fromFloat(160.00);         // The discount amount of the order. (160.00 €)
-$order->discount_rate = Aplazame\BusinessModel\Decimal::fromFloat(2.00);      // The rate discount of the order. (2.00 %)
-$order->cart_discount = Aplazame\BusinessModel\Decimal::fromFloat(0.50);      // The discount amount of the cart. (0.50 €)
-$order->cart_discount_rate = Aplazame\BusinessModel\Decimal::fromFloat(3.00); // The rate discount of the cart. (3.00 %)
+$order = new stdClass();
+$order->id = "28475648233786783165";                                       // Your order ID.
+$order->currency = "EUR";                                                  // Currency code of the order.
+$order->tax_rate = Aplazame\Serializer\Decimal::fromFloat(21.00);          // Order tax rate. (21.00%)
+$order->total_amount = Aplazame\Serializer\Decimal::fromFloat(4620.00);    // Order total amount. (4,620.00 €)
+$order->articles = $articles;                                              // Articles in cart.
+$order->discount = Aplazame\Serializer\Decimal::fromFloat(160.00);         // The discount amount of the order. (160.00 €)
+$order->discount_rate = Aplazame\Serializer\Decimal::fromFloat(2.00);      // The rate discount of the order. (2.00 %)
+$order->cart_discount = Aplazame\Serializer\Decimal::fromFloat(0.50);      // The discount amount of the cart. (0.50 €)
+$order->cart_discount_rate = Aplazame\Serializer\Decimal::fromFloat(3.00); // The rate discount of the cart. (3.00 %)
 
 /*
  * Customer address model
  */
-$customerAddress = new Aplazame\BusinessModel\Address();
+$customerAddress = new stdClass();
 $customerAddress->first_name = "John";                              // Address first name.
 $customerAddress->last_name = "Coltrane";                           // Address last name.
 $customerAddress->street = "Plaza del Angel nº10";                  // Address street.
@@ -88,24 +88,24 @@ $customerAddress->address_addition = "Cerca de la plaza Santa Ana"; // Address a
 /*
  * Customer model
  */
-$customer = new Aplazame\BusinessModel\Customer();
-$customer->id = "1618";                                                                             // Customer ID.
-$customer->email = "dev@aplazame.com";                                                              // The customer email.
-$customer->type = Aplazame\BusinessModel\Customer::TYPE_EXISTING;                                   // Customer type. Other options are: TYPE_GUEST and TYPE_NEW.
-$customer->gender = Aplazame\BusinessModel\Customer::GENDER_UNKNOWN;                                // Customer gender. Other options are: GENDER_MALE, GENDER_FEMALE and GENDER_NOT_APPLICABLE.
-$customer->first_name = "John";                                                                     // Customer first name.
-$customer->last_name = "Coltrane";                                                                  // Customer last name.
-$customer->birthday = DateTime::createFromFormat(DateTime::ISO8601, "1990-08-21T13:56:45+0000");    // Customer birthday.
-$customer->language = "es";                                                                         // Customer language preferences.
-$customer->date_joined = DateTime::createFromFormat(DateTime::ISO8601, "2014-08-21T13:56:45+0000"); // A datetime designating when the customer account was created.
-$customer->last_login = DateTime::createFromFormat(DateTime::ISO8601, "2014-08-27T19:57:56+0000");  // A datetime of the customer last login.
-$customer->address = $customerAddress;                                                              // Customer address.
+$customer = new stdClass();
+$customer->id = "1618";                                                                               // Customer ID.
+$customer->email = "dev@aplazame.com";                                                                // The customer email.
+$customer->type = 'existing';                                                                         // Customer type. Other options are: 'guest' and 'new'.
+$customer->gender = 'unknown';                                                                        // Customer gender. Other options are: 'male', 'female'and 'gender_not_aplicable'.
+$customer->first_name = "John";                                                                       // Customer first name.
+$customer->last_name = "Coltrane";                                                                    // Customer last name.
+$customer->birthday = Aplazame\Serializer\Date::fromDateTime(new DateTime("1990-08-21 13:56:45"));    // Customer birthday.
+$customer->language = "es";                                                                           // Customer language preferences.
+$customer->date_joined = Aplazame\Serializer\Date::fromDateTime(new DateTime("2014-08-21 13:56:45")); // A datetime designating when the customer account was created.
+$customer->last_login = Aplazame\Serializer\Date::fromDateTime(new DateTime("2014-08-27 19:57:56"));  // A datetime of the customer last login.
+$customer->address = $customerAddress;                                                                // Customer address.
 
 
 /*
  * Billing address model
  */
-$billingAddress = new Aplazame\BusinessModel\Address();
+$billingAddress = new stdClass();
 $billingAddress->first_name = "Bill";                        // Billing first name.
 $billingAddress->last_name = "Evans";                        // Billing last name.
 $billingAddress->street = "Calle de Las Huertas 22";         // Billing street.
@@ -121,28 +121,28 @@ $billingAddress->address_addition =  "Cerca de la pizzería"; // Billing address
 /*
  * Shipping info model
  */
-$shippingInfo = new Aplazame\BusinessModel\Address();
-$shippingInfo->first_name = "Django";                                           // Shipping first name.
-$shippingInfo->last_name = "Reinhard";                                          // Shipping last name.
-$shippingInfo->street = "Plaza del Angel nº10";                                 // Shipping street.
-$shippingInfo->city = "Madrid";                                                 // Shipping city.
-$shippingInfo->state = "Madrid";                                                // Shipping state.
-$shippingInfo->country = "ES";                                                  // Shipping country code.
-$shippingInfo->postcode = "28012";                                              // Shipping postcode.
-$shippingInfo->name = "Planet Express";                                         // Shipping name.
-$shippingInfo->price = Aplazame\BusinessModel\Decimal::fromFloat(5.00);         // Shipping price (tax is not included). (5.00 €)
-$shippingInfo->phone = "616123456";                                             // Shipping phone number.
-$shippingInfo->alt_phone = "+34917909930";                                      // Shipping alternative phone.
-$shippingInfo->address_addition = "Cerca de la plaza Santa Ana";                // Shipping address addition.
-$shippingInfo->tax_rate = Aplazame\BusinessModel\Decimal::fromFloat(21.00);     // Shipping tax rate. (21.00%)
-$shippingInfo->discount = Aplazame\BusinessModel\Decimal::fromFloat(1.00);      // The discount amount of the shipping. (1.00 €)
-$shippingInfo->discount_rate = Aplazame\BusinessModel\Decimal::fromFloat(2.00); // The rate discount of the shipping. (2.00 %)
+$shippingInfo = new stdClass();
+$shippingInfo->first_name = "Django";                                        // Shipping first name.
+$shippingInfo->last_name = "Reinhard";                                       // Shipping last name.
+$shippingInfo->street = "Plaza del Angel nº10";                              // Shipping street.
+$shippingInfo->city = "Madrid";                                              // Shipping city.
+$shippingInfo->state = "Madrid";                                             // Shipping state.
+$shippingInfo->country = "ES";                                               // Shipping country code.
+$shippingInfo->postcode = "28012";                                           // Shipping postcode.
+$shippingInfo->name = "Planet Express";                                      // Shipping name.
+$shippingInfo->price = Aplazame\Serializer\Decimal::fromFloat(5.00);         // Shipping price (tax is not included). (5.00 €)
+$shippingInfo->phone = "616123456";                                          // Shipping phone number.
+$shippingInfo->alt_phone = "+34917909930";                                   // Shipping alternative phone.
+$shippingInfo->address_addition = "Cerca de la plaza Santa Ana";             // Shipping address addition.
+$shippingInfo->tax_rate = Aplazame\Serializer\Decimal::fromFloat(21.00);     // Shipping tax rate. (21.00%)
+$shippingInfo->discount = Aplazame\Serializer\Decimal::fromFloat(1.00);      // The discount amount of the shipping. (1.00 €)
+$shippingInfo->discount_rate = Aplazame\Serializer\Decimal::fromFloat(2.00); // The rate discount of the shipping. (2.00 %)
 
 
 /*
  * Checkout model
  */
-$checkout = new Aplazame\BusinessModel\Checkout();
+$checkout = new stdClass();
 $checkout->toc = true;
 $checkout->merchant = $merchant;
 $checkout->order = $order;
@@ -154,7 +154,7 @@ $checkout->shipping = $shippingInfo;
 In your view you will need to put an snippet similar to this one.
 ```html
 <script>
-  aplazame.checkout( <?php echo json_encode($checkout->jsonSerialize()); ?> );
+  aplazame.checkout( <?php echo json_encode(Aplazame\Serializer\JsonSerializer::serializeValue($checkout)); ?> );
 </script>
 ```
 

src/BusinessModel/AbstractModel.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace Aplazame\Serializer;
+
+use DateTime;
+
+/**
+ * DateTime Type.
+ */
+class Date implements JsonSerializable
+{
+    /**
+     * @param DateTime $value
+     *
+     * @return self
+     */
+    public static function fromDateTime($value)
+    {
+        return new self($value->format(DateTime::ISO8601));
+    }
+
+    /**
+     * @var null|string
+     */
+    public $value;
+
+    /**
+     * @param string $value
+     */
+    public function __construct($value)
+    {
+        $this->value = $value;
+    }
+
+    /**
+     * @return DateTime
+     */
+    public function asDateTime()
+    {
+        $dateTime = DateTime::createFromFormat(DateTime::ISO8601, $this->value);
+
+        return $dateTime;
+    }
+
+    public function jsonSerialize()
+    {
+        return $this->value;
+    }
+}

src/BusinessModel/Address.php

@@ -1,11 +1,11 @@
 <?php
 
-namespace Aplazame\BusinessModel;
+namespace Aplazame\Serializer;
 
 /**
  * Decimal Type.
  */
-class Decimal extends AbstractModel
+class Decimal implements JsonSerializable
 {
     public static function fromFloat($value)
     {

src/BusinessModel/Article.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Aplazame\Serializer;
+
+interface JsonSerializable
+{
+    /**
+     * Serializes the object to a value that can be serialized natively by json_encode().
+     *
+     * @link http://php.net/manual/en/jsonserializable.jsonserialize.php
+     *
+     * @return mixed data which can be serialized by json_encode(), which is a value of any type other than a resource.
+     */
+    public function jsonSerialize();
+}

src/BusinessModel/Checkout.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace Aplazame\Serializer;
+
+use DateTime;
+use DomainException;
+
+/**
+ * This class assist to compose API models serializable as JSON for PHP versions prior to v5.4
+ */
+class JsonSerializer
+{
+    /**
+     * Important: This method does not return a JSON string, the return of this method must be encoded with `json_encode()`
+     *
+     * @param mixed $value
+     *
+     * @return mixed a value valid for to be used with native `json_encode()` function
+     */
+    public static function serializeValue($value)
+    {
+        if ($value instanceof JsonSerializable || $value instanceof \JsonSerializable) {
+            return $value->jsonSerialize();
+        }
+
+        if (is_object($value)) {
+            $value = (array) $value;
+        }
+
+        if (is_array($value)) {
+            foreach ($value as &$nestedValue) {
+                $nestedValue = self::serializeValue($nestedValue);
+            }
+
+            return $value;
+        }
+
+        if ($value instanceof DateTime || $value instanceof \DateTimeInterface) {
+            throw new DomainException('Please wrap your DateTime objects with Aplazame\Serializer\Date::fromDateTime');
+        }
+
+        if (is_float($value)) {
+            throw new DomainException('Please wrap your float values with Aplazame\Serializer\Decimal::fromFloat');
+        }
+
+        return $value;
+    }
+}

src/BusinessModel/Customer.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace Aplazame\Serializer;
+
+use PHPUnit_Framework_TestCase as TestCase;
+
+/**
+ * @covers Aplazame\Serializer\Date
+ */
+class DateTest extends TestCase
+{
+    public function testJsonSerialize()
+    {
+        $date = new Date('123');
+
+        self::assertSame('123', $date->jsonSerialize());
+    }
+
+    /**
+     * @dataProvider valuesProvider
+     */
+    public function testConversion($dateTime, $string)
+    {
+        $date = Date::fromDateTime($dateTime);
+
+        self::assertSame($string, $date->value, 'string value not match');
+        self::assertEquals($dateTime, $date->asDateTime(), 'datetime value not match');
+    }
+
+    public function valuesProvider()
+    {
+        return array(
+            // Description => [DateTime, string]
+            '1999-12-31' => array(new \DateTime('1999-12-31'), '1999-12-31T00:00:00+0100'),
+            '1999-12-31 23:59:59' => array(new \DateTime('1999-12-31 23:59:59'), '1999-12-31T23:59:59+0100'),
+        );
+    }
+}

src/BusinessModel/Merchant.php

@@ -1,11 +1,13 @@
 <?php
 
-namespace Aplazame\BusinessModel;
+namespace Aplazame\Serializer;
+
+use PHPUnit_Framework_TestCase as TestCase;
 
 /**
- * @covers Aplazame\BusinessModel\Decimal
+ * @covers Aplazame\Serializer\Decimal
  */
-class DecimalTest extends AbstractModelTestCase
+class DecimalTest extends TestCase
 {
     public function testJsonSerialize()
     {

src/BusinessModel/Order.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace Aplazame\Serializer;
+
+use DateTime;
+use PHPUnit_Framework_TestCase as TestCase;
+
+/**
+ * @covers Aplazame\Serializer\Decimal
+ */
+class JsonSerializerTest extends TestCase
+{
+    /**
+     * @dataProvider valuesProvider
+     */
+    public function testSerializeValue($value, $serialized)
+    {
+        self::assertEquals($serialized, json_encode(JsonSerializer::serializeValue($value)));
+    }
+
+    public function valuesProvider()
+    {
+        $date = Date::fromDateTime(new DateTime('2000-01-02 03:04:05'));
+        $decimal = Decimal::fromFloat(1.23);
+
+        return array(
+            // Description => [value, serialized]
+            'string' => array('foo', '"foo"'),
+            '[string]' => array(array('foo'), '["foo"]'),
+            '{string}' => array((object) array('a' => 'foo'), '{"a":"foo"}'),
+            'int' => array(1, 1),
+            '[int]' => array(array(1), '[1]'),
+            '{int}' => array((object) array('a' => 1), '{"a":1}'),
+            // 'float' is omitted as this type is forbidden
+            'Decimal' => array($decimal, '123'),
+            '[Decimal]' => array(array($decimal), '[123]'),
+            '{Decimal}' => array((object) array('a' => $decimal), '{"a":123}'),
+            'true' => array(true, 'true'),
+            '[true]' => array(array(true), '[true]'),
+            '{true}' => array((object) array('a' => true), '{"a":true}'),
+            'false' => array(false, 'false'),
+            '[false]' => array(array(false), '[false]'),
+            '{false}' => array((object) array('a' => false), '{"a":false}'),
+            // 'DateTime' is omitted as this type is forbidden
+            'Date' => array($date, '"2000-01-02T03:04:05+0100"'),
+            '[Date]' => array(array($date), '["2000-01-02T03:04:05+0100"]'),
+            '{Date}' => array((object) array('a' => $date), '{"a":"2000-01-02T03:04:05+0100"}'),
+        );
+    }
+}