Add DateTimeBinding

fixes #30

Author: fetzi

CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.1.0] - 2020-04-10
+### Added
+- `DateTimeBinding` for parsing date string
+
 ## [3.0.0] - 2020-03-25
 ### Changed
 - Update dependencies to be compatible with PHP 7.4

readme.md

@@ -103,6 +103,7 @@ The following `Binding` implementations are available
 * [FieldBinding](#fieldbinding)
 * [ArrayBinding](#arraybinding)
 * [AliasBinding](#aliasbinding)
+* [DateTimeBinding](#datetimebinding)
 * [CallbackBinding](#callbackbinding)
 
 #### FieldBinding
@@ -131,6 +132,14 @@ Defines a JSON field to property binding.
 new AliasBinding($property, $jsonField);
 ```
 
+#### DateTimeBinding
+Defines a JSON field to property binding and converts the given string to a `DateTime` instance.
+
+**Signature:**
+```php
+new new DateTimeBinding($property, $jsonField, $isRequired = false, $dateTimeFormat = DateTime::ATOM);
+```
+
 #### CallbackBinding
 Defines a property binding that gets the callback result set as its value.
 

src/Bindings/DateTimeBinding.php

@@ -0,0 +1,55 @@
+<?php
+
+namespace Karriere\JsonDecoder\Bindings;
+
+use DateTime;
+use Karriere\JsonDecoder\Binding;
+
+class DateTimeBinding extends Binding
+{
+    /**
+     * @var string
+     */
+    private $format;
+
+    /**
+     * DateTimeBinding constructor.
+     *
+     * @param string $property          the property to bind to
+     * @param string $jsonField         the json field
+     * @param bool   $isRequired        defines if the field value is required during decoding
+     * @param string $dateTimeFormat    defines the date format used for parsing, defaults to DateTime::ATOM
+     */
+    public function __construct($property, $jsonField, $isRequired = false, $dateTimeFormat = DateTime::ATOM)
+    {
+        parent::__construct($property, $jsonField, null, $isRequired);
+
+        $this->format = $dateTimeFormat;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function validate($jsonData): bool
+    {
+        if (array_key_exists($this->jsonField, $jsonData)) {
+            return DateTime::createFromFormat($this->format, $jsonData[$this->jsonField]) !== false;
+        }
+
+        return !$this->isRequired;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function bind($jsonDecoder, $jsonData, $propertyAccessor)
+    {
+        if (array_key_exists($this->jsonField, $jsonData)) {
+            $dateTimeObject = DateTime::createFromFormat($this->format, $jsonData[$this->jsonField]);
+
+            if ($dateTimeObject !== false) {
+                $propertyAccessor->set($dateTimeObject);
+            }
+        }
+    }
+}

src/ClassBindings.php

@@ -64,7 +64,7 @@ public function decode($data, $instance)
 
                 if (!$binding->validate($data)) {
                     throw new JsonValueException(
-                        sprintf('Unable to bind required property "%s" because JSON data is missing', $propertyName)
+                        sprintf('Unable to bind required property "%s" because JSON data is missing or invalid', $propertyName)
                     );
                 }
 

tests/specs/Bindings/DateTimeBindingSpec.php

@@ -0,0 +1,66 @@
+<?php
+
+namespace tests\specs\Karriere\JsonDecoder\Bindings;
+
+use DateTime;
+use Karriere\JsonDecoder\Bindings\DateTimeBinding;
+use Karriere\JsonDecoder\JsonDecoder;
+use Karriere\JsonDecoder\PropertyAccessor;
+use PhpSpec\ObjectBehavior;
+use Prophecy\Argument;
+
+class DateTimeBindingSpec extends ObjectBehavior
+{
+    public function let()
+    {
+        $this->beConstructedWith('property', 'field');
+    }
+
+    public function it_is_initializable()
+    {
+        $this->shouldHaveType(DateTimeBinding::class);
+    }
+
+    public function it_should_return_the_property_name()
+    {
+        $this->property()->shouldReturn('property');
+    }
+
+    public function it_should_succeed_on_binding_validation()
+    {
+        $this->validate(['field' => '2018-02-01T12:00:00+00:00'])->shouldReturn(true);
+    }
+
+    public function it_should_fail_on_binding_validation_for_a_required_property_with_invalid_format()
+    {
+        $this->beConstructedWith('property', 'field', true);
+        $this->validate(['field' => 'value'])->shouldReturn(false);
+    }
+
+    public function it_should_fail_on_binding_validation_for_a_not_required_property_with_invalid_format()
+    {
+        $this->validate(['field' => 'value'])->shouldReturn(false);
+    }
+
+    public function it_should_be_able_to_parse_an_atom_datetime(JsonDecoder $jsonDecoder, PropertyAccessor $propertyAccessor)
+    {
+        $expectedDateTime = DateTime::createFromFormat(DateTime::ATOM, '2020-01-01T12:00:00+00:00');
+        $propertyAccessor->set($expectedDateTime)->shouldBeCalled();
+
+        $this->bind($jsonDecoder, ['field' => '2020-01-01T12:00:00+00:00'], $propertyAccessor);
+    }
+
+    public function it_should_not_set_a_value_for_an_empty_datetime_string(JsonDecoder $jsonDecoder, PropertyAccessor $propertyAccessor)
+    {
+        $propertyAccessor->set(Argument::any())->shouldNotBeCalled();
+
+        $this->bind($jsonDecoder, ['field' => ''], $propertyAccessor);
+    }
+
+    public function it_should_not_set_a_value_for_an_invalid_formatted_datetime_string(JsonDecoder $jsonDecoder, PropertyAccessor $propertyAccessor)
+    {
+        $propertyAccessor->set(Argument::any())->shouldNotBeCalled();
+
+        $this->bind($jsonDecoder, ['field' => 'invalid'], $propertyAccessor);
+    }
+}