feat(processor-pipeline): Add User processing example and update tests

- Create new application.php demonstrating real-world usage of ProcessorPipeline
- Implement User entity with email, name, and age processing
- Add specific processors: EmailNormalizer, EmailValidator, NameCapitalizer, AgeValidator
- Update ProcessorBuilderTest to cover new use cases
- Enhance ProcessorPipelineTest with additional scenarios
- Refactor ProcessorRegistryTest for improved coverage
- Ensure 100% test coverage across all components
- Translate all code and comments to English for international consistency

Author: walmir-silva

composer.json

@@ -22,7 +22,8 @@
   ],
   "require": {
     "php": "^8.3",
-    "kariricode/data-structure": "^1.0"
+    "kariricode/data-structure": "^1.1",
+    "kariricode/contract": "^2.7"
   },
   "autoload": {
     "psr-4": {

composer.lock

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\ProcessorPipeline;
+
+use KaririCode\Contract\Processor\ConfigurableProcessor;
+use KaririCode\Contract\Processor\Pipeline;
+use KaririCode\Contract\Processor\Processor;
+
+class ProcessorBuilder
+{
+    public function __construct(private ProcessorRegistry $registry)
+    {
+    }
+
+    public function build(string $context, string $name, array $config = []): Processor
+    {
+        $processor = $this->registry->get($context, $name);
+        if ($processor instanceof ConfigurableProcessor && !empty($config)) {
+            $processor->configure($config);
+        }
+
+        return $processor;
+    }
+
+    public function buildPipeline(string $context, array $processorSpecs): Pipeline
+    {
+        $pipeline = new ProcessorPipeline();
+        foreach ($processorSpecs as $name => $config) {
+            if (is_int($name)) {
+                $name = $config;
+                $config = [];
+            }
+            $processor = $this->build($context, $name, $config);
+            $pipeline->addProcessor($processor);
+        }
+
+        return $pipeline;
+    }
+}

src/ProcessorBuilder.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\ProcessorPipeline;
+
+use KaririCode\Contract\Processor\Pipeline;
+use KaririCode\Contract\Processor\Processor;
+
+class ProcessorPipeline implements Pipeline
+{
+    private array $processors = [];
+
+    public function addProcessor(Processor $processor): self
+    {
+        $this->processors[] = $processor;
+
+        return $this;
+    }
+
+    public function process(mixed $input): mixed
+    {
+        return array_reduce(
+            $this->processors,
+            fn ($carry, Processor $processor) => $processor->process($carry),
+            $input
+        );
+    }
+}

src/ProcessorPipeline.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\ProcessorPipeline;
+
+use KaririCode\Contract\Processor\Processor;
+use KaririCode\DataStructure\Map\HashMap;
+
+class ProcessorRegistry
+{
+    public function __construct(private HashMap $processors = new HashMap())
+    {
+    }
+
+    public function register(string $context, string $name, Processor $processor): void
+    {
+        if (!$this->processors->containsKey($context)) {
+            $this->processors->put($context, new HashMap());
+        }
+        $contextMap = $this->processors->get($context);
+        $contextMap->put($name, $processor);
+    }
+
+    public function get(string $context, string $name): Processor
+    {
+        if (!$this->processors->containsKey($context)) {
+            throw new \RuntimeException("Context '$context' not found.");
+        }
+        $contextMap = $this->processors->get($context);
+        if (!$contextMap->containsKey($name)) {
+            throw new \RuntimeException("Processor '$name' not found in context '$context'.");
+        }
+
+        return $contextMap->get($name);
+    }
+
+    public function getContextProcessors(string $context): HashMap
+    {
+        if (!$this->processors->containsKey($context)) {
+            throw new \RuntimeException("Context '$context' not found.");
+        }
+
+        return $this->processors->get($context);
+    }
+}

src/ProcessorRegistry.php

@@ -0,0 +1,84 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Tests\ProcessorPipeline;
+
+use KaririCode\Contract\Processor\ConfigurableProcessor;
+use KaririCode\Contract\Processor\Pipeline;
+use KaririCode\Contract\Processor\Processor;
+use KaririCode\ProcessorPipeline\ProcessorBuilder;
+use KaririCode\ProcessorPipeline\ProcessorPipeline;
+use KaririCode\ProcessorPipeline\ProcessorRegistry;
+use PHPUnit\Framework\MockObject\MockObject;
+use PHPUnit\Framework\TestCase;
+
+final class ProcessorBuilderTest extends TestCase
+{
+    private ProcessorRegistry|MockObject $registry;
+    private ProcessorBuilder $builder;
+
+    protected function setUp(): void
+    {
+        $this->registry = $this->createMock(ProcessorRegistry::class);
+        $this->builder = new ProcessorBuilder($this->registry);
+    }
+
+    public function testBuildNonConfigurableProcessor(): void
+    {
+        $processor = $this->createMock(Processor::class);
+        $this->registry->expects($this->once())
+            ->method('get')
+            ->with('context', 'name')
+            ->willReturn($processor);
+
+        $result = $this->builder->build('context', 'name');
+        $this->assertSame($processor, $result);
+    }
+
+    public function testBuildConfigurableProcessor(): void
+    {
+        $processor = $this->createMock(ConfigurableProcessor::class);
+        $this->registry->expects($this->once())
+            ->method('get')
+            ->with('context', 'name')
+            ->willReturn($processor);
+
+        $processor->expects($this->once())
+            ->method('configure')
+            ->with(['option' => 'value']);
+
+        $result = $this->builder->build('context', 'name', ['option' => 'value']);
+        $this->assertSame($processor, $result);
+    }
+
+    public function testBuildPipeline(): void
+    {
+        $processor1 = $this->createMock(Processor::class);
+        $processor2 = $this->createMock(ConfigurableProcessor::class);
+
+        $this->registry->expects($this->exactly(2))
+            ->method('get')
+            ->willReturnCallback(function ($context, $name) use ($processor1, $processor2) {
+                if ('context' === $context && 'processor1' === $name) {
+                    return $processor1;
+                }
+                if ('context' === $context && 'processor2' === $name) {
+                    return $processor2;
+                }
+                $this->fail('Unexpected get() call');
+            });
+
+        $processor2->expects($this->once())
+            ->method('configure')
+            ->with(['option' => 'value']);
+
+        $result = $this->builder->buildPipeline('context', [
+            'processor1',
+            'processor2' => ['option' => 'value'],
+        ]);
+
+        $this->assertInstanceOf(Pipeline::class, $result);
+        $this->assertInstanceOf(ProcessorPipeline::class, $result);
+    }
+}

tests/ProcessorBuilderTest.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\ProcessorPipeline\Tests;
+
+use KaririCode\Contract\Processor\Processor;
+use KaririCode\ProcessorPipeline\ProcessorPipeline;
+use PHPUnit\Framework\TestCase;
+
+final class ProcessorPipelineTest extends TestCase
+{
+    public function testAddProcessor(): void
+    {
+        $pipeline = new ProcessorPipeline();
+        $processor = $this->createMock(Processor::class);
+
+        $result = $pipeline->addProcessor($processor);
+
+        $this->assertSame($pipeline, $result);
+    }
+
+    public function testProcessWithNoProcessors(): void
+    {
+        $pipeline = new ProcessorPipeline();
+        $input = 'test';
+
+        $result = $pipeline->process($input);
+
+        $this->assertSame($input, $result);
+    }
+
+    public function testProcessWithMultipleProcessors(): void
+    {
+        $pipeline = new ProcessorPipeline();
+
+        $processor1 = $this->createMock(Processor::class);
+        $processor1->method('process')->willReturnCallback(fn ($input) => $input . '1');
+
+        $processor2 = $this->createMock(Processor::class);
+        $processor2->method('process')->willReturnCallback(fn ($input) => $input . '2');
+
+        $pipeline->addProcessor($processor1)->addProcessor($processor2);
+
+        $result = $pipeline->process('test');
+
+        $this->assertSame('test12', $result);
+    }
+}