add binding structure

Author: fetzi

readme.md

@@ -12,7 +12,7 @@ composer require karriere/json-decoder
 ```
 
 ## Usage
-By default all not defined fields of the input json will be stored in a class property with the same name.
+By default all public properties of the class will be inspected. For all properties that have a json key with the same name the according value will be set.
 
 ### A simple example
 Assume you have a class `Person` that looks like this:
@@ -28,10 +28,98 @@ The following code will transform the given json data into an instance of `Perso
 ```php
 $jsonDecoder = new JsonDecoder();
 $jsonData = '{"id": 1, "name": "John Doe"}';
-$arrayData = json_decode($jsonData, true);
 
-$person = $jsonDecoder->decode($arrayData, Person::class);
+$person = $jsonDecoder->decode($jsonData, Person::class);
+```
+
+### Defining a Transformer
+Let's extend the previous example with a property called address. This address field should contain an instance of `Address`.
+```php
+class Person {
+    public $id;
+    public $name;
+    public $address;
+}
+```
+
+To be able to transform the address data into an `Address` class object you need to define a transformer for `Person`:
+
+The transformer interface defines two methods:
+
+* register: here you register your field, array, alias and callback bindings
+* transforms: gives you the full qualified class name e.g.: Your\Namespace\Class
+```php
+class PersonTransformer implements Transformer {
+    
+    public function register(ClassBindings $classBindings)
+    {
+        $classBindings->register(new FieldBinding('address', 'address', Address::class);
+    }
+    
+    public function transforms()
+    {
+        return Person::class;
+    }
+}
+```
+
+After registering the transformer the `JsonDecoder` will use the defined transformer:
+```php
+$jsonDecoder = new JsonDecoder();
+$jsonDecoder->register(new PersonTransformer());
+
+$jsonData = '{"id": 1, "name": "John Doe"}';
+
+$person = $jsonDecoder->decode($jsonData, Person::class);
+```
+
+### Handling private and protected properties
+The `JsonDecoder` class accepts two boolean constructor parameters to enable the handling of private and protected properties.
+
+To do so a so called `AccessProxy` will be installed and on property set the proxy will set the property to accessible, set the according value and then will set the property to not accessible again.
+
+## Documentation
+
+### Transformer Bindings
+The following `Binding` implementations are available
+
+* [FieldBinding](#fieldbinding)
+* [ArrayBinding](#arraybinding)
+* [AliasBinding](#aliasbinding)
+* [CallbackBinding](#callbackbinding)
+
+#### FieldBinding
+Defines a json field to property binding for the given type.
+
+**Signature:**
+```php
+new FieldBinding($property, $jsonField, $type);
+```
+This defines a field mapping for the property `$property` to a class instance of type `$type` with data in `$jsonField`.
 
+#### ArrayBinding
+Defines a array field binding for the given type.
+
+**Signature:**
+```php
+new ArrayBinding($property, $jsonField, $type);
+```
+This defines a field mapping for the property `$property` to an array of class instance of type `$type` with data in `$jsonField`.
+
+### AliasBinding
+Defines a json field to property binding.
+
+**Signature:**
+```php
+new AliasBinding($property, $jsonField);
+```
+
+#### CallbackBinding
+Defines a property binding that gets the callback result set as its value.
+
+**Signature:**
+```php
+new CallbackBinding($property, $callback);
 ```
 
 ## License

src/AccessProxy.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace Karriere\JsonDecoder;
+
+use ReflectionProperty;
+
+class AccessProxy
+{
+    /**
+     * @var ReflectionProperty
+     */
+    private $property;
+
+    private $instance;
+
+    public function __construct(ReflectionProperty $property, $instance)
+    {
+        $this->property = $property;
+        $this->instance = $instance;
+    }
+
+    public function __set($name, $value)
+    {
+        if ($name === $this->property->getName()) {
+            $this->property->setAccessible(true);
+            $this->property->setValue($this->instance, $value);
+            $this->property->setAccessible(false);
+        }
+    }
+}

src/Binding.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Karriere\JsonDecoder;
+
+interface Binding
+{
+    /**
+     * executes the defined binding method on the class instance
+     *
+     * @param JsonDecoder $jsonDecoder
+     * @param mixed $jsonData
+     * @param mixed $instance the class instance to bind to
+     * @return mixed
+     */
+    public function bind($jsonDecoder, $jsonData, $instance);
+
+    /**
+     * @return string the name of the property to bind
+     */
+    public function property();
+}

src/Bindings/AliasBinding.php

@@ -0,0 +1,60 @@
+<?php
+
+namespace Karriere\JsonDecoder\Bindings;
+
+use Karriere\JsonDecoder\Binding;
+use Karriere\JsonDecoder\Exceptions\JsonValueException;
+use Karriere\JsonDecoder\JsonDecoder;
+
+class AliasBinding implements Binding
+{
+    /**
+     * @var string
+     */
+    private $property;
+
+    /**
+     * @var string
+     */
+    private $jsonField;
+
+    /**
+     * AliasBinding constructor.
+     *
+     * @param string $property the property to bind to
+     * @param string $jsonField the json field
+     */
+    public function __construct($property, $jsonField)
+    {
+        $this->property = $property;
+        $this->jsonField = $jsonField;
+    }
+
+    /**
+     * executes the defined binding method on the class instance
+     *
+     * @param JsonDecoder $jsonDecoder
+     * @param mixed $jsonData
+     * @param mixed $instance the class instance to bind to
+     * @return mixed
+     * @throws JsonValueException if given json field is not available
+     */
+    public function bind($jsonDecoder, $jsonData, $instance)
+    {
+        if (!array_key_exists($this->jsonField, $jsonData)) {
+            throw new JsonValueException(
+                sprintf('the value "%s" for property "%s" does not exist', $this->jsonField, $this->property)
+            );
+        }
+
+        $instance->{$this->property} = $jsonData[$this->jsonField];
+    }
+
+    /**
+     * @return string the name of the property to bind
+     */
+    public function property()
+    {
+        return $this->property;
+    }
+}

src/Bindings/ArrayBinding.php

@@ -0,0 +1,74 @@
+<?php
+
+namespace Karriere\JsonDecoder\Bindings;
+
+use Karriere\JsonDecoder\Binding;
+use Karriere\JsonDecoder\Exceptions\JsonValueException;
+use Karriere\JsonDecoder\JsonDecoder;
+
+class ArrayBinding implements Binding
+{
+    /**
+     * @var string
+     */
+    private $property;
+
+    /**
+     * @var string
+     */
+    private $jsonField;
+
+    /**
+     * @var string
+     */
+    private $type;
+
+    /**
+     * ArrayBinding constructor.
+     *
+     * @param string $property the property to bind to
+     * @param string $jsonField the json field
+     * @param string $type the desired type of the property
+     */
+    public function __construct($property, $jsonField, $type)
+    {
+        $this->property = $property;
+        $this->jsonField = $jsonField;
+        $this->type = $type;
+    }
+
+    /**
+     * executes the defined binding method on the class instance
+     *
+     * @param JsonDecoder $jsonDecoder
+     * @param array $jsonData
+     * @param mixed $instance the class instance to bind to
+     * @return mixed
+     * @throws JsonValueException if given json field is not available
+     */
+    public function bind($jsonDecoder, $jsonData, $instance)
+    {
+        if (!array_key_exists($this->jsonField, $jsonData)) {
+            throw new JsonValueException(
+                sprintf('the value "%s" for property "%s" does not exist', $this->jsonField, $this->property)
+            );
+        }
+
+        $data = $jsonData[$this->jsonField];
+        $values = [];
+
+        foreach ($data as $item) {
+            $values[] = $jsonDecoder->decodeArray($item, $this->type);
+        }
+
+        $instance->{$this->property} = $values;
+    }
+
+    /**
+     * @return string the name of the property to bind
+     */
+    public function property()
+    {
+        return $this->property;
+    }
+}

src/Bindings/CallbackBinding.php

@@ -0,0 +1,51 @@
+<?php
+
+namespace Karriere\JsonDecoder\Bindings;
+
+use Karriere\JsonDecoder\Binding;
+use Karriere\JsonDecoder\JsonDecoder;
+
+class CallbackBinding implements Binding
+{
+    /**
+     * @var string
+     */
+    private $property;
+
+    /**
+     * @var callable
+     */
+    private $callback;
+
+    /**
+     * CallbackBinding constructor.
+     * @param string $property
+     * @param callable $callback
+     */
+    public function __construct($property, $callback)
+    {
+        $this->property = $property;
+        $this->callback = $callback;
+    }
+
+    /**
+     * executes the defined binding method on the class instance
+     *
+     * @param JsonDecoder $jsonDecoder
+     * @param mixed $jsonData
+     * @param mixed $instance the class instance to bind to
+     * @return mixed
+     */
+    public function bind($jsonDecoder, $jsonData, $instance)
+    {
+        $instance->{$this->property} = $this->callback->__invoke($jsonData);
+    }
+
+    /**
+     * @return string the name of the property to bind
+     */
+    public function property()
+    {
+        return $this->property;
+    }
+}