Featrue/normalizers (#10)

* add validate
* add validation docs

Author: astral-data

benchmarks/SerializeBench.php

@@ -83,7 +83,7 @@ public function setupObject(): void
         Revs(500),
         Iterations(5),
         BeforeMethods([ 'setupObjectCreation']),
-        Assert('mode(variant.time.avg) < 120 microseconds +/- 5%')
+        Assert('mode(variant.time.avg) < 130 microseconds +/- 5%')
     ]
     public function benchObjectCreation(): void
     {

docs/en/SUMMARY.md

@@ -11,6 +11,7 @@
 * [Array Object Mapping](mapper/array-mapper.md)
 * [Union Type Mapping](mapper/union-mapper.md)
 * [Output Format](mapper/out.md)
+* [Validation](mapper/validate.md)
 
 ## Annotation Usage
 

docs/en/mapper/out.md

@@ -27,6 +27,7 @@ $user = User::from([
 ### Outputting the Object
 
 ```php
+
 // $user is an object by default
 echo $user->name;  // Output: Jon
 echo $user->age;   // Output: 30

docs/en/mapper/validate.md

@@ -0,0 +1,61 @@
+## Parameter Validation
+
+### Validation via the `validate` Method
+
+The `Serialize` class provides a `validate` method that is automatically called when an object is created using the `from` method. You can implement custom data validation logic within this method.
+
+Here's an example:
+
+```php
+use Astral\Serialize\Serialize;
+
+class TestConstructValidationFromSerialize extends Serialize 
+{
+    public string $type_string;
+
+    /**
+     * Data validation method
+     * Automatically called after object creation via the from method
+     */
+    public function validate(): void
+    {
+        // Validate the value of the type_string property
+        if ($this->type_string !== '123') {
+            throw new Exception('type_string must be equal to 123');
+        }
+
+        // You can also modify property values
+        $this->type_string = '234';
+    }
+}
+```
+
+### Validation in `__construct`
+
+When creating objects directly using the `__construct` method, you can implement parameter validation logic in the constructor. However, note that this approach can only access properties defined in the constructor and cannot access other properties.
+
+```php
+use Astral\Serialize\Serialize;
+
+class TestConstructFromSerialize extends Serialize
+{
+    // Note: This property cannot be accessed in the constructor
+    // If you need to validate this property, use the validate method
+    public string $not_validate_string;
+    
+    /**
+     * Parameter validation in the constructor
+     * @param string $type_string The input string parameter
+     */
+    public function __construct(
+        public string $type_string,
+    ) {
+        // Validate the input parameter
+        if ($this->type_string !== '123') {
+            throw new Exception('type_string must be equal to 123');
+        }
+
+        // Modify the property value
+        $this->type_string = '234';
+    }
+}

docs/zh/SUMMARY.md

@@ -11,6 +11,8 @@
 * [数组对象转换](mapper/array-mapper.md)
 * [联合类型转换](mapper/union-mapper.md)
 * [输出格式](mapper/out.md)
+* [参数校验](mapper/validate.md)
+
 
 ## 注解类使用
 

docs/zh/mapper/validate.md

@@ -0,0 +1,61 @@
+## 参数校验
+
+### 使用 validate 方法进行参数校验
+
+`Serialize` 类提供了一个 `validate` 方法，当通过 `from` 方法创建对象时，该方法会被自动调用。我们可以在 `validate` 方法中实现自定义的数据验证逻辑。
+
+下面是一个使用示例：
+
+```php
+use Astral\Serialize\Serialize;
+
+class TestConstructValidationFromSerialize extends Serialize 
+{
+    public string $type_string;
+
+    /**
+     * 数据验证方法
+     * 在对象通过 from 方法创建后自动调用
+     */
+    public function validate(): void
+    {
+        // 验证 type_string 属性的值
+        if ($this->type_string !== '123') {
+            throw new Exception('type_string 必须等于 123');
+        }
+
+        // 可以修改属性值
+        $this->type_string = '234';
+    }
+}
+```
+
+### 在构造函数中进行参数校验
+
+当直接使用 `__construct` 方法创建对象时，可以在构造函数中实现参数验证逻辑。但需要注意的是，这种方式只能访问构造函数中定义的属性，无法访问其他属性。
+
+```php
+use Astral\Serialize\Serialize;
+
+class TestConstructFromSerialize extends Serialize
+{
+    // 注意：这个属性在构造函数中无法访问
+    // 如果需要验证此属性，请使用 validate 方法
+    public string $not_validate_string;
+    
+    /**
+     * 构造函数中的参数验证
+     * @param string $type_string 输入的字符串参数
+     */
+    public function __construct(
+        public string $type_string,
+    ) {
+        // 验证传入的参数
+        if ($this->type_string !== '123') {
+            throw new Exception('type_string 必须等于 123');
+        }
+
+        // 修改属性值
+        $this->type_string = '234';
+    }
+}

src/Casts/InputValue/InputValueOnlyBaseTypeCast.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Astral\Serialize\Casts\InputValue;
+
+use Astral\Serialize\Contracts\Attribute\InputValueCastInterface;
+use Astral\Serialize\Enums\TypeKindEnum;
+use Astral\Serialize\Support\Collections\DataCollection;
+use Astral\Serialize\Support\Context\InputValueContext;
+
+class InputValueOnlyBaseTypeCast implements InputValueCastInterface
+{
+    public function match(mixed $value, DataCollection $collection, InputValueContext $context): bool
+    {
+        return $value !== null && $collection->isNullable() === false && count($collection->getTypes()) == 1 ;
+    }
+
+    public function resolve(mixed $value, DataCollection $collection, InputValueContext $context): mixed
+    {
+        return match ($collection->getTypes()[0]->kind) {
+            TypeKindEnum::INT     => (int)$value,
+            TypeKindEnum::FLOAT   => (float)$value,
+            TypeKindEnum::STRING  => (string)$value,
+            TypeKindEnum::BOOLEAN => (bool)$value,
+            default               => $value,
+        };
+    }
+}

src/Resolvers/InputResolver.php

@@ -26,7 +26,7 @@ public function __construct(
     /**
      * @throws ReflectionException
      */
-    public function resolve(ChooseSerializeContext $chooseContext, GroupDataCollection $groupCollection, array $payload)
+    public function resolve(ChooseSerializeContext $chooseContext, GroupDataCollection $groupCollection, array $payload): object
     {
         $reflectionClass =  $this->reflectionClassInstanceManager->get($groupCollection->getClassName());
         $object          =  $reflectionClass->newInstanceWithoutConstructor();
@@ -72,6 +72,11 @@ classInstance: $object,
             $this->inputConstructCast->resolve($groupCollection->getConstructProperties(), $object, $constructInputs);
         }
 
+        // validate execution
+        if(method_exists($object,'validate')){
+            $object->validate();
+        }
+
         return $object;
 
     }

src/Serialize.php

@@ -32,7 +32,6 @@ public function setContext(SerializeContext $context): static
 
     public static function setGroups(array|string $groups): SerializeContext
     {
-        /** @var SerializeContext<static> $serializeContext */
         $serializeContext = ContextFactory::build(static::class);
         return $serializeContext->setGroups((array)$groups);
     }
@@ -84,6 +83,11 @@ public static function faker(): static
         return $instance;
     }
 
+    public function validate(): void
+    {
+
+    }
+
     public function __debugInfo()
     {
         $res             = get_object_vars($this);

src/Support/Config/ConfigManager.php

@@ -7,6 +7,7 @@
 use Astral\Serialize\Casts\InputValue\InputObjectBestMatchChildCast;
 use Astral\Serialize\Casts\InputValue\InputValueEnumCast;
 use Astral\Serialize\Casts\InputValue\InputValueNullCast;
+use Astral\Serialize\Casts\InputValue\InputValueOnlyBaseTypeCast;
 use Astral\Serialize\Casts\Normalizer\ArrayNormalizerCast;
 use Astral\Serialize\Casts\Normalizer\DateTimeNormalizerCast;
 use Astral\Serialize\Casts\Normalizer\JsonNormalizerCast;
@@ -36,6 +37,7 @@ class ConfigManager
         InputArraySingleChildCast::class,
         InputArrayBestMatchChildCast::class,
         InputValueEnumCast::class,
+        InputValueOnlyBaseTypeCast::class,
     ];
 
     /** @var (OutValueCastInterface|string)[] $outputValueCasts */