update register return in ProcessorRegistry

.gitignore

@@ -59,4 +59,5 @@ temp/
 tmp/
 .vscode/launch.json
 .vscode/extensions.json
-tests/lista_de_arquivos.php
+tests/lista_de_arquivos.php
+/composer.lock

src/Processor/Attribute/BaseProcessorAttribute.php

@@ -4,27 +4,79 @@
 
 namespace KaririCode\Contract\Processor\Attribute;
 
+/**
+ * Classe BaseProcessorAttribute.
+ *
+ * Classe abstrata que implementa atributos de processamento, fornecendo funcionalidades
+ * para registrar processadores e mensagens customizadas associadas a cada um. Esta classe
+ * é projetada para servir como base para a criação de atributos de processamento que
+ * suportam personalização de mensagens.
+ *
+ * @category  Processor
+ *
+ * @license   MIT
+ */
 abstract class BaseProcessorAttribute implements ProcessableAttribute, CustomizableMessageAttribute
 {
+    /**
+     * @var array Lista de processadores associados ao atributo.
+     *            Somente processadores válidos são armazenados nesta lista.
+     */
     private readonly array $processors;
+
+    /**
+     * @var array Lista de mensagens customizadas para os processadores.
+     *            As mensagens são associadas ao nome do processador e são opcionais.
+     */
     private readonly array $messages;
 
+    /**
+     * Construtor da classe BaseProcessorAttribute.
+     *
+     * Inicializa a lista de processadores e, opcionalmente, as mensagens customizadas.
+     * Os processadores inválidos (nulos ou false) são automaticamente filtrados.
+     *
+     * @param array $processors Lista de processadores a serem associados ao atributo
+     * @param array|null $messages (Opcional) Lista de mensagens customizadas associadas aos processadores
+     */
     public function __construct(array $processors, ?array $messages = null)
     {
         $this->processors = self::filterValidProcessors($processors);
         $this->messages = $messages ?? [];
     }
 
+    /**
+     * Retorna a lista de processadores associados ao atributo.
+     *
+     * @return array A lista de processadores válidos
+     */
     public function getProcessors(): array
     {
         return $this->processors;
     }
 
+    /**
+     * Obtém uma mensagem customizada para um processador específico, caso esteja definida.
+     *
+     * @param string $processorName O nome do processador para o qual a mensagem é requisitada
+     *
+     * @return string|null A mensagem customizada associada ao processador, ou null se não existir
+     */
     public function getMessage(string $processorName): ?string
     {
         return $this->messages[$processorName] ?? null;
     }
 
+    /**
+     * Filtra e retorna somente os processadores válidos.
+     *
+     * Este método estático remove processadores nulos ou definidos como false,
+     * garantindo que apenas processadores utilizáveis sejam armazenados.
+     *
+     * @param array $processors Lista de processadores a serem filtrados
+     *
+     * @return array A lista de processadores válidos
+     */
     private static function filterValidProcessors(array $processors): array
     {
         return array_filter($processors, static fn ($v) => null !== $v && false !== $v);

src/Processor/ProcessingResult.php

@@ -0,0 +1,75 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Processor;
+
+/**
+ * Interface ProcessingResult.
+ *
+ * Defines the contract for handling processing results, including errors and processed data management.
+ *
+ * @category  Processor
+ *
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ *
+ * @see       https://kariricode.org/
+ */
+interface ProcessingResult
+{
+    /**
+     * Adds an error associated with a specific property.
+     *
+     * @param string $property The property where the error occurred
+     * @param string $errorKey A unique identifier for the type of error
+     * @param string $message A human-readable error message
+     */
+    public function addError(string $property, string $errorKey, string $message): void;
+
+    /**
+     * Stores processed data for a specific property.
+     *
+     * @param string $property The property associated with the processed data
+     * @param mixed $value The processed value to be stored
+     */
+    public function setProcessedData(string $property, mixed $value): void;
+
+    /**
+     * Checks if there are any errors in the processing result.
+     *
+     * @return bool True if there are errors, false otherwise
+     */
+    public function hasErrors(): bool;
+
+    /**
+     * Retrieves all errors that occurred during processing.
+     *
+     * @return array<string, array<int, array{errorKey: string, message: string}>>
+     *                                                                             A map of property names to their associated errors
+     */
+    public function getErrors(): array;
+
+    /**
+     * Retrieves all processed data.
+     *
+     * @return array<string, mixed> A map of property names to their processed values
+     */
+    public function getProcessedData(): array;
+
+    /**
+     * Converts the processing result into an array representation.
+     *
+     * @return array{
+     *     isValid: bool,
+     *     errors: array<string, array<int, array{errorKey: string, message: string}>>,
+     *     processedData: array<string, mixed>
+     * }
+     */
+    public function toArray(): array;
+
+    /**
+     * Clears all stored errors and processed data.
+     */
+    public function clear(): void;
+}

src/Processor/ProcessorRegistry.php

@@ -15,8 +15,8 @@
  *
  * @category  ProcessorPipeline
  *
- * @author    Walmir Silva <walmir.silva@kariricode.org>
  * @license   MIT
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
  *
  * @see       https://kariricode.org/
  */
@@ -31,8 +31,10 @@ interface ProcessorRegistry
      * @param string $context The context under which the processor is registered
      * @param string $name The unique name of the processor within the context
      * @param Processor $processor The processor instance to be registered
+     *
+     * @return self Returns the current instance to enable a fluent interface
      */
-    public function register(string $context, string $name, Processor $processor): void;
+    public function register(string $context, string $name, Processor $processor): self;
 
     /**
      * Retrieves a processor by its context and name.

src/Processor/ValidatableProcessor.php

@@ -23,6 +23,16 @@
  */
 interface ValidatableProcessor extends Processor
 {
+    /**
+     * Resets the processor's state to its initial values.
+     *
+     * This method should be called before reusing the processor instance to ensure
+     * that any previous validation state is cleared and the processor is ready for
+     * new validation. This is particularly important when processors are reused
+     * across multiple validation cycles.
+     */
+    public function reset(): void;
+
     /**
      * Checks if the processor is in a valid state.
      *