feat: add Transformer contract and enhance composite processors

- Added `Transformer` contract in `src/Contract/Transformer.php`:
  - Defines the core interface for all transformers, ensuring consistency across implementations.

- Updated `ChainTransformer`:
  - Enhanced chaining mechanism for sequential processing of transformations.
  - Improved error handling and data validation during transformation chain execution.

- Improved `ConditionalTransformer`:
  - Added conditional checks to apply transformations based on configurable criteria.
  - Enhanced logic for validating conditions before executing transformations.

- Modified main `Transformer` class in `src/Transformer.php`:
  - Integrated `Transformer` contract to standardize transformation behavior.
  - Streamlined method signatures and added additional validation for consistent data processing.

Author: walmir-silva

src/Contract/Transformer.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Transformer;
+
+use KaririCode\Transformer\Result\TransformationResult;
+
+interface Transformer
+{
+    public function transform(mixed $object): TransformationResult;
+}

src/Processor/Composite/ChainTransformer.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Transformer\Processor\Composite;
+
+use KaririCode\Contract\Processor\ConfigurableProcessor;
+use KaririCode\Transformer\Processor\AbstractTransformerProcessor;
+
+class ChainTransformer extends AbstractTransformerProcessor implements ConfigurableProcessor
+{
+    /** @var array<AbstractTransformerProcessor> */
+    private array $transformers = [];
+
+    private bool $stopOnError = true;
+
+    public function configure(array $options): void
+    {
+        if (isset($options['transformers']) && is_array($options['transformers'])) {
+            foreach ($options['transformers'] as $transformer) {
+                if ($transformer instanceof AbstractTransformerProcessor) {
+                    $this->transformers[] = $transformer;
+                }
+            }
+        }
+
+        $this->stopOnError = $options['stopOnError'] ?? $this->stopOnError;
+    }
+
+    public function process(mixed $input): mixed
+    {
+        $result = $input;
+
+        foreach ($this->transformers as $transformer) {
+            try {
+                $result = $transformer->process($result);
+
+                if (!$transformer->isValid() && $this->stopOnError) {
+                    $this->setInvalid($transformer->getErrorKey());
+                    break;
+                }
+            } catch (\Exception $e) {
+                if ($this->stopOnError) {
+                    $this->setInvalid('transformationError');
+                    break;
+                }
+            }
+        }
+
+        return $result;
+    }
+}

src/Processor/Composite/ConditionalTransformer.php

@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Transformer\Processor\Composite;
+
+use KaririCode\Contract\Processor\ConfigurableProcessor;
+use KaririCode\Transformer\Processor\AbstractTransformerProcessor;
+
+class ConditionalTransformer extends AbstractTransformerProcessor implements ConfigurableProcessor
+{
+    private ?AbstractTransformerProcessor $transformer = null;
+    private ?callable $condition = null;
+    private mixed $defaultValue = null;
+    private bool $useDefaultOnError = true;
+
+    public function configure(array $options): void
+    {
+        if (!isset($options['transformer']) || !$options['transformer'] instanceof AbstractTransformerProcessor) {
+            throw new \InvalidArgumentException('A valid transformer must be provided');
+        }
+
+        if (!isset($options['condition']) || !is_callable($options['condition'])) {
+            throw new \InvalidArgumentException('A valid condition callback must be provided');
+        }
+
+        $this->transformer = $options['transformer'];
+        $this->condition = $options['condition'];
+        $this->defaultValue = $options['defaultValue'] ?? $this->defaultValue;
+        $this->useDefaultOnError = $options['useDefaultOnError'] ?? $this->useDefaultOnError;
+    }
+
+    public function process(mixed $input): mixed
+    {
+        if (!$this->shouldTransform($input)) {
+            return $this->defaultValue ?? $input;
+        }
+
+        try {
+            $result = $this->transformer->process($input);
+
+            if (!$this->transformer->isValid() && $this->useDefaultOnError) {
+                $this->setInvalid($this->transformer->getErrorKey());
+                return $this->defaultValue ?? $input;
+            }
+
+            return $result;
+        } catch (\Exception $e) {
+            $this->setInvalid('transformationError');
+            return $this->defaultValue ?? $input;
+        }
+    }
+
+    private function shouldTransform(mixed $input): bool
+    {
+        try {
+            return call_user_func($this->condition, $input);
+        } catch (\Exception $e) {
+            return false;
+        }
+    }
+}

src/Transformer.php

@@ -0,0 +1,96 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Transformer;
+
+use KaririCode\Contract\Processor\ProcessorRegistry;
+use KaririCode\Contract\Transformer\Transformer as TransformerContract;
+use KaririCode\ProcessorPipeline\Handler\ProcessorAttributeHandler;
+use KaririCode\ProcessorPipeline\ProcessorBuilder;
+use KaririCode\PropertyInspector\AttributeAnalyzer;
+use KaririCode\PropertyInspector\Utility\PropertyInspector;
+use KaririCode\Transformer\Attribute\Transform;
+use KaririCode\Transformer\Result\TransformationResult;
+
+final class Transformer implements TransformerContract
+{
+    private const IDENTIFIER = 'transformer';
+
+    private readonly ProcessorBuilder $builder;
+
+    public function __construct(
+        private readonly ProcessorRegistry $registry
+    ) {
+        $this->builder = new ProcessorBuilder($this->registry);
+    }
+
+    public function transform(mixed $object): TransformationResult
+    {
+        $handler = new ProcessorAttributeHandler(
+            self::IDENTIFIER,
+            $this->builder
+        );
+
+        $propertyInspector = new PropertyInspector(
+            new AttributeAnalyzer(Transform::class)
+        );
+
+        /** @var ProcessorAttributeHandler */
+        $handler = $propertyInspector->inspect($object, $handler);
+        $handler->applyChanges($object);
+
+        return new TransformationResult(
+            $handler->getProcessingResults()
+        );
+    }
+}
+
+namespace KaririCode\Transformer\Processor\Composite;
+
+use KaririCode\Contract\Processor\ConfigurableProcessor;
+use KaririCode\Transformer\Processor\AbstractTransformerProcessor;
+
+class ChainTransformer extends AbstractTransformerProcessor implements ConfigurableProcessor
+{
+    /** @var array<AbstractTransformerProcessor> */
+    private array $transformers = [];
+
+    private bool $stopOnError = true;
+
+    public function configure(array $options): void
+    {
+        if (isset($options['transformers']) && is_array($options['transformers'])) {
+            foreach ($options['transformers'] as $transformer) {
+                if ($transformer instanceof AbstractTransformerProcessor) {
+                    $this->transformers[] = $transformer;
+                }
+            }
+        }
+
+        $this->stopOnError = $options['stopOnError'] ?? $this->stopOnError;
+    }
+
+    public function process(mixed $input): mixed
+    {
+        $result = $input;
+
+        foreach ($this->transformers as $transformer) {
+            try {
+                $result = $transformer->process($result);
+
+                if (!$transformer->isValid() && $this->stopOnError) {
+                    $this->setInvalid($transformer->getErrorKey());
+                    break;
+                }
+            } catch (\Exception $e) {
+                if ($this->stopOnError) {
+                    $this->setInvalid('transformationError');
+                    break;
+                }
+            }
+        }
+
+        return $result;
+    }
+}