feat: add validator cloning

Author: lemmon

AGENTS.md

@@ -82,6 +82,7 @@ A comprehensive, fluent validation library for PHP inspired by Valibot and Zod.
 - **Task Tracking** - Use GitHub-style checkboxes (`- [ ]` for pending, `- [x]` for completed) in ROADMAP.md for clear progress tracking
 - **Commit Standards** - Follow Conventional Commits spec (e.g., `fix:`, `refactor:`, `docs:`)
 - **Commit Scope** - Each commit should address a single concern; tests and implementation can ship together, but unrelated formatting belongs elsewhere
+- **Git Tags** - Prefer annotated tags for releases (author, date, message/signing) over lightweight tags
 
 ### Development Tools
 - **Debugging** - `symfony/var-dumper` integration

CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.9.0] - 2025-11-18
+
+### Added
+- **Validator cloning**: Added `clone()` support to all validators for safe reuse of prebuilt pipelines without shared state. Pipelines are rebound to the cloned instance and nested schemas/item validators deep-clone to avoid cross-contamination between validators.
+
 ## [0.8.0] - 2025-11-06
 ### Changed
 - Migrated all runtime classes to the `Lemmon\Validator` namespace and aligned documentation/examples with the new structure.

ROADMAP.md

@@ -61,7 +61,10 @@ This roadmap outlines the strategic development plan for future releases, priori
   - Ensured all internal navigation works properly
 
 ### Critical API Improvements
-- [ ] **Create `clone()` function** - Provide a first-class way to duplicate validator pipelines for reuse without rebuilding chains manually
+- [x] **Create `clone()` function** - Provide a first-class way to duplicate validator pipelines for reuse without rebuilding chains manually
+  - Added deep clone support with pipeline closure rebinding to cloned instances
+  - Nested schemas/item validators now clone recursively to prevent shared state
+  - Added regression tests covering pipeline state isolation and schema deep copying
 - [x] **Rename `addValidation()` to `satisfies()`** - Intuitive, descriptive method name that clearly indicates validation intent
   - Added new `satisfies(callable $validation, ?string $message = null)` method with optional error message
   - Maintains backward compatibility with deprecated `addValidation()` method

docs/api-reference/validator-factory.md

@@ -214,6 +214,24 @@ $email2 = $emailValidator->validate('user2@example.com');
 $email3 = $emailValidator->validate('user3@example.com');
 ```
 
+### Cloning Validators for Variations
+
+Use `clone()` to fork a base pipeline without sharing state:
+
+```php
+$baseEmail = Validator::isString()
+    ->email()
+    ->pipe('trim', 'strtolower');
+
+$requiredEmail = $baseEmail->clone()->required();
+$nullableEmail = $baseEmail->clone()->default(null);
+
+$requiredEmail->validate('USER@EXAMPLE.COM'); // 'user@example.com'
+$nullableEmail->validate(null);               // null (default applied)
+```
+
+`clone()` performs a deep copy, including nested schemas/item validators, so modifications on the clone never leak back to the original.
+
 ### Complex Schema Validation
 
 ```php

src/Lemmon/Validator/ArrayValidator.php

@@ -102,4 +102,13 @@ protected function validateType(mixed $value, string $key): mixed
 
         return $value;
     }
+
+    public function __clone()
+    {
+        parent::__clone();
+
+        if ($this->itemValidator !== null) {
+            $this->itemValidator = $this->itemValidator->clone();
+        }
+    }
 }

src/Lemmon/Validator/AssociativeValidator.php

@@ -88,4 +88,13 @@ protected function validateType(mixed $value, string $key): mixed
 
         return $data;
     }
+
+    public function __clone()
+    {
+        parent::__clone();
+
+        foreach ($this->schema as $fieldKey => $validator) {
+            $this->schema[$fieldKey] = $validator->clone();
+        }
+    }
 }

src/Lemmon/Validator/FieldValidator.php

@@ -10,6 +10,16 @@ abstract class FieldValidator
     protected bool $required = false;
     protected ?string $requiredMessage = null;
 
+    /**
+     * Creates a deep copy of the validator, including pipeline closures bound to the clone.
+     *
+     * @return static
+     */
+    public function clone(): static
+    {
+        return clone $this;
+    }
+
     /**
      * @var array<array{type: PipelineType, operation: callable}>
      */
@@ -453,4 +463,22 @@ protected function coerceToAssociativeArray(mixed $value): mixed
         }
         return $value; // Preserve keys - no reindexing!
     }
+
+    public function __clone()
+    {
+        $rebuiltPipeline = [];
+        foreach ($this->pipeline as $step) {
+            $operation = $step['operation'];
+            if ($operation instanceof \Closure) {
+                $operation = $operation->bindTo($this);
+            }
+
+            $rebuiltPipeline[] = [
+                'type' => $step['type'],
+                'operation' => $operation,
+            ];
+        }
+
+        $this->pipeline = $rebuiltPipeline;
+    }
 }

src/Lemmon/Validator/ObjectValidator.php

@@ -88,4 +88,13 @@ protected function validateType(mixed $value, string $key): mixed
 
         return $data;
     }
+
+    public function __clone()
+    {
+        parent::__clone();
+
+        foreach ($this->schema as $fieldKey => $validator) {
+            $this->schema[$fieldKey] = $validator->clone();
+        }
+    }
 }

tests/FieldValidatorTest.php

@@ -193,6 +193,46 @@
     expect($errors)->toBe(['Value must be a string']);
 });
 
+it('should clone validators without sharing pipeline state', function () {
+    $original = Validator::isString()
+        ->transform(fn ($v) => explode(',', trim($v))) // String → Array
+        ->pipe('array_reverse')                        // Array operations use current type
+        ->transform(fn ($v) => implode('-', $v));      // Array → String
+
+    $clone = $original->clone();
+
+    $result = $clone->validate('a,b,c');
+    expect($result)->toBe('c-b-a');
+
+    $currentType = new ReflectionProperty($original, 'currentType');
+    $currentType->setAccessible(true);
+
+    expect($currentType->getValue($original))->toBeNull(); // Original instance untouched
+});
+
+it('should deep clone nested schemas for associative validators', function () {
+    $original = Validator::isAssociative([
+        'nickname' => Validator::isString(),
+    ]);
+
+    $clone = $original->clone();
+
+    $schemaProperty = new ReflectionProperty($clone, 'schema');
+    $schemaProperty->setAccessible(true);
+    $cloneSchema = $schemaProperty->getValue($clone);
+
+    $cloneSchema['nickname']->default('buddy');
+
+    $originalSchemaProperty = new ReflectionProperty($original, 'schema');
+    $originalSchemaProperty->setAccessible(true);
+    $originalSchema = $originalSchemaProperty->getValue($original);
+
+    expect($cloneSchema['nickname'])->not->toBe($originalSchema['nickname']); // No shared instances
+
+    expect($original->validate([]))->toBe([]);
+    expect($clone->validate([]))->toBe(['nickname' => 'buddy']);
+});
+
 it('should fail fast in single pipeline - first validation error stops execution', function () {
     $validator = Validator::isString()->minLength(10)->maxLength(3)->email();